config.yml Reference

Minimal Example

The smallest useful configuration:

branches:
  defaultBase: main

pr:
  merge:
    method: squash

Full Schema

Branching Strategy

Controls which branch agents target for new PRs and whether release branch workflows are enabled.

branches:
  defaultBase: main
  release:
    enabled: false
    base: main

Field	Default	What it does
branches.defaultBase	main	Default base branch for PRs
branches.release.enabled	false	Enables release branch workflows
branches.release.base	main	Base branch for release branches

PR & Merge Behavior

Controls how agents merge pull requests.

pr:
  merge:
    method: squash

Field	Default	What it does
pr.merge.method	squash	How PRs are merged: squash, merge, or rebase

Continuous Integration

Defines commands that regenerate files (snapshots, compiled schemas, auto-generated code) when specific file patterns are modified. Agents run these commands before committing whenever matching files change.

ci:
  generatedFileCommands:
    - name: prompt-snapshots
      filePatterns:
        - "apps/api/src/agents/**"
      command: "cd apps/api && UPDATE_SNAPSHOTS=true bun test ..."

Field	Default	What it does
ci.generatedFileCommands	—	Commands to regenerate files (snapshots, codegen) before committing

See Generated File Commands for a detailed breakdown of this field.

Preview Environments

Configures preview environment URLs so agents can construct and reference deployment links.

preview:
  primaryEnvironment: staging
  environments:
    staging:
      urlTemplate: "https://pr-{prNumber}-staging.example.com"
      backendBaseUrl: "https://api.stage.example.com"

Field	Default	What it does
preview.primaryEnvironment	—	Which environment key to use for preview deploys
preview.environments.<key>.urlTemplate	—	URL pattern for preview environments ({prNumber} is substituted)
preview.environments.<key>.backendBaseUrl	—	Backend API URL for the preview environment

Quality Assurance

Points agents to QA documentation and automation scripts.

qa:
  guidePaths:
    - dashboard/QA.md
  automationPaths:
    - .github/staging-automations/

Field	Default	What it does
qa.guidePaths	—	Paths to QA documentation agents should reference
qa.automationPaths	—	Paths to QA automation scripts agents can execute

Triage & Tracking

Routes automated PR reviews to a specific Obvious project.

triageProjects:
  reviewProjectId: prj_abc123

Field	Default	What it does
triageProjects.reviewProjectId	—	Obvious project ID where automated PR reviews are routed

Complete Field Reference

Field	Default	What it does
branches.defaultBase	main	Default base branch for PRs
branches.release.enabled	false	Enables release branch workflows
branches.release.base	main	Base branch for release branches
pr.merge.method	squash	How PRs are merged: squash, merge, or rebase
ci.generatedFileCommands	—	Commands to regenerate files (snapshots, codegen) before committing
preview.primaryEnvironment	—	Which environment key to use for preview deploys
preview.environments.<key>.urlTemplate	—	URL pattern for preview environments ({prNumber} is substituted)
preview.environments.<key>.backendBaseUrl	—	Backend API URL for the preview environment
qa.guidePaths	—	Paths to QA documentation agents should reference
qa.automationPaths	—	Paths to QA automation scripts agents can execute
triageProjects.reviewProjectId	—	Obvious project ID where automated PR reviews are routed

How Agents Consume config.yml

Agents receive your configuration through two channels.

Preamble Summary

Orchestrators see a compact one-liner summarizing key policy values:

defaultBase=main · release=disabled · merge=squash

Workers see a full table listing every field, its resolved value, and whether the value came from your config or a built-in default.

Shell Environment Variables

Key policy values are injected as environment variables into every shell command agents execute:

Variable	Source field
REPO_POLICY_BRANCH_DEFAULT_BASE	branches.defaultBase
REPO_POLICY_MERGE_METHOD	pr.merge.method
REPO_POLICY_RELEASE_ENABLED	branches.release.enabled
REPO_POLICY_RELEASE_BASE	branches.release.base
REPO_POLICY_PREVIEW_URL	preview.environments.<primary>.urlTemplate
REPO_POLICY_PREVIEW_BACKEND_URL	preview.environments.<primary>.backendBaseUrl
REPO_POLICY_PREVIEW_TIMEOUT_MINUTES	preview.deploy.timeoutMinutes
REPO_POLICY_SNAPSHOT_COMMAND	ci.generatedFileCommands[*].command

Generated File Commands

The ci.generatedFileCommands field is designed for repositories with generated artifacts — test snapshots, compiled GraphQL schemas, auto-generated type definitions, or any file that must be kept in sync with source changes.

When an agent modifies files matching the filePatterns globs, it automatically runs the corresponding command to regenerate dependent files before committing.

Field Breakdown

Each entry under ci.generatedFileCommands supports three fields:

Field	Required	Description
name	No	Human-readable label for this command
filePatterns	No	Glob patterns that trigger the command when matched files change
command	Yes	The shell command to run

Examples

Prompt snapshots — regenerate test snapshots when agent prompt files change:

ci:
  generatedFileCommands:
    - name: prompt-snapshots
      filePatterns:
        - "apps/api/src/agents/modes/prompts/**"
        - "apps/api/src/services/sandbox/skills/**"
      command: "cd apps/api && UPDATE_SNAPSHOTS=true bun test src/agents/modes/prompts/prompts.snapshot.test.ts"

GraphQL codegen — regenerate typed queries when schema files change:

ci:
  generatedFileCommands:
    - name: graphql-codegen
      filePatterns:
        - "**/*.graphql"
      command: "npm run codegen"

Multiple entries are supported — each runs independently based on its own filePatterns.

Config Validation

Agents can validate your config.yml using the built-in CLI:

autobuild-config validate

The validator checks for unknown fields and diagnoses them with suggestions for the correct path. For example, if merge is placed at the top level instead of under pr, the validator identifies the misplacement and points to the correct location.

Run validation after making changes to catch structural errors before agents pick up the file.