Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

config.yml keys

Every key .ank/config.yml may carry, with the type of its value and what an absent key means. A key not listed here is refused, and so is a file whose schema is newer than this build reads.

This build reads schema: 1 through schema: 2; a file carrying requires_ank declares schema: 2, and one without it may stay at schema: 1. A duration is <n><unit>, the unit one of s, m, h or d. <name> stands for a key the file chooses; ank config <key> reads and writes each key, signers aside, which ank signers writes.

KeyTypeDefaultNotes
schemaintegerrequiredthe version of this file’s format
requires_ankversionnoneMAJOR.MINOR.PATCH: the oldest ank this corpus needs, compared with the running binary and never with a release; a file carrying it declares schema: 2; absent, no requirement; moved by ank config requires_ank
context_budgetinteger8000what context hands a reader, in characters; at least 1
claim_ttl_maxduration2hthe longest lease a claim is granted, whatever --ttl asks; at least 1s
claim_ttl_defaultduration30mthe lease claim grants without --ttl, capped by claim_ttl_max; at least 1s
default_branchstringnonethe branch carrying the reference state; absent, refs/remotes/origin/HEAD names it
peers.<name>pathnonea peer corpus a scope entry reaches by name: a path to a checkout on disk, relative to this root or absolute, and never a URL; a reader whose layout differs overrides it in their own corpora.yml with ank config --user peers.<identity>.<name> <path>
verifiers.<name>.runcommandrequiredwhat done runs through sh; required in a declared verifier
verifiers.<name>.timeoutduration10mhow long done lets the command run; at least 1s
verifiers.<name>.defaultbooleanfalsetrue writes the verifier into every task ank new task creates
verifiers.<name>.inputslist of globsnonethe files whose content can change the result, relative to the root; absent, the whole tree; written as one flow sequence, never empty
proof.reuse_max_ageduration24hhow old a passing run recorded under <git-common-dir>/ank/runs/ may be for done to reuse it rather than run the verifier again, at least 1s; done --fresh reuses nothing
verifier_jobsintegernonehow many verifiers one done runs at once, at least 1; absent, the machine’s available parallelism
verifier_lockbooleantruewhether done waits for the verifiers another done of the repository is running, in any of its worktrees, before it starts its own; false lets them run at the same time (ADR-eab130f731f3)
roles.<name>.canlist of stringsnonewhat the role may do, each entry a word of the role vocabulary below; a list other than ["*"] forbids every act it omits, so can: [] forbids every act, while absent the key restricts nothing; written as one flow sequence by ank config roles.<name>.can, which declares the role when it is absent, and --unset leaves the role with no can key
roles.<name>.cannotlist of strings[]what the role may not do, each entry a word of the role vocabulary below; written by ank config roles.<name>.cannot
identities.<identity>stringnonethe role of an identity, one roles declares; one absent from the table is an agent; written by ank config identities.<identity> <role> and removed by --unset
permissions.enforceoff, warn or denyoffhow roles apply: off not at all, warn and deny as ADR-ddbe024ca7f2 sets; ank init writes warn into the corpus it creates; moved by ank config permissions.enforce
weight.hot_filesinteger3000check signals a hot corpus holding more entity files
weight.plane_bytesinteger4000000check signals claim and proof records weighing more bytes
guard.corpusdeny or offdenywhat ank hooks run does with a file tool aimed under the corpus directory: deny refuses it, off lets it through; a launch environment may set ANK_GUARD_CORPUS tighter, never looser (ADR-43cbb20dcbf1)
guard.editoff, warn or claimwarnwhat ank hooks run does with an edit no live claim of the identity covers: off says nothing, warn lets it through naming the path, claim refuses it; a launch environment may set ANK_GUARD_EDIT tighter, never looser (ADR-43cbb20dcbf1)
signers.<principal>.keys[].keystringrequireda key allowed to ratify, gpg <fingerprint> or <ssh key type> <base64>; the block is written by ank signers, never by ank config (ADR-5c6db7a161b8)
signers.<principal>.keys[].notestringnonewhat the key is, for the reader; ank signers migrate puts the comments of a former .ank/allowed_signers here
signers.<principal>.keys[].valid_beforedatenoneYYYY-MM-DD: the key ratifies nothing committed from that day on, UTC, and what it signed before stays verified; absent, the key has no end

The role vocabulary

Every entry of roles.<name>.can and roles.<name>.cannot is one of these words, and ank check faults config.yml on a word outside them. An act is forbidden to an identity when its role lists it under cannot, or has a can list other than ["*"] that omits it; an identity absent from identities has the role agent.

  • *: every act; can: ["*"] is the only list that allows everything
  • context: ank context
  • find: ank find
  • claim: ank claim
  • log: ank log, which writes an entry
  • done: ank done
  • new:task: ank new task
  • new:adr:proposed: ank new adr, which writes a proposed ADR
  • new:spec:proposed: ank new spec, which writes a proposed spec
  • adr:accept: ank accept on an ADR
  • spec:accept: ank accept on a spec
  • adr:edit-constraint: a change to the constraint of an ADR
  • task:close: ank close
  • delete: removing an entity
  • config:permissions: a write to roles, identities, permissions, check or ratify in this file