Skip to content

Reference

Runbook YAML schema.

A runbook is a YAML file that tells briar what to extract for a company, how often, and where to save it. It can also hold the settings agents use: where they may post, which MCP servers they get, and the name on their commits. This page builds a runbook one step at a time, then lists every key.

On this page

The shape of a runbook

A runbook has a list of companies. Each company has its own settings. Here are all the keys a company can have:

version: 1 # optional, always 1
companies: # one or more companies
acme: # the company key
knowledge: ... # where results are saved
extract: ... # extractors that run once a day
schedules: ... # named groups of extractors, each with a timer
messages: ... # channels agents may post to
mcp: ... # MCP servers agents may use
git_identity: ... # name and email on agent commits
profile: ... # free text label
workspace_id: ... # free text label
knowledge_file: ... # old way to name the output file
KeysRead by
knowledge, extract, schedules, knowledge_filebriar runbook extract, sweep and serve.
messages, mcp, git_identitybriar agent implement, agent prfix and plan run, when you pass --runbook.
profile, workspace_idNothing today. They are labels for you.

The company key matters. It is the name you pass as --company acme. It also picks the env vars briar reads for that company, like JIRA_ACME_TOKEN.

Step 1: the smallest useful file

One company, one extractor, no timer:

runbooks/acme.yaml
version: 1
companies:
acme:
extract:
- name: codebase-conventions
args:
repo: [acme-co/acme-app]
  • companies.acme is the company.
  • extract is a list of extractors to run. Each one has a name and optional args.
  • codebase-conventions reads the repo and writes how the code is built, tested and linted.
$ briar runbook extract runbooks/acme.yaml

You get the file ./knowledge/acme.md. With runbook serve, this list runs once a day at 03:17 UTC as a job named extractors.

Step 2: say where to save

Agents look for a company's knowledge under names that start with knowledge:acme. The default file from step 1 does not have that name, so agents do not find it. Add a knowledge block:

version: 1
companies:
acme:
knowledge:
store: file
name: knowledge:acme
extract:
- name: codebase-conventions
args:
repo: [acme-co/acme-app]

Now the result goes to ./knowledge/knowledge/acme.md. briar agent and scaffold --company acme both find it. Use store: postgres to save in a database instead. See knowledge for all options.

Which sections reach the coding agent

An agent puts only some extractors' sections in its prompt. agent implement uses codebase-conventions, code-hotspots, reviewer-profile, active-work, pr-archaeology and meeting-digest. agent prfix uses the same list without pr-archaeology. Other extractors, like aws-infra or ci-health, are saved for you to read (for example with briar context get), but the coding agent does not see them.

Step 3: add timers with schedules

A schedule is a named group of extractors with its own timer. Use schedules when some data must be fresh every hour and some only once a night.

version: 1
companies:
acme:
knowledge:
store: file
name: knowledge:acme
schedules:
- task: extractors
every: "day at 03:17"
extract:
- name: codebase-conventions
args:
repo: [acme-co/acme-app]
- name: pr-archaeology
args:
repo: [acme-co/acme-app]
- task: tickets
every: "hour"
extract:
- name: active-tickets
args:
tracker: jira
ticket_project: [ACME]
  • task is the job name. You use it with --task.
  • every is the timer. See timer strings.
  • Each job saves its own blob. The job named extractors writes to knowledge:acme. Any other job adds its name: knowledge:acme.tickets. Agents look in all of them for the sections they use.
# Run the hourly job now, without waiting.
$ briar runbook extract runbooks/acme.yaml --task tickets

You get a fresh knowledge:acme.tickets blob.

Step 4: tune each extractor with args

args holds the settings for one extractor. The keys are the briar extract flag names with _ instead of -. A flag you can repeat becomes a YAML list.

version: 1
companies:
acme:
knowledge:
store: file
name: knowledge:acme
schedules:
- task: extractors
every: "day at 03:17"
extract:
- name: code-hotspots
args:
repo: [acme-co/acme-app, acme-co/acme-shared]
since_days: 60
top_n: 15
- name: reviewer-profile
args:
repo: [acme-co/acme-app]
reviewer_top_n: 3
- name: aws-infra
args:
cloud: aws
aws_extract_region: us-east-1
aws_extract_service: [ecs, rds, lambda]
  • repo, since_days and top_n are shared keys. Every extractor that has that idea uses them.
  • reviewer_top_n is the extractor's own key. An own key wins over the shared one.
  • aws_extract_* keys have no shared version. Use them as they are.

The full list of keys for each extractor is in Every args key, per extractor.

Step 5: filter by person

Four shared keys keep or drop items by who wrote them or who they are assigned to. They take a list of user names.

version: 1
companies:
acme:
knowledge:
store: file
name: knowledge:acme
schedules:
- task: prfix
every: "hour"
extract:
- name: pr-archaeology
args:
repo: [acme-co/acme-app]
authors_block: ["renovate[bot]", "dependabot[bot]"]
- name: active-work
args:
repo: [acme-co/acme-app]
authors_allow: [alice, bob]
assignees_block: [carol]
KeyKeeps
authors_allowOnly items written by someone in the list.
authors_blockEverything except items written by someone in the list.
assignees_allowOnly items assigned to someone in the list.
assignees_blockEverything except items assigned to someone in the list.
  • Only pr-archaeology and active-work read these four keys. Other extractors ignore them.
  • An item must pass the allow list and must not be in the block list. Block wins.
  • Put names like renovate[bot] in quotes. Without quotes, YAML reads the brackets as a list.
  • meeting-digest has its own filter, meeting_attendee_allow (a list of email addresses). See the meeting example.

Step 6: let agents post (messages)

The messages block gives an agent named channels to post to. Each channel has a name you pick and a kind. With this block, the agent gets a send_message tool. Without it, the agent has no channel tool.

version: 1
companies:
acme:
knowledge:
store: file
name: knowledge:acme
extract:
- name: active-work
args:
repo: [acme-co/acme-app]
messages:
ticket_comment:
kind: jira-comment
pr_reply:
kind: github-pr-comment
ops_chat:
kind: slack-channel
# The agent can now post to ticket_comment, pr_reply and ops_chat.
$ briar agent implement --ticket-key ACME-42 --runbook runbooks/acme.yaml

You get an agent run whose tool list includes send_message with those three channels. briar adds [AI] to the start of every message, so readers know a bot wrote it.

Messages are not alerts

messages is only for agents run with --runbook. To get told when a runbook job fails, set BRIAR_NOTIFY_SINKS instead. See failure alerts.

Step 7: give agents MCP servers

MCP (Model Context Protocol) servers are extra tool servers. The agent connects to each one, lists its tools, and can call them. Each tool shows up as mcp__github__search_issues (server name, then tool name).

version: 1
companies:
acme:
knowledge:
store: file
name: knowledge:acme
mcp:
github:
command: docker
args: ["run", "-i", "--rm", "-e", "GITHUB_TOKEN", "ghcr.io/github/github-mcp-server"]
env:
GITHUB_TOKEN: GITHUB_TOKEN
tools: [search_issues, get_pull_request]
purpose: "GitHub issues, pull requests and review threads"
  • You need the MCP extra: pip install "briar-cli[mcp]". Without it, an agent run with this block stops and tells you to install it.
  • env values are env var names, not secrets. Here briar copies its own GITHUB_TOKEN into the server.
  • Two servers are always added when the MCP extra is installed: think and time. Without the extra, briar skips them with one warning. Turn them off with --no-default-mcp on the agent command or BRIAR_NO_DEFAULT_MCP=1.

Step 8: set the commit name (git_identity)

Agents commit with a git name and email. Put them in the runbook so every machine uses the same ones.

version: 1
companies:
acme:
knowledge:
store: file
name: knowledge:acme
git_identity:
name: acme-briar-bot

The agent picks each value on its own, in this order: --git-user-name / --git-user-email, then this block (with --runbook), then your local git config (not in CI). If none gives a value, the agent stops with an error.

Everything in one file

A complete runbook with every block filled in. Copy it, then delete what you do not need.

runbooks/acme.yaml
version: 1
companies:
acme:
profile: production
knowledge:
store: postgres
name: knowledge:acme
config:
dsn_env: BRIAR_ACME_DATABASE_URL
inventory: "true"
git_identity:
name: acme-briar-bot
messages:
ticket_comment:
kind: jira-comment
ticket_done:
kind: jira-transition
config:
status: "In Review"
pr_reply:
kind: github-pr-comment
ops_chat:
kind: slack-channel
escalation:
kind: telegram-chat
config:
chat_env: TELEGRAM_ACME_ONCALL_CHAT_ID
mcp:
github:
transport: stdio
command: docker
args: ["run", "-i", "--rm", "-e", "GITHUB_TOKEN", "ghcr.io/github/github-mcp-server"]
env:
GITHUB_TOKEN: GITHUB_TOKEN
tools: [search_issues, get_pull_request]
purpose: "GitHub issues, pull requests and review threads"
sentry:
transport: http
url: https://mcp.sentry.dev/mcp
headers:
Authorization: SENTRY_MCP_BEARER
archetypes: [engineer]
purpose: "Production errors, stack traces and regressions"
enabled: false
schedules:
- task: extractors
every: "day at 03:17"
extract:
- name: pr-archaeology
args:
repo: [acme-co/acme-app, acme-co/acme-shared]
max: 100
authors_block: ["renovate[bot]", "dependabot[bot]"]
- name: codebase-conventions
args:
repo: [acme-co/acme-app]
- name: aws-infra
args:
cloud: aws
aws_extract_region: us-east-1
aws_extract_service: [ecs, rds, lambda]
- task: tickets
every: "hour"
extract:
- name: active-tickets
args:
tracker: jira
ticket_project: [ACME]
- task: meetings
every: "4 hours"
extract:
- name: meeting-digest
args:
meeting: fireflies
since_days: 7

Top-level keys

version integerdefault: 1
The file format version. Only 1 exists. You may leave it out.
companies map: company key → companyrequired
One or more companies. The key (acme) is the company name used by --company and in env var names. An empty map is an error.
version: 1
companies:
acme:
extract:
- name: active-work
args:
repo: [acme-co/acme-app]

Any other top-level key is an error. A file can hold many companies, but one company per file is easier to run. See the multi-company example.

Company keys

Every key under a company is optional.

knowledge mapdefault: file store, knowledge:<company>
Where results are saved. See knowledge.
extract list of extract entriesdefault: []
Extractors that run as one job named extractors, timer "day at 03:17". If a schedule is already named extractors, this list is ignored. See extract entry.
schedules list of schedulesdefault: []
Named jobs, each with a timer. See schedule.
messages map: channel name → message bindingdefault: {}
Channels an agent may post to. See messages.
mcp map: server name → MCP serverdefault: {}
MCP servers an agent may use. See mcp.
git_identity mapdefault: not set
Name and email on agent commits. See git_identity.
profile stringdefault: ""
A free text label, like production. briar does not use it.
workspace_id stringdefault: ""
A free text label. briar does not use it.
knowledge_file stringdefault: ""
Old way to name the output. Used only when knowledge.name is empty, and always with the file store. Prefer knowledge.
version: 1
companies:
acme:
profile: production
workspace_id: acme-eng
knowledge:
store: file
name: knowledge:acme
extract:
- name: active-work
args:
repo: [acme-co/acme-app]

Typos at this level are ignored

briar ignores unknown keys under a company, so old files still load. The downside: a typo like schedule: (no s) or knowlege: is dropped without an error. If a job does not run, check the spelling first. Keys inside knowledge and git_identity work the same way. All other blocks reject unknown keys.

Extract entry

One item in an extract list. It is used both under a company and under a schedule.

name extractor namerequired
Which extractor to run. It must be one of the 23 extractors, or the file fails to load. The list is in Every args key and on briar extract.
args mapdefault: {} (the extractor's defaults)
Settings for this extractor. Keys are briar extract flag names with _ for -. See Every args key.
version: 1
companies:
acme:
extract:
- name: stale-prs
args:
repo: [acme-co/acme-app]
stale_days: 7

Any other key next to name and args is an error. Keys inside args are not checked, so a typo there is ignored.

Schedule

One item in the schedules list.

task stringrequired
The job name. runbook extract --task uses it. It also names the saved blob: a job named weekly writes knowledge:acme.weekly. Only the name extractors writes to the plain name.
every stringrequired
The timer, like "hour" or "monday at 06:00". Only runbook serve reads it. See timer strings.
extract list of extract entriesdefault: []
The extractors this job runs, in order. Their results go into one blob.
version: 1
companies:
acme:
knowledge:
store: file
name: knowledge:acme
schedules:
- task: weekly
every: "monday at 06:00"
extract:
- name: ticket-archaeology
args:
tracker: jira
ticket_archaeology_project: [ACME]
ticket_max: 200

Knowledge

Where a company's results are saved.

store stringdefault: file
filepostgres
file saves markdown files on disk. postgres saves rows in a database, which is better when a scheduler and other machines share the data.
name stringdefault: "" (see below)
The blob name. Use knowledge:<company> so agents find it. If empty, briar uses knowledge_file, or else knowledge:<company> (since 1.1.86; before, ./knowledge/<company>.md, which agents never read), and in both cases it uses the file store, whatever store says.
root stringdefault: ./knowledge
The folder for the file store. Agents must use the same folder (their --root option). Postgres ignores it.
config map of stringsdefault: {}
Extra store settings. Values must be strings, so quote "true". Two keys exist:
  • dsn_env: for Postgres, the name of the env var that holds the database URL. Never the URL itself.
  • inventory: set to "true" to also save a JSON file with the full raw data (see below).
version: 1
companies:
acme:
knowledge:
store: postgres
name: knowledge:acme
config:
dsn_env: BRIAR_ACME_KB_PG
inventory: "true"
extract:
- name: aws-infra
args:
aws_extract_service: [tagging-inventory]

Where a file-store name ends up

nameFile
knowledge:acme./knowledge/knowledge/acme.md (inside root)
knowledge:acme, job tickets./knowledge/knowledge/acme.tickets.md
acme-notes (no colon)./knowledge/acme-notes.md
./knowledge/acme.md (has / or .md)That exact path. root is not used. Agents do not find it.

config.inventory: the full data, on demand

The markdown blob is a short summary. With inventory: "true", each job also saves a JSON blob with all the data the extractors found, for example every tagged AWS resource from tagging-inventory. Its name is inventory:acme for knowledge:acme. It is only rewritten when the data changes, so the Postgres history shows what changed and when. List it with briar context list --prefix inventory:. Agents do not read it. It is off by default.

Which database Postgres uses

briar tries these in order and uses the first one that is set:
  1. The env var named in config.dsn_env.
  2. BRIAR_ACME_DATABASE_URL (company name in upper case, - becomes _).
  3. BRIAR_DATABASE_URL.
So two companies on one machine can use two different databases.

Messages

Each key under messages is a channel name you pick, like ticket_comment. The agent uses that name when it calls send_message.

kind stringrequired
jira-commentjira-transitiongithub-pr-commentbitbucket-pr-commentslack-channeltelegram-chat
Where the message goes. An unknown kind is an error.
config mapdefault: {}
Settings for this channel. Each kind reads its own keys. See message kinds.
version: 1
companies:
acme:
messages:
ticket_done:
kind: jira-transition
config:
status: "Done"
ops_chat:
kind: slack-channel
config:
webhook_env: SLACK_ACME_OPS_WEBHOOK_URL

git_identity

name stringdefault: ""
The git config user.name for agent commits. Example: acme-briar-bot.
email stringdefault: ""
The git config user.email for agent commits. Example: [email protected].

Command-line flags win

--git-user-name and --git-user-email on the agent command win over this block. Each value is chosen on its own, so you can set name here and pass only the email on the command line.

mcp

Each key under mcp is a server name you pick. It becomes part of each tool name: mcp__<server>__<tool>. A server that fails to connect is skipped and the agent keeps going.

transport stringdefault: stdio
stdiohttp
stdio starts the server as a local program. http talks to a server over the network (Streamable HTTP).
command stringdefault: ""
The program to start. Needed for stdio. Example: docker or uvx.
args list of stringsdefault: []
Arguments for command.
env mapdefault: {}
Env vars to give the program. Each value is the name of an env var in briar's own environment, never the secret. An unset name is left out with a warning.
url stringdefault: ""
The server address. Needed for http.
headers mapdefault: {}
HTTP headers to send. Each value is the name of an env var that holds the full header value (for example Bearer abc123).
tools list of stringsdefault: [] (all tools)
Only these tools are given to the agent. Leave it out to give all.
enabled true or falsedefault: true
false skips the server but keeps its block in the file.
archetypes list of stringsdefault: [] (every agent type)
Only these agent types get the server, for example engineer (used by agent implement) or pr-fixer (used by agent prfix).
purpose stringdefault: ""
A short note on what the server is good for. The agent sees it next to each tool. When two or more of your servers apply, a short model call reads these notes and picks which servers to connect. If that call fails, all of them connect.
version: 1
companies:
acme:
mcp:
aws:
transport: stdio
command: uvx
args: ["awslabs.aws-api-mcp-server@latest"]
env:
AWS_ACCESS_KEY_ID: AWS_ACME_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY: AWS_ACME_SECRET_ACCESS_KEY
AWS_REGION: AWS_ACME_REGION
READ_OPERATIONS_ONLY: READ_OPERATIONS_ONLY
tools: [call_aws, suggest_aws_commands]
purpose: "Live AWS account state: ECS, RDS, Lambda, logs"
sentry:
transport: http
url: https://mcp.sentry.dev/mcp
headers:
Authorization: SENTRY_MCP_BEARER
archetypes: [engineer]
  • A stdio server with no command, or an http server with no url, is an error when the file loads.
  • The built-in think server needs npx and time needs uvx. Use a server name of think or time in your file to replace one.
  • MCP tools are not limited to the agent's work folder. Keep tools short, and give servers read-only credentials where you can.

Credentials: never in the file

A runbook has no block for passwords or tokens. briar reads them from env vars (or your credential store), named after the company. The runbook only holds env var names, in dsn_env, webhook_env, chat_env, and the MCP env and headers.

Used byEnv vars (company acme)
GitHub repos, github-issues, github-pr-commentGITHUB_TOKEN (one for all companies)
Bitbucket repos, bitbucket-issues, bitbucket-pr-commentBITBUCKET_ACME_USERNAME, BITBUCKET_ACME_APP_PASSWORD, BITBUCKET_ACME_WORKSPACE
Jira extractorsJIRA_ACME_URL plus either JIRA_ACME_EMAIL and JIRA_ACME_TOKEN, or a browser session (see Jira session login)
jira-comment, jira-transitionJIRA_ACME_URL, JIRA_ACME_EMAIL, JIRA_ACME_TOKEN (token only)
Linear trackerLINEAR_ACME_TOKEN
AWS (aws-infra)AWS_ACME_ACCESS_KEY_ID, AWS_ACME_SECRET_ACCESS_KEY, optional AWS_ACME_SESSION_TOKEN and AWS_ACME_REGION. Without them, AWS uses its normal login (profile, SSO or machine role).
Fireflies (meeting-digest)FIREFLIES_ACME_API_KEY
Postgres storeSee Which database Postgres uses
slack-channelSLACK_ACME_WEBHOOK_URL, or the name in webhook_env
telegram-chatTELEGRAM_BOT_TOKEN and TELEGRAM_ACME_CHAT_ID, or the name in chat_env

For a company key with a dash, like acme-co, the env var part is ACME_CO. GCP, Azure and the full list are on the Configuration page. To see what is missing:

$ briar secrets doctor --examples runbooks/

You get ok or MISSING: ... for every extractor and channel in every *.yaml file. Values are never printed.

Timer strings for every:

every uses a tiny language. Only briar runbook serve reads it. Upper or lower case both work.

The forms that work

<unit> minute | hour | day | week | monday ... sunday
<n> <units> 5 minutes | 4 hours | 2 days | 3 weeks (no number on a weekday)
day at HH:MM day at 03:17 | 2 days at 06:00 (UTC, two-digit hour)
<weekday> at HH:MM monday at 09:00 (UTC, two-digit hour)
hour at :MM hour at :15 | 2 hours at :15 (minute past the hour)
minute at :SS minute at :30 (second of the minute)
<unit> may be singular or plural: "hour" and "hours" mean the same.

Examples

everyRuns
"5 minutes"Every 5 minutes. Too fast for most extractors; good for a test.
"hour"Every hour, at a fixed minute picked for this company and job.
"hour at :15"Every hour at 15 minutes past.
"4 hours"Every 4 hours, at a fixed offset.
"day"Once a day, at a fixed offset.
"day at 03:17"Every day at 03:17 UTC. This is the timer of the company extract list.
"2 days at 06:00"Every second day at 06:00 UTC.
"monday at 09:00"Every Monday at 09:00 UTC.
"2 weeks"Every 2 weeks, at a fixed offset.

These fail: daily, every day, day at 3:17 (write 03:17), day at 03:17:30, week at 09:00, 2 mondays, hour at 15. Watch out for hour at 00:15: it loads, but means 0 minutes and 15 seconds.

The fixed offset (stagger)

A timer without at does not start at the top of its period. briar shifts it by an offset inside the period: 0 to 59 minutes for an hourly job, 0 to 239 minutes for a 4-hour job. The offset comes from a hash of company:task, so it is the same after a restart, and two companies do not hit the same API at the same minute. Timers with at are never shifted. This also means a weekday without a time, like "monday", can first run on another day. Always give a weekday a time.

Every args key, per extractor

Anything you can pass to briar extract on the command line can go under args. Three rules:

  1. Drop the leading -- and change - to _. --since-days becomes since_days.
  2. A flag you can repeat becomes a list. --repo a --repo b becomes repo: [a, b]. Use a list even for one item.
  3. A shared key fills the extractor's own key, unless you also set the own key. The own key wins.

Shared keys

Shared keyMeansExample
repoRepos to read, as owner/repo. A list.repo: [acme-co/acme-app]
since_daysHow many days back to look.since_days: 30
maxMost items or commits to read per repo.max: 100
top_nHow many results to keep per repo.top_n: 5
sampleHow many recent pull requests to sample.sample: 30
authors_allow, authors_blockKeep only, or drop, items by these authors. A list.authors_block: ["renovate[bot]"]
assignees_allow, assignees_blockKeep only, or drop, items assigned to these people. A list.assignees_allow: [alice]

For active-tickets and ticket-archaeology, repo fills the project list only for GitHub Issues and Bitbucket Issues. For Jira and Linear, set ticket_project or ticket_archaeology_project (a Jira key like ACME, or a Linear team like ENG).

Keys of each extractor

Defaults are in brackets. The last column lists the shared keys that extractor reads. Every extractor also gets company, set to the company key for you.

ExtractorIts own keys (default)Shared keys
pr-archaeologyprovider (github), pr_repo ([]), pr_max (100), pr_authors_allow ([]), pr_authors_block ([]), pr_assignees_allow ([]), pr_assignees_block ([])repo, max, authors_allow, authors_block, assignees_allow, assignees_block
aws-infracloud (aws), aws_extract_profile (none), aws_extract_region (us-east-1), aws_extract_service ([])none
active-workprovider (github), active_repo ([]), active_authors_allow ([]), active_authors_block ([]), active_assignees_allow ([]), active_assignees_block ([])repo, authors_allow, authors_block, assignees_allow, assignees_block
github-deploymentsprovider (github), deploy_repo ([])repo
codebase-conventionsprovider (github), conventions_repo ([])repo
active-ticketstracker (jira), ticket_project ([])repo (GitHub and Bitbucket Issues only)
ticket-archaeologytracker (jira), ticket_archaeology_project ([]), ticket_max (100)repo (GitHub and Bitbucket Issues only), max
reviewer-profileprovider (github), reviewer_repo ([]), reviewer_pr_sample (20), reviewer_top_n (5)repo, sample, top_n
code-hotspotsprovider (github), hotspots_repo ([]), hotspots_since_days (30), hotspots_max_commits (100), hotspots_top_n (10)repo, since_days, max, top_n
meeting-digestmeeting (fireflies), meeting_since_days (7), meeting_max (25), meeting_attendee_allow ([])since_days, max
defect-hotspotsprovider (github), risk_repo ([]), risk_since_days (90), risk_max_commits (200), risk_top_n (10)repo, since_days, max, top_n
review-nitsprovider (github), nits_repo ([]), nits_pr_sample (30), nits_top_n (15)repo, sample, top_n
pr-hygieneprovider (github), prhygiene_repo ([]), prhygiene_max (100), prhygiene_diffstat_sample (30), prhygiene_large_loc (400)repo, max, sample
ci-healthprovider (github), cihealth_repo ([]), cihealth_limit (100)repo, max
dependency-healthprovider (github), deps_repo ([]), deps_max (200)repo, max
code-scanningprovider (github), scan_repo ([]), scan_max (200), scan_top_n (10)repo, max, top_n
repo-governanceprovider (github), gov_repo ([]), gov_branch ("")repo
revert-signalsprovider (github), revert_repo ([]), revert_since_days (90), revert_max_commits (200)repo, since_days, max
stale-prsprovider (github), stale_repo ([]), stale_max (100), stale_days (14)repo, max
test-disciplineprovider (github), testdisc_repo ([]), testdisc_top_n (10)repo, top_n
todo-densityprovider (github), todo_repo ([]), todo_max (200), todo_top_n (10)repo, max, top_n
release-cadenceprovider (github), release_repo ([]), release_max (100)repo, max
commit-message-qualityprovider (github), msg_repo ([]), msg_since_days (90), msg_max_commits (200)repo, since_days, max

Keys with a fixed set of values

KeyAllowed values
providergithub, bitbucket
trackerjira, github-issues, bitbucket-issues, linear
cloudaws, gcp, azure
aws_extract_serviceecs, lambda, logs, rds, sqs, tagging-inventory
meetingfireflies

args are not checked when the file loads

The command line rejects a wrong flag or value. A runbook does not: an unknown key under args is ignored, and a wrong value fails only when the job runs. Try the same settings with briar extract first if you are not sure.

Message kinds and their config keys

When the agent calls send_message, it gives a channel name, a target and a body. The target depends on the kind.

kindTarget the agent givesconfig keys
jira-commentA ticket key, like ACME-42.None.
jira-transitionA ticket key. The body becomes a comment on the move.status: the default status to move to, like "In Review". The agent can pick another one per message. With neither, the send fails.
github-pr-commentacme-co/acme-app#482. With a file and line, it replies on that line.None.
bitbucket-pr-commentacme-co/acme-app#482 (workspace/repo#PR).None.
slack-channelNot used. The webhook decides the channel.webhook_env: the name of the env var with the webhook URL. Default SLACK_ACME_WEBHOOK_URL. Use it for a second Slack channel.
telegram-chatOptional chat ID. Empty means the bound chat.chat_env: the name of the env var with the chat ID. Default TELEGRAM_ACME_CHAT_ID.

briar secrets doctor checks the default env var names only. It does not follow webhook_env.

More examples

Each example below is a complete file that loads without errors. Change the repos and project keys to yours.

One GitHub repo, run by hand

version: 1
companies:
acme:
knowledge:
store: file
name: knowledge:acme
extract:
- name: pr-archaeology
args:
repo: [acme-co/acme-app]
max: 50
authors_block: ["renovate[bot]", "dependabot[bot]"]
- name: code-hotspots
args:
repo: [acme-co/acme-app]
since_days: 30
top_n: 15
- name: codebase-conventions
args:
repo: [acme-co/acme-app]
$ briar runbook extract runbooks/acme.yaml

You get one blob, knowledge:acme, with three sections.

GitHub, Jira and AWS, once a day

Code in GitHub, tickets in Jira, servers in AWS. One job at 03:17 UTC.

version: 1
companies:
acme:
knowledge:
store: file
name: knowledge:acme
schedules:
- task: extractors
every: "day at 03:17"
extract:
- name: pr-archaeology
args:
repo: [acme-co/acme-app, acme-co/acme-shared]
max: 100
authors_allow: [alice, bob, carol]
- name: active-tickets
args:
tracker: jira
ticket_project: [ACME, INFRA]
- name: ticket-archaeology
args:
tracker: jira
ticket_archaeology_project: [ACME]
ticket_max: 50
- name: aws-infra
args:
cloud: aws
aws_extract_region: us-east-1
aws_extract_service: [ecs, lambda, rds, sqs, logs]
- name: reviewer-profile
args:
repo: [acme-co/acme-app]
top_n: 5
- name: code-hotspots
args:
repo: [acme-co/acme-app]
since_days: 30

Several companies: one file each

Put one file per company in the same folder. Then one serve runs them all.

runbooks/acme.yaml
version: 1
companies:
acme:
knowledge:
store: postgres
name: knowledge:acme
schedules:
- task: extractors
every: "day at 07:00"
extract:
- name: pr-archaeology
args:
repo: [acme-co/acme-app]
- name: active-tickets
args:
tracker: jira
ticket_project: [ACME]
runbooks/widgets.yaml
version: 1
companies:
widgets:
knowledge:
store: postgres
name: knowledge:widgets
schedules:
- task: extractors
every: "day at 07:30"
extract:
- name: pr-archaeology
args:
repo: [widgets-inc/core]
- name: code-hotspots
args:
repo: [widgets-inc/core]
since_days: 14
- task: prfix
every: "hour"
extract:
- name: active-work
args:
repo: [widgets-inc/core]
$ briar runbook serve runbooks/

You get three timers: acme/extractors, widgets/extractors and widgets/prfix.

Why not one file?

You can list both companies in one file. But when a job fires, briar runs that task name for every company in the file. Two companies that both have extractors would then each run twice a day. Separate files avoid this.

Bitbucket and Linear

Same extractors, other services. Set provider for the repo host and tracker for the ticket system. For Linear, the project is the team key.

version: 1
companies:
acme:
knowledge:
store: postgres
name: knowledge:acme
config:
dsn_env: BRIAR_ACME_KB_PG
messages:
pr_reply:
kind: bitbucket-pr-comment
ops_chat:
kind: slack-channel
escalation:
kind: telegram-chat
schedules:
- task: archaeology
every: "monday at 02:30"
extract:
- name: pr-archaeology
args:
provider: bitbucket
repo: [acme-co/acme-app, acme-co/acme-api]
max: 50
- name: ticket-archaeology
args:
tracker: linear
ticket_archaeology_project: [ENG]
- task: prfix
every: "hour"
extract:
- name: active-work
args:
provider: bitbucket
repo: [acme-co/acme-app]
- name: active-tickets
args:
tracker: linear
ticket_project: [ENG]
- task: extractors
every: "day at 04:17"
extract:
- name: aws-infra
args:
cloud: aws
aws_extract_region: us-west-2

Google Cloud

The extractor keeps the name aws-infra. cloud: gcp switches it to Google Cloud. aws_extract_profile holds the project ID. Install the extra first: pip install "briar-cli[gcp]".

version: 1
companies:
acme:
knowledge:
store: file
name: knowledge:acme
schedules:
- task: extractors
every: "day at 05:00"
extract:
- name: aws-infra
args:
cloud: gcp
aws_extract_profile: acme-prod # GCP project ID
aws_extract_region: us-central1

Azure

Same idea. aws_extract_profile holds the subscription ID. Install pip install "briar-cli[azure]".

version: 1
companies:
acme:
knowledge:
store: file
name: knowledge:acme
schedules:
- task: extractors
every: "day at 07:30"
extract:
- name: aws-infra
args:
cloud: azure
aws_extract_profile: 11111111-2222-3333-4444-555555555555 # subscription ID
aws_extract_region: eastus

Meetings, only with some people

Reads Fireflies meeting notes from the last 7 days. It keeps a meeting only if at least one listed person was there.

version: 1
companies:
acme:
knowledge:
store: file
name: knowledge:acme
schedules:
- task: meetings
every: "hour"
extract:
- name: meeting-digest
args:
meeting: fireflies
meeting_since_days: 7
meeting_max: 25
meeting_attendee_allow:

Many timers for one company

A common setup: slow jobs at night, open work every hour, deep history once a week.

version: 1
companies:
acme:
knowledge:
store: postgres
name: knowledge:acme
schedules:
# Slow, complete jobs: once a night.
- task: nightly
every: "day at 03:17"
extract:
- name: pr-archaeology
args: { repo: [acme-co/acme-app, acme-co/acme-api] }
- name: reviewer-profile
args: { repo: [acme-co/acme-app], top_n: 5 }
- name: code-hotspots
args: { repo: [acme-co/acme-app], since_days: 30 }
# How the code is written and shipped: every 4 hours.
- task: implementation
every: "4 hours"
extract:
- name: codebase-conventions
args: { repo: [acme-co/acme-app, acme-co/acme-api] }
- name: github-deployments
args: { repo: [acme-co/acme-app] }
# Open tickets: every hour.
- task: tickets
every: "hour"
extract:
- name: active-tickets
args: { tracker: jira, ticket_project: [ACME] }
# Open pull requests: every hour, at 15 minutes past.
- task: prfix
every: "hour at :15"
extract:
- name: active-work
args:
repo: [acme-co/acme-app, acme-co/acme-api]
authors_block: ["renovate[bot]", "dependabot[bot]"]
# Old tickets: once a week.
- task: weekly
every: "monday at 02:00"
extract:
- name: ticket-archaeology
args:
tracker: jira
ticket_archaeology_project: [ACME]
ticket_max: 200

Every message kind

All six kinds, plus a second Slack channel and a second Telegram chat.

version: 1
companies:
acme:
knowledge:
store: postgres
name: knowledge:acme
messages:
# Jira: add a comment, or move the ticket to a new status.
ticket_comment:
kind: jira-comment
ticket_review:
kind: jira-transition
config:
status: "In Review"
# A comment on a pull request.
pr_reply:
kind: github-pr-comment
bb_pr_reply:
kind: bitbucket-pr-comment
# Slack: the default webhook is SLACK_ACME_WEBHOOK_URL.
ops_chat:
kind: slack-channel
# A second Slack channel that reads a different env var.
escalation_slack:
kind: slack-channel
config:
webhook_env: SLACK_ACME_ESCALATION_WEBHOOK_URL
# Telegram: the default chat is TELEGRAM_ACME_CHAT_ID.
escalation_telegram:
kind: telegram-chat
config:
chat_env: TELEGRAM_ACME_ONCALL_CHAT_ID

Jira session login (no API token)

Some Jira sites turn off API tokens. briar can then log in with your browser session cookies. The runbook does not change. Only the env vars do.

version: 1
companies:
acme:
knowledge:
store: file
name: knowledge:acme
schedules:
- task: tickets
every: "hour"
extract:
- name: active-tickets
args:
tracker: jira
ticket_project: [ACME]
# Set these env vars outside this file (for example in your secrets file):
# JIRA_ACME_URL https://acme.atlassian.net
# JIRA_ACME_TENANT_SESSION_TOKEN value of the tenant.session.token cookie
# JIRA_ACME_XSRF_TOKEN value of the atlassian.xsrf.token cookie
# Optional, to force session login:
# JIRA_ACME_AUTH_KIND=session
  • JIRA_ACME_SESSION_TOKEN (the cloud.session.token cookie) works in place of the tenant cookie.
  • If a session cookie env var is set, briar uses session login. Otherwise it uses JIRA_ACME_EMAIL and JIRA_ACME_TOKEN. JIRA_ACME_AUTH_KIND (token or session) forces one.
  • This is for the Jira extractors only. The jira-comment and jira-transition message kinds still need the email and token.

Staging and production

Two company keys, with profile as a label. Staging runs later and reads fewer pull requests.

version: 1
companies:
acme-prod:
profile: production
knowledge:
store: postgres
name: knowledge:acme-prod
schedules:
- task: prod-nightly
every: "day at 03:17"
extract:
- name: pr-archaeology
args: { repo: [acme-co/acme-app] }
acme-staging:
profile: staging
knowledge:
store: postgres
name: knowledge:acme-staging
schedules:
- task: staging-nightly
every: "day at 04:00"
extract:
- name: pr-archaeology
args: { repo: [acme-co/acme-app], max: 25 }
  • The task names differ, so serve does not run each job twice.
  • Avoid one company key that starts another, like acme and acme-staging. Agents for acme read every blob that starts with knowledge:acme, so they would also read staging's.

Cookbook

Reuse args with YAML anchors

Name a block once with &name, then copy it with <<: *name. Keys after the copy change only that one value.

version: 1
companies:
acme:
knowledge:
store: file
name: knowledge:acme
schedules:
- task: nightly
every: "day at 03:17"
extract:
- name: pr-archaeology
args: &pr_args
repo: [acme-co/acme-app, acme-co/acme-api]
max: 100
authors_block: ["renovate[bot]", "dependabot[bot]"]
- task: backfill
every: "monday at 02:00"
extract:
- name: pr-archaeology
args:
<<: *pr_args
max: 500 # change just this key

Run one job now

Pass the job name to --task. The timer is not used.

$ briar runbook extract runbooks/acme.yaml --task tickets
$ briar runbook extract runbooks/acme.yaml --task nightly

You get one fresh blob per command.

Spread jobs out at startup

You do not need to do anything. A timer without at already gets a fixed offset from its company and task name. So acme:tickets and widgets:tickets on "hour" run at different minutes, and keep those minutes after a restart. Use at only when you need an exact time.

One database per company

Name the env var in dsn_env. Leave it out to use BRIAR_ACME_DATABASE_URL, and then BRIAR_DATABASE_URL.

version: 1
companies:
# 1. Reads the env var named in dsn_env: BRIAR_ACME_KB_PG.
acme:
knowledge:
store: postgres
name: knowledge:acme
config:
dsn_env: BRIAR_ACME_KB_PG
extract:
- name: active-work
args: { repo: [acme-co/acme-app] }

Check credentials before you run

$ briar secrets doctor --examples runbooks/

You get one line per extractor and per message channel, for each company. Missing env vars are named. Values are never printed. The exit code is 1 if anything is missing.

Turn a command into YAML

Start from a command that works:

$ briar extract --company acme --include pr-archaeology \
--repo acme-co/acme-app --repo acme-co/acme-api \
--max 50 --authors-block "renovate[bot]"

Drop briar extract --company acme. The --include value becomes name. The other flags go under args, with _ for -. Repeated flags become lists.

version: 1
companies:
acme:
knowledge:
store: file
name: knowledge:acme
extract:
- name: pr-archaeology
args:
repo: [acme-co/acme-app, acme-co/acme-api]
max: 50
authors_block: ["renovate[bot]"]

Checking a runbook

Three checks, from fast to full.

1. Load the file, run nothing

$ briar runbook extract runbooks/acme.yaml --task check-only

No job is named check-only, so nothing runs. briar still loads the file. A bad key, extractor name, message kind or store gives an error that names the line and field. A good file prints an empty table. This does not check every or args.

To also check every timer string, run this Python in the same environment where briar is installed:

from pathlib import Path
from briar.iac.runbook import EveryParser, RunbookSchedules, load_runbook_file
runbook = load_runbook_file(Path("runbooks/acme.yaml"))
for name, company in runbook.companies.items():
for schedule in RunbookSchedules.for_company(company):
EveryParser.parse(schedule.every)
print(name, schedule.task, schedule.every, "ok")

You get one ok line per job, or an error for the bad one.

2. Check credentials

$ briar secrets doctor --examples runbooks/

You get every missing env var, by extractor and by message channel.

3. Run one job for real

$ briar runbook extract runbooks/acme.yaml --task tickets

This calls the real APIs and writes to the knowledge store. Nothing is scheduled. Check the status column: you want wrote ... or skipped (unchanged, ...), not empty or failed.

See also