Reference
Runbook YAML schema.
On this page
- The shape of a runbook
- Build it step by step: 1. smallest file, 2. knowledge store, 3. schedules, 4. extractor args, 5. user filters, 6. messages, 7. MCP servers, 8. git identity
- Everything in one file
- Key reference: top level, company, extract entry, schedule, knowledge, messages, git_identity, mcp
- Credentials (not in the file)
- Timer strings for every:
- Every args key, per extractor
- Message kinds and their config keys
- More examples, cookbook, checking a runbook
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 1companies: # one or more companiesacme: # the company keyknowledge: ... # where results are savedextract: ... # extractors that run once a dayschedules: ... # named groups of extractors, each with a timermessages: ... # channels agents may post tomcp: ... # MCP servers agents may usegit_identity: ... # name and email on agent commitsprofile: ... # free text labelworkspace_id: ... # free text labelknowledge_file: ... # old way to name the output file
| Keys | Read by |
|---|---|
knowledge, extract, schedules, knowledge_file | briar runbook extract, sweep and serve. |
messages, mcp, git_identity | briar agent implement, agent prfix and plan run, when you pass --runbook. |
profile, workspace_id | Nothing 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:
version: 1companies:acme:extract:- name: codebase-conventionsargs:repo: [acme-co/acme-app]
companies.acmeis the company.extractis a list of extractors to run. Each one has anameand optionalargs.codebase-conventionsreads 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: 1companies:acme:knowledge:store: filename: knowledge:acmeextract:- name: codebase-conventionsargs: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
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: 1companies:acme:knowledge:store: filename: knowledge:acmeschedules:- task: extractorsevery: "day at 03:17"extract:- name: codebase-conventionsargs:repo: [acme-co/acme-app]- name: pr-archaeologyargs:repo: [acme-co/acme-app]- task: ticketsevery: "hour"extract:- name: active-ticketsargs:tracker: jiraticket_project: [ACME]
taskis the job name. You use it with--task.everyis the timer. See timer strings.- Each job saves its own blob. The job named
extractorswrites toknowledge: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: 1companies:acme:knowledge:store: filename: knowledge:acmeschedules:- task: extractorsevery: "day at 03:17"extract:- name: code-hotspotsargs:repo: [acme-co/acme-app, acme-co/acme-shared]since_days: 60top_n: 15- name: reviewer-profileargs:repo: [acme-co/acme-app]reviewer_top_n: 3- name: aws-infraargs:cloud: awsaws_extract_region: us-east-1aws_extract_service: [ecs, rds, lambda]
repo,since_daysandtop_nare shared keys. Every extractor that has that idea uses them.reviewer_top_nis 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: 1companies:acme:knowledge:store: filename: knowledge:acmeschedules:- task: prfixevery: "hour"extract:- name: pr-archaeologyargs:repo: [acme-co/acme-app]authors_block: ["renovate[bot]", "dependabot[bot]"]- name: active-workargs:repo: [acme-co/acme-app]authors_allow: [alice, bob]assignees_block: [carol]
| Key | Keeps |
|---|---|
authors_allow | Only items written by someone in the list. |
authors_block | Everything except items written by someone in the list. |
assignees_allow | Only items assigned to someone in the list. |
assignees_block | Everything except items assigned to someone in the list. |
- Only
pr-archaeologyandactive-workread 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-digesthas 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: 1companies:acme:knowledge:store: filename: knowledge:acmeextract:- name: active-workargs:repo: [acme-co/acme-app]messages:ticket_comment:kind: jira-commentpr_reply:kind: github-pr-commentops_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: 1companies:acme:knowledge:store: filename: knowledge:acmemcp:github:command: dockerargs: ["run", "-i", "--rm", "-e", "GITHUB_TOKEN", "ghcr.io/github/github-mcp-server"]env:GITHUB_TOKEN: GITHUB_TOKENtools: [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. envvalues are env var names, not secrets. Here briar copies its ownGITHUB_TOKENinto the server.- Two servers are always added when the MCP extra is installed:
thinkandtime. Without the extra, briar skips them with one warning. Turn them off with--no-default-mcpon the agent command orBRIAR_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: 1companies:acme:knowledge:store: filename: knowledge:acmegit_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.
version: 1companies:acme:profile: productionknowledge:store: postgresname: knowledge:acmeconfig:dsn_env: BRIAR_ACME_DATABASE_URLinventory: "true"git_identity:name: acme-briar-botmessages:ticket_comment:kind: jira-commentticket_done:kind: jira-transitionconfig:status: "In Review"pr_reply:kind: github-pr-commentops_chat:kind: slack-channelescalation:kind: telegram-chatconfig:chat_env: TELEGRAM_ACME_ONCALL_CHAT_IDmcp:github:transport: stdiocommand: dockerargs: ["run", "-i", "--rm", "-e", "GITHUB_TOKEN", "ghcr.io/github/github-mcp-server"]env:GITHUB_TOKEN: GITHUB_TOKENtools: [search_issues, get_pull_request]purpose: "GitHub issues, pull requests and review threads"sentry:transport: httpurl: https://mcp.sentry.dev/mcpheaders:Authorization: SENTRY_MCP_BEARERarchetypes: [engineer]purpose: "Production errors, stack traces and regressions"enabled: falseschedules:- task: extractorsevery: "day at 03:17"extract:- name: pr-archaeologyargs:repo: [acme-co/acme-app, acme-co/acme-shared]max: 100authors_block: ["renovate[bot]", "dependabot[bot]"]- name: codebase-conventionsargs:repo: [acme-co/acme-app]- name: aws-infraargs:cloud: awsaws_extract_region: us-east-1aws_extract_service: [ecs, rds, lambda]- task: ticketsevery: "hour"extract:- name: active-ticketsargs:tracker: jiraticket_project: [ACME]- task: meetingsevery: "4 hours"extract:- name: meeting-digestargs:meeting: firefliessince_days: 7
Top-level keys
version integerdefault: 11 exists. You may leave it out.companies map: company key → companyrequiredacme) is the company name used by --company and in env var names. An empty map is an error.version: 1companies:acme:extract:- name: active-workargs: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>extract list of extract entriesdefault: []extractors, timer "day at 03:17". If a schedule is already named extractors, this list is ignored. See extract entry.schedules list of schedulesdefault: []messages map: channel name → message bindingdefault: {}mcp map: server name → MCP serverdefault: {}git_identity mapdefault: not setprofile stringdefault: ""production. briar does not use it.workspace_id stringdefault: ""knowledge_file stringdefault: ""knowledge.name is empty, and always with the file store. Prefer knowledge.version: 1companies:acme:profile: productionworkspace_id: acme-engknowledge:store: filename: knowledge:acmeextract:- name: active-workargs:repo: [acme-co/acme-app]
Typos at this level are ignored
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 namerequiredargs mapdefault: {} (the extractor's defaults)version: 1companies:acme:extract:- name: stale-prsargs: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 stringrequiredrunbook 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 stringrequiredextract list of extract entriesdefault: []version: 1companies:acme:knowledge:store: filename: knowledge:acmeschedules:- task: weeklyevery: "monday at 06:00"extract:- name: ticket-archaeologyargs:tracker: jiraticket_archaeology_project: [ACME]ticket_max: 200
Knowledge
Where a company's results are saved.
store stringdefault: filefilepostgresfile 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)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--root option). Postgres ignores it.config map of stringsdefault: {}"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: 1companies:acme:knowledge:store: postgresname: knowledge:acmeconfig:dsn_env: BRIAR_ACME_KB_PGinventory: "true"extract:- name: aws-infraargs:aws_extract_service: [tagging-inventory]
Where a file-store name ends up
| name | File |
|---|---|
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
- The env var named in
config.dsn_env. BRIAR_ACME_DATABASE_URL(company name in upper case,-becomes_).BRIAR_DATABASE_URL.
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 stringrequiredjira-commentjira-transitiongithub-pr-commentbitbucket-pr-commentslack-channeltelegram-chatconfig mapdefault: {}version: 1companies:acme:messages:ticket_done:kind: jira-transitionconfig:status: "Done"ops_chat:kind: slack-channelconfig:webhook_env: SLACK_ACME_OPS_WEBHOOK_URL
git_identity
name stringdefault: ""git config user.name for agent commits. Example: acme-briar-bot.email stringdefault: ""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: stdiostdiohttpstdio starts the server as a local program. http talks to a server over the network (Streamable HTTP).command stringdefault: ""stdio. Example: docker or uvx.args list of stringsdefault: []command.env mapdefault: {}url stringdefault: ""http.headers mapdefault: {}Bearer abc123).tools list of stringsdefault: [] (all tools)enabled true or falsedefault: truefalse skips the server but keeps its block in the file.archetypes list of stringsdefault: [] (every agent type)engineer (used by agent implement) or pr-fixer (used by agent prfix).purpose stringdefault: ""version: 1companies:acme:mcp:aws:transport: stdiocommand: uvxargs: ["awslabs.aws-api-mcp-server@latest"]env:AWS_ACCESS_KEY_ID: AWS_ACME_ACCESS_KEY_IDAWS_SECRET_ACCESS_KEY: AWS_ACME_SECRET_ACCESS_KEYAWS_REGION: AWS_ACME_REGIONREAD_OPERATIONS_ONLY: READ_OPERATIONS_ONLYtools: [call_aws, suggest_aws_commands]purpose: "Live AWS account state: ECS, RDS, Lambda, logs"sentry:transport: httpurl: https://mcp.sentry.dev/mcpheaders:Authorization: SENTRY_MCP_BEARERarchetypes: [engineer]
- A
stdioserver with nocommand, or anhttpserver with nourl, is an error when the file loads. - The built-in
thinkserver needsnpxandtimeneedsuvx. Use a server name ofthinkortimein your file to replace one. - MCP tools are not limited to the agent's work folder. Keep
toolsshort, 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 by | Env vars (company acme) |
|---|---|
GitHub repos, github-issues, github-pr-comment | GITHUB_TOKEN (one for all companies) |
Bitbucket repos, bitbucket-issues, bitbucket-pr-comment | BITBUCKET_ACME_USERNAME, BITBUCKET_ACME_APP_PASSWORD, BITBUCKET_ACME_WORKSPACE |
| Jira extractors | JIRA_ACME_URL plus either JIRA_ACME_EMAIL and JIRA_ACME_TOKEN, or a browser session (see Jira session login) |
jira-comment, jira-transition | JIRA_ACME_URL, JIRA_ACME_EMAIL, JIRA_ACME_TOKEN (token only) |
| Linear tracker | LINEAR_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 store | See Which database Postgres uses |
slack-channel | SLACK_ACME_WEBHOOK_URL, or the name in webhook_env |
telegram-chat | TELEGRAM_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
| every | Runs |
|---|---|
"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)
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:
- Drop the leading
--and change-to_.--since-daysbecomessince_days. - A flag you can repeat becomes a list.
--repo a --repo bbecomesrepo: [a, b]. Use a list even for one item. - A shared key fills the extractor's own key, unless you also set the own key. The own key wins.
Shared keys
| Shared key | Means | Example |
|---|---|---|
repo | Repos to read, as owner/repo. A list. | repo: [acme-co/acme-app] |
since_days | How many days back to look. | since_days: 30 |
max | Most items or commits to read per repo. | max: 100 |
top_n | How many results to keep per repo. | top_n: 5 |
sample | How many recent pull requests to sample. | sample: 30 |
authors_allow, authors_block | Keep only, or drop, items by these authors. A list. | authors_block: ["renovate[bot]"] |
assignees_allow, assignees_block | Keep 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.
| Extractor | Its own keys (default) | Shared keys |
|---|---|---|
pr-archaeology | provider (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-infra | cloud (aws), aws_extract_profile (none), aws_extract_region (us-east-1), aws_extract_service ([]) | none |
active-work | provider (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-deployments | provider (github), deploy_repo ([]) | repo |
codebase-conventions | provider (github), conventions_repo ([]) | repo |
active-tickets | tracker (jira), ticket_project ([]) | repo (GitHub and Bitbucket Issues only) |
ticket-archaeology | tracker (jira), ticket_archaeology_project ([]), ticket_max (100) | repo (GitHub and Bitbucket Issues only), max |
reviewer-profile | provider (github), reviewer_repo ([]), reviewer_pr_sample (20), reviewer_top_n (5) | repo, sample, top_n |
code-hotspots | provider (github), hotspots_repo ([]), hotspots_since_days (30), hotspots_max_commits (100), hotspots_top_n (10) | repo, since_days, max, top_n |
meeting-digest | meeting (fireflies), meeting_since_days (7), meeting_max (25), meeting_attendee_allow ([]) | since_days, max |
defect-hotspots | provider (github), risk_repo ([]), risk_since_days (90), risk_max_commits (200), risk_top_n (10) | repo, since_days, max, top_n |
review-nits | provider (github), nits_repo ([]), nits_pr_sample (30), nits_top_n (15) | repo, sample, top_n |
pr-hygiene | provider (github), prhygiene_repo ([]), prhygiene_max (100), prhygiene_diffstat_sample (30), prhygiene_large_loc (400) | repo, max, sample |
ci-health | provider (github), cihealth_repo ([]), cihealth_limit (100) | repo, max |
dependency-health | provider (github), deps_repo ([]), deps_max (200) | repo, max |
code-scanning | provider (github), scan_repo ([]), scan_max (200), scan_top_n (10) | repo, max, top_n |
repo-governance | provider (github), gov_repo ([]), gov_branch ("") | repo |
revert-signals | provider (github), revert_repo ([]), revert_since_days (90), revert_max_commits (200) | repo, since_days, max |
stale-prs | provider (github), stale_repo ([]), stale_max (100), stale_days (14) | repo, max |
test-discipline | provider (github), testdisc_repo ([]), testdisc_top_n (10) | repo, top_n |
todo-density | provider (github), todo_repo ([]), todo_max (200), todo_top_n (10) | repo, max, top_n |
release-cadence | provider (github), release_repo ([]), release_max (100) | repo, max |
commit-message-quality | provider (github), msg_repo ([]), msg_since_days (90), msg_max_commits (200) | repo, since_days, max |
Keys with a fixed set of values
| Key | Allowed values |
|---|---|
provider | github, bitbucket |
tracker | jira, github-issues, bitbucket-issues, linear |
cloud | aws, gcp, azure |
aws_extract_service | ecs, lambda, logs, rds, sqs, tagging-inventory |
meeting | fireflies |
args are not checked when the file loads
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.
| kind | Target the agent gives | config keys |
|---|---|---|
jira-comment | A ticket key, like ACME-42. | None. |
jira-transition | A 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-comment | acme-co/acme-app#482. With a file and line, it replies on that line. | None. |
bitbucket-pr-comment | acme-co/acme-app#482 (workspace/repo#PR). | None. |
slack-channel | Not 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-chat | Optional 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: 1companies:acme:knowledge:store: filename: knowledge:acmeextract:- name: pr-archaeologyargs:repo: [acme-co/acme-app]max: 50authors_block: ["renovate[bot]", "dependabot[bot]"]- name: code-hotspotsargs:repo: [acme-co/acme-app]since_days: 30top_n: 15- name: codebase-conventionsargs: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: 1companies:acme:knowledge:store: filename: knowledge:acmeschedules:- task: extractorsevery: "day at 03:17"extract:- name: pr-archaeologyargs:repo: [acme-co/acme-app, acme-co/acme-shared]max: 100authors_allow: [alice, bob, carol]- name: active-ticketsargs:tracker: jiraticket_project: [ACME, INFRA]- name: ticket-archaeologyargs:tracker: jiraticket_archaeology_project: [ACME]ticket_max: 50- name: aws-infraargs:cloud: awsaws_extract_region: us-east-1aws_extract_service: [ecs, lambda, rds, sqs, logs]- name: reviewer-profileargs:repo: [acme-co/acme-app]top_n: 5- name: code-hotspotsargs: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.
version: 1companies:acme:knowledge:store: postgresname: knowledge:acmeschedules:- task: extractorsevery: "day at 07:00"extract:- name: pr-archaeologyargs:repo: [acme-co/acme-app]- name: active-ticketsargs:tracker: jiraticket_project: [ACME]
version: 1companies:widgets:knowledge:store: postgresname: knowledge:widgetsschedules:- task: extractorsevery: "day at 07:30"extract:- name: pr-archaeologyargs:repo: [widgets-inc/core]- name: code-hotspotsargs:repo: [widgets-inc/core]since_days: 14- task: prfixevery: "hour"extract:- name: active-workargs:repo: [widgets-inc/core]
$ briar runbook serve runbooks/
You get three timers: acme/extractors, widgets/extractors and widgets/prfix.
Why not one file?
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: 1companies:acme:knowledge:store: postgresname: knowledge:acmeconfig:dsn_env: BRIAR_ACME_KB_PGmessages:pr_reply:kind: bitbucket-pr-commentops_chat:kind: slack-channelescalation:kind: telegram-chatschedules:- task: archaeologyevery: "monday at 02:30"extract:- name: pr-archaeologyargs:provider: bitbucketrepo: [acme-co/acme-app, acme-co/acme-api]max: 50- name: ticket-archaeologyargs:tracker: linearticket_archaeology_project: [ENG]- task: prfixevery: "hour"extract:- name: active-workargs:provider: bitbucketrepo: [acme-co/acme-app]- name: active-ticketsargs:tracker: linearticket_project: [ENG]- task: extractorsevery: "day at 04:17"extract:- name: aws-infraargs:cloud: awsaws_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: 1companies:acme:knowledge:store: filename: knowledge:acmeschedules:- task: extractorsevery: "day at 05:00"extract:- name: aws-infraargs:cloud: gcpaws_extract_profile: acme-prod # GCP project IDaws_extract_region: us-central1
Azure
Same idea. aws_extract_profile holds the subscription ID. Install pip install "briar-cli[azure]".
version: 1companies:acme:knowledge:store: filename: knowledge:acmeschedules:- task: extractorsevery: "day at 07:30"extract:- name: aws-infraargs:cloud: azureaws_extract_profile: 11111111-2222-3333-4444-555555555555 # subscription IDaws_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: 1companies:acme:knowledge:store: filename: knowledge:acmeschedules:- task: meetingsevery: "hour"extract:- name: meeting-digestargs:meeting: firefliesmeeting_since_days: 7meeting_max: 25meeting_attendee_allow:
Many timers for one company
A common setup: slow jobs at night, open work every hour, deep history once a week.
version: 1companies:acme:knowledge:store: postgresname: knowledge:acmeschedules:# Slow, complete jobs: once a night.- task: nightlyevery: "day at 03:17"extract:- name: pr-archaeologyargs: { repo: [acme-co/acme-app, acme-co/acme-api] }- name: reviewer-profileargs: { repo: [acme-co/acme-app], top_n: 5 }- name: code-hotspotsargs: { repo: [acme-co/acme-app], since_days: 30 }# How the code is written and shipped: every 4 hours.- task: implementationevery: "4 hours"extract:- name: codebase-conventionsargs: { repo: [acme-co/acme-app, acme-co/acme-api] }- name: github-deploymentsargs: { repo: [acme-co/acme-app] }# Open tickets: every hour.- task: ticketsevery: "hour"extract:- name: active-ticketsargs: { tracker: jira, ticket_project: [ACME] }# Open pull requests: every hour, at 15 minutes past.- task: prfixevery: "hour at :15"extract:- name: active-workargs:repo: [acme-co/acme-app, acme-co/acme-api]authors_block: ["renovate[bot]", "dependabot[bot]"]# Old tickets: once a week.- task: weeklyevery: "monday at 02:00"extract:- name: ticket-archaeologyargs:tracker: jiraticket_archaeology_project: [ACME]ticket_max: 200
Every message kind
All six kinds, plus a second Slack channel and a second Telegram chat.
version: 1companies:acme:knowledge:store: postgresname: knowledge:acmemessages:# Jira: add a comment, or move the ticket to a new status.ticket_comment:kind: jira-commentticket_review:kind: jira-transitionconfig:status: "In Review"# A comment on a pull request.pr_reply:kind: github-pr-commentbb_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-channelconfig:webhook_env: SLACK_ACME_ESCALATION_WEBHOOK_URL# Telegram: the default chat is TELEGRAM_ACME_CHAT_ID.escalation_telegram:kind: telegram-chatconfig: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: 1companies:acme:knowledge:store: filename: knowledge:acmeschedules:- task: ticketsevery: "hour"extract:- name: active-ticketsargs:tracker: jiraticket_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(thecloud.session.tokencookie) works in place of the tenant cookie.- If a session cookie env var is set, briar uses session login. Otherwise it uses
JIRA_ACME_EMAILandJIRA_ACME_TOKEN.JIRA_ACME_AUTH_KIND(tokenorsession) forces one. - This is for the Jira extractors only. The
jira-commentandjira-transitionmessage 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: 1companies:acme-prod:profile: productionknowledge:store: postgresname: knowledge:acme-prodschedules:- task: prod-nightlyevery: "day at 03:17"extract:- name: pr-archaeologyargs: { repo: [acme-co/acme-app] }acme-staging:profile: stagingknowledge:store: postgresname: knowledge:acme-stagingschedules:- task: staging-nightlyevery: "day at 04:00"extract:- name: pr-archaeologyargs: { repo: [acme-co/acme-app], max: 25 }
- The task names differ, so
servedoes not run each job twice. - Avoid one company key that starts another, like
acmeandacme-staging. Agents foracmeread every blob that starts withknowledge: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: 1companies:acme:knowledge:store: filename: knowledge:acmeschedules:- task: nightlyevery: "day at 03:17"extract:- name: pr-archaeologyargs: &pr_argsrepo: [acme-co/acme-app, acme-co/acme-api]max: 100authors_block: ["renovate[bot]", "dependabot[bot]"]- task: backfillevery: "monday at 02:00"extract:- name: pr-archaeologyargs:<<: *pr_argsmax: 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: 1companies:# 1. Reads the env var named in dsn_env: BRIAR_ACME_KB_PG.acme:knowledge:store: postgresname: knowledge:acmeconfig:dsn_env: BRIAR_ACME_KB_PGextract:- name: active-workargs: { 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: 1companies:acme:knowledge:store: filename: knowledge:acmeextract:- name: pr-archaeologyargs:repo: [acme-co/acme-app, acme-co/acme-api]max: 50authors_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 Pathfrom briar.iac.runbook import EveryParser, RunbookSchedules, load_runbook_filerunbook = 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
- briar runbook: the commands that run these files, the scheduler, and failure alerts.
- briar extract: every extractor and flag, from the command line.
- briar agent: how agents use
messages,mcpandgit_identity. - Plugin registries: every extractor, message kind and provider name.
- Configuration: env var names and credential stores.
- Recipes: full setups from start to end.