Skip to content

Project Configuration

goga reads project configuration from .goga/config.yml in the project root. This file is created by goga init and can be edited manually.

The page covers the global fields and the sections that belong to no single domain. Every domain-owned section (build, pipeline, tools, usages, lint, topics) is documented in full in its domain's Configuration page — see Domain sections.

The authored file is the source of these values: installed tool packages may additionally amend the configuration in memory at the load moment of a host-side command (see Hooks) — the authored file itself is never modified by that mechanism.

File location

.goga/config.yml

The config loader looks for this file relative to the current working directory.

For the machine-wide ~/.goga/config.yml, see Home Configuration. To read values back from the command line, see goga config.

Example configuration

language: python
image: qarium/goga-python-3.14:2.0
# dockerfile: .goga/Dockerfile     # optional — when set, `--update` builds from this Dockerfile instead of pulling

build:                             # two-part: the root is the tasks-pass settings
  agent: claude                    # the tasks-pass executor
  env:
    ANTHROPIC_API_KEY: sk-ant-...
  session_timeout: 30m
  idle_timeout: 10m
  max_iterations: 10
  # review:                       # optional review-pass settings
  #   skip: false                 # true → tasks-only run
  #   agent: codex                # review executor (inherits build.agent when unset)
  #   roles: [quality, testing]   # reviewer composition; absent/[] → full default set
  #   env:                        # review-pass env layer (requires agent when non-empty)
  #     ANTHROPIC_MODEL: reviewer
  #   base_ref: origin/1.2.x      # review diff base — branch name or commit hash
  #   strategy: medium            # full | medium | short
  #   max_iterations: 3           # review-pass iteration cap (never inherits the root value)
  #   additional:
  #     patience: 3               # stop the external review after N unchanged rounds
  # proxy: http://corp:3123        # optional HTTP/HTTPS proxy URL for the build container
  # hosts:                         # optional docker run --add-host entries
  #   foo.local: 127.0.0.1

pipeline:
  agent: claude
  env:
    ANTHROPIC_API_KEY: sk-ant-...
  # proxy: http://corp:3123        # optional HTTP/HTTPS proxy URL for the pipeline container
  # hosts:                         # optional docker run --add-host entries
  #   foo.local: 127.0.0.1

codemanifest:
  usages:
    conventions: .goga/usages/conventions.md

  annotations: |
    Follow the project `conventions` for all code generation.

# tools: optional — declared tools are installed together by `goga install`
# tools:
#   viewer: latest        # → no specifier (pip selects newest)
#   mkdocs: 1.0.x         # → ~=1.0.0
#   mypy: 1.x             # → ~=1.0
#   go: 1.0.1             # → ==1.0.1

# usages: optional — git dependencies whose cell-level .usages/ are synced by `goga usages sync` and status-checked by `goga usages status`
# usages:
#   libs:
#     click:
#       git: https://github.com/pallets/click.git
#       ref: 8.1.7         # optional — branch, tag, or commit; omit for the default branch
#       root: docs         # optional — subpath inside the repo to walk .usages from; omit for the clone root

# lint: optional — directories ignored by `goga lint` (exact relative paths, no glob)
# lint:
#   ignore:
#     - .venv/
#     - build/dist

# topics: optional — the topic exchange base and per-command templates (`goga topics`)
# topics:
#   base_ref: origin/main                     # base of the topic exchange (update/propagate), creation, and the clear scope
#   create:
#     commit: "feat: {slug} todo"             # commit template of the published todo commit ({slug} optional)
#   update:
#     strategy: merge                         # merge | rebase | ff-else-merge | ff-else-rebase
#     commit: "Update {slug} from {base}"     # merge-commit template of the update
#   propagate:
#     strategy: merge                         # merge | ff | squash
#     commit: "Deliver {slug} into {base}"    # delivery-commit template of the propagation

Fields reference

Top-level

Field Type Required Description
language string Yes Project language. One of: python, golang, kotlin, swift, javascript
image string No Docker image used by goga build and goga pipeline (e.g. qarium/goga-python-3.14:2.0). Consumers raise an error when it is unset. The deprecated build.image field is silently ignored — set this top-level field instead
dockerfile string No Path to a project Dockerfile. When set, goga build --update and goga pipeline --update build the image locally from this Dockerfile (fatal on build failure). When unset (default), --update pulls image from the registry instead (non-fatal warning on pull failure)
commands mapping No Reserved for future prompt customization. Defaults to {}
codemanifest mapping No Global codemanifest configuration — see codemanifest
build mapping No Build pipeline settings — see Build — Configuration
pipeline mapping No Pipeline execution settings — see Pipelines — Configuration
tools mapping No goga-tool version declarations for bulk install — see Install — Configuration
usages mapping No Git dependencies of cell-level usages — see Usages — Configuration
lint mapping No Linter ignore list — see Lint — Configuration
topics mapping No Topic exchange base, per-command commit templates, and the update/propagate strategies — see Topics — Configuration

Domain sections

Each domain-owned section is documented in full — every field, typing rule, and CLI precedence — in its domain's Configuration page:

Section Domain Consumed by
build (incl. review) Build goga build
pipeline Pipelines goga pipeline
tools Install goga install (bulk mode)
usages Usages goga usages sync / goga usages status
lint Lint goga lint
topics Topics goga topics create, goga topics clear, goga topics update, goga topics propagate, goga topics board (the divergence base)

codemanifest

The codemanifest section is global — it belongs to no single domain. It feeds every CODEMANIFEST of the project (see Cells).

Field Type Required Description
usages mapping No Named practices available in CODEMANIFEST files. Format: {name: path/to/file.md}. Defaults to {}
annotations string No Free-text instructions for AI agents. Defaults to None

Pre-built Docker images

goga provides prebuilt language images for build execution:

Language Images
Python qarium/goga-python-3.10:2.0 through qarium/goga-python-3.14:2.0
Go qarium/goga-golang-1.23:2.0 through qarium/goga-golang-1.26:2.0
JavaScript qarium/goga-node-22:2.0, qarium/goga-node-24:2.0
Kotlin qarium/goga-kotlin-2.0:2.0 through qarium/goga-kotlin-2.3:2.0
Swift qarium/goga-swift-6.0:2.0 through qarium/goga-swift-6.2:2.0

Validation errors

The config loader raises specific exceptions for invalid configuration:

Error Cause
FileNotFoundError .goga/config.yml does not exist or is empty
KeyError Missing required field (language)
ValueError Invalid field value (wrong type, empty string, non-mapping where mapping expected); the same per-field pattern covers the pipeline (pipeline.env / proxy / hosts), codemanifest, lint, tools ('tools' must be a mapping in .goga/config.yml), and usages sections (including usages.<group>.<dep>.git is required for a missing dep git). build adds: a non-string agent / session knob / prompts_dir / agents_dir / review string field (build.agent must be a string in .goga/config.yml, and the same pattern for every session knob and build.review.* string field), a non-int max_iterations including a YAML boolean, a non-mapping env (build.env must be a mapping in .goga/config.yml, build.review.env likewise), env with non-string keys/values (build.env must have string keys and values), a non-mapping build.review (build.review must be a mapping in .goga/config.yml), a non-bool build.review.skip (a YAML 1 is rejected), roles that is not a list of strings, a non-mapping build.review.additional, or a non-int patience/max_iterations of the additional block including a YAML boolean. The retired keys (worktree, skip_finalize, codex_review, task_executor, review_executor) raise nothing — they are silently ignored. topics adds: a non-mapping section ('topics' must be a mapping in .goga/config.yml), a non-mapping sub-section ('topics.create' must be a mapping in .goga/config.yml, and the same for topics.update and topics.propagate), or a non-string field (topics.base_ref must be a string in .goga/config.yml, topics.create.commit must be a string in .goga/config.yml, topics.update.strategy must be a string in .goga/config.yml, topics.update.commit must be a string in .goga/config.yml, topics.propagate.strategy must be a string in .goga/config.yml, topics.propagate.commit must be a string in .goga/config.yml). The retired topics.publish_commit key raises nothing — it is silently ignored

Implementation details

Configuration is loaded as immutable frozen dataclasses (frozen=True, kw_only=True). Once loaded, the ProjectConfig object cannot be modified. This ensures consistent behavior across the build pipeline.