bitcd.yaml

Sections

Every file starts with schema: bitcd/v1. These sections are the whole vocabulary. An unknown field is an error, except inside free-form data you supply: a connector's config, an enum's map.

* A file needs at least one intent type, value or fleet. Locks alone are not enough.

A quorum is always four fields: threshold, role, min_humans and max_per_operator (0 means no cap). allow_open cannot be written by hand. Open access exists only where the file's structure calls for it: a fleet's lease, a lock, or one lock's value.

Example

The development organization beside the CLI, bitcd-core/core/example/bitcd.yaml, with addresses shortened and each signer on one line.

schema: bitcd/v1
org: chainops
version: 1
naming: literal            # every name fits in 31 characters — checked at compile
ceremony:
  renounce: true           # give up ownership when setup finishes; after that, new
                           # policies need a prefix with its own SET_POLICY gate

cast:
  roles: [OPERATOR, EXEC_K8S, OPS_PROPOSER]
  signers:
    agent1:      { address: "0x078662…c8b1", human: true,  operator: OP_A,   role: OPERATOR }
    agent2:      { address: "0x049dfb…f38e", human: true,  operator: OP_B,   role: OPERATOR }
    agent3:      { address: "0x04f348…27d3", human: false, operator: OP_A,   role: OPERATOR }
                 # shares agent1's operator, so the per-operator cap applies to them together
    k8s-bridge:  { address: "0x003736…e06f", human: false, operator: OP_K8S, role: EXEC_K8S }
                 # the connector's own executor role
    ops-console: { address: "0x014fc4…492d", human: false, operator: OP_OPS, role: OPS_PROPOSER }
                 # no policy names this role: the web app's key can propose, but its approvals never count

connectors:
  dev-cluster:
    type: k8s-rbac         # which connector package does the work
    role: EXEC_K8S
    executors: [k8s-bridge]
    config:                # non-secret; copied into the manifest as-is
      context: k3d-bitcd-rbac
    credentials: {}        # environment-variable names only — never the secrets themselves

storage:
  bucket: bitcd-tfstate
  endpoint_env: BITCD_S3_ENDPOINT

intent_types:
  k8s-access:              # “give this account these permissions, for this long”
    connector: dev-cluster
    prefix: k8s/rbac
    schema: k8srbacgrant/v1
    key: "k8s/rbac/{ns}/{name}"   # longest possible key: 10 + 6 + 13 = 29 characters
    params:
      ns:      { type: enum, label: Namespace, values: [team-a] }
      name:    { type: name, label: Grant name, max_len: 13, format: key-slug }
      subject: { type: subject, label: Who, kinds: [User, Group, ServiceAccount] }
      pset:
        type: enum
        label: Permission set
        values: [read-secrets]
        map:                     # each named set maps to fixed provider data
          read-secrets: { roleKind: Role, roleName: read-secrets }
    ttl:                          # how long a grant lasts, in chain time (the executor revokes it)
      required: false
      default: 24h
      max: 720h
    quorum:                       # who approves a grant: two operators, one of them human,
      threshold: 2                # at most one per operator
      role: OPERATOR
      min_humans: 1
      max_per_operator: 1
    revoke: same                  # revoking takes the same quorum as granting
    attest: { k: 1 }              # one executor report is enough
    summon_human: false            # a person already signs every grant here
    mutable: true                 # this prefix's policies can be changed later

reserved_prefixes:                # room to grow: only the policy-setting gate is created now
  - prefix: aws/iam
    set_policy: { threshold: 2, role: OPERATOR, min_humans: 1, max_per_operator: 1 }

baseline:
  unmanaged: untouched            # executors leave everything they don't manage alone
  drift_scope: managed-keys

manifest:                         # where the compiled definition lives, and who may change it
  key: sys/manifest
  quorum: { threshold: 2, role: OPERATOR, min_humans: 1, max_per_operator: 1 }

Intent types

An intent type is a request form. Its key template, built from parameters in {braces}, decides where each grant is stored. Its params decide what can be filled in. There is no expression language: each parameter is one of six types, and a new need becomes a new type.

Every parameter also takes label (required), help, required (default true) and default. A default is checked like a submitted value and must sit within the field's own min and max. Parameters used in the key must be enum or name and required, so the compiler can prove the longest key fits in 31 characters. Values are checked character by character when a request is made; format: key-slug is the stricter, lowercase form.

The rest of an intent type:

• ttl, optional. Without it, requests cannot set a TTL. With it, max is required, required defaults to false, and leaving out default lets a request be permanent.
• quorum.
• revoke: same by default, or its own quorum, never weaker.
• attest: how many executors must agree, {k: 1} by default.
• summon_human: true lets any voter demand a person's signature on one proposal, after which no quorum can commit without it. False when left out. See [person-reachable].
• mutable, always stated. mutable: false locks the prefix's policies once setup ends and needs immutable_ack: true beside it.

Fleets, locks and values

Three sections need no connector. An agent fleet or a sign-off gate lives in the same file:

At most one prefix can have a lease-written value. Such a value has no quorum behind it, so a takeover has no governed way back; the compiler allows one for that reason. The contract enforces policies per prefix: the keys and schemas you declare describe what you intend to store there, and anyone meeting a prefix's policy can write other keys under it.

Keys in these sections are fixed strings, must sit under their prefix, and schemas follow name/vN. Values need an explicit mutable (with immutable_ack: true when false); summon_human defaults to false.

What the compiler seeds

From the file, the compiler builds the complete list of signers and policies to seed:

• Each intent type: SET_VALUE (its quorum), TOMBSTONE_VALUE (its revoke quorum), SET_STATUS (its executor role and attest.k), and SET_POLICY if mutable.
• Values, fleets and locks: the policies in the table above. Mutable locks get a SET_POLICY gate; a fleet's lease prefix does not. A derived policy-changing gate always requires at least one human.
• Executor reports (SET_STATUS): the executor role, threshold = attest.k, no human requirement, and a per-operator cap of 1 when k is above 1.
• Global gates for managing signers and policies ('GLOBAL' SET_ROLE and SET_POLICY) at the manifest quorum's strength, so signers can be rotated after setup.
• The manifest's own SET_VALUE, TOMBSTONE_VALUE and SET_POLICY, and a SET_POLICY-only gate on each reserved prefix.

Once ownership is renounced, a prefix without a SET_POLICY gate can never get new policies. The declared prefixes plus the reserved ones are the boundary of the organization from then on. Anything outside them needs a new deployment.

The CLI

One command, bitcd: bitcd-core/core/bin/bitcd.mjs, part of @bitcd/core. It needs only the bitcd-core checkout.

The commands that talk to a chain or a store share these options. validate and plan need none of them; diff needs no keystore. An unknown option is refused before anything happens.

Before you rely on it

• It signs with a local keystore. Writing commands use the --keys file; publish-manifest, propose-changes and --approve-dev approve and commit with the signers in it that are active on chain. For real signers, propose without approving (publish-manifest --no-commit, propose-changes --no-commit) and have people sign with their own keys.
• Setup does not read back what it wrote. Run apply-ceremony with renounce: false, check with bitcd diff, then set renounce: true and run it again. Onboarding walks through it.
• A deployment record belongs to one chain. Every command that talks to the chain checks that a contract lives at the recorded address and, when the record names a class, that it runs that class. Otherwise it refuses. After restarting a devnet, delete the old record. Keep one record per network.
• Removing a policy from the file does not remove it from the chain. Removed signers are deactivated. Policies can only be made stricter, never deleted.
• A manifest approved outside the CLI needs one more step. After it commits, run publish-manifest again to put it in place; executors halt until you do.
• The store endpoint comes from --s3-endpoint, else the variable named in storage.endpoint_env, else BITCD_S3_ENDPOINT.
• The TTL clock starts when the request is made, not when it is approved. version in the file is your own number; the chain keeps its own revision count.

Lints

validate, plan and every command that loads the file run these checks. Each one is an error and stops the command. Together they check that every quorum can be met by the declared cast, not that the right people hold the keys. The code in brackets starts the message.

The schema checks catch the rest without a code: secret-looking values anywhere and secret-looking field names outside credentials (matched by pattern, so not exhaustive), a manifest quorum without a human, an intent type or value that does not state mutable, and any unknown field.

After setup

Later changes go through propose-changes and the quorums you declared. You can make governance stricter, add signers, change policies on mutable prefixes and start using a reserved prefix. You cannot create policies on a prefix without its own SET_POLICY gate, and you cannot loosen a governance policy. An organization that outgrows its prefixes needs a new deployment, so reserve a few.