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.
| Key | Type | Default | Notes |
|---|---|---|---|
schema | integer | required | the version of this file’s format |
requires_ank | version | none | MAJOR.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_budget | integer | 8000 | what context hands a reader, in characters; at least 1 |
claim_ttl_max | duration | 2h | the longest lease a claim is granted, whatever --ttl asks; at least 1s |
claim_ttl_default | duration | 30m | the lease claim grants without --ttl, capped by claim_ttl_max; at least 1s |
default_branch | string | none | the branch carrying the reference state; absent, refs/remotes/origin/HEAD names it |
peers.<name> | path | none | a 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>.run | command | required | what done runs through sh; required in a declared verifier |
verifiers.<name>.timeout | duration | 10m | how long done lets the command run; at least 1s |
verifiers.<name>.default | boolean | false | true writes the verifier into every task ank new task creates |
verifiers.<name>.inputs | list of globs | none | the 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_age | duration | 24h | how 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_jobs | integer | none | how many verifiers one done runs at once, at least 1; absent, the machine’s available parallelism |
verifier_lock | boolean | true | whether 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>.can | list of strings | none | what 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>.cannot | list 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> | string | none | the 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.enforce | off, warn or deny | off | how 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_files | integer | 3000 | check signals a hot corpus holding more entity files |
weight.plane_bytes | integer | 4000000 | check signals claim and proof records weighing more bytes |
guard.corpus | deny or off | deny | what 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.edit | off, warn or claim | warn | what 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[].key | string | required | a 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[].note | string | none | what the key is, for the reader; ank signers migrate puts the comments of a former .ank/allowed_signers here |
signers.<principal>.keys[].valid_before | date | none | YYYY-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 everythingcontext:ank contextfind:ank findclaim:ank claimlog:ank log, which writes an entrydone:ank donenew:task:ank new tasknew:adr:proposed:ank new adr, which writes a proposed ADRnew:spec:proposed:ank new spec, which writes a proposed specadr:accept:ank accepton an ADRspec:accept:ank accepton a specadr:edit-constraint: a change to the constraint of an ADRtask:close:ank closedelete: removing an entityconfig:permissions: a write toroles,identities,permissions,checkorratifyin this file