Skip to content

Protect the vault branch

A vault inside a code repository lives on its own branch, vaultfold by default. Every member pushes to it directly, and every vaultfold client checks every event's signature, so a pull request would only make a write wait for a human without making it safer. What a forge can add is a second layer: keep non-members from writing, and stop anyone from rewriting or deleting the branch.

Without these rules the vault is still safe, because clients reject anything that is unsigned or not allowed by the vault's policy. The rules make a forgery fail at the forge instead of at every client.

  • A vault on its own branch (see store and read).
  • Admin rights on the repository, to create rules.
  • The names of the vault's members (vaultfold member list) as users or a team on the forge.

Create a ruleset (Settings, Rules, Rulesets, New ruleset, New branch ruleset).

  1. Add a target "Include by pattern" for vaultfold, or the name you gave --branch.
  2. Turn on "Restrict creations", "Restrict updates", "Restrict deletions" and "Block force pushes". Optionally turn on "Require linear history", which matches what vaultfold writes, and "Require signed commits", which needs every member to set commit.gpgSign.
  3. Add a bypass list, allowed to bypass always (not only for pull requests), holding exactly the vault's members: a team, or the narrowest role that covers them. Only they can create, update and push the branch. Keep it in step with vaultfold member list.
  4. Leave "Require a pull request before merging" and "Require status checks to pass" off for this branch. Either one blocks every sync.
  5. If another ruleset targets all branches ("Include all branches", ~ALL in the API, or a * pattern), add an "Exclude by pattern" entry for vaultfold to it. Otherwise the vault branch inherits that ruleset's pull request requirement.

If your plan has no rulesets for private repositories, use classic branch protection on vaultfold with "Restrict who can push to matching branches" if it is offered (repositories owned by an organization). If it does not, there is no forge protection, and the signatures remain the authority.

Protect the branch (Settings, Repository, Protected branches). Set "Allowed to push and merge" ("Allowed to push" in older versions) to the vault's members, leave "Allowed to force push" off, and ignore "Allowed to merge". Choosing individual users or groups needs GitLab Premium; on Free choose the narrowest role. Do not set it to "No one", which forces every write through a merge request.

Restrict the vault branch so that only the vault's members have write access (Bitbucket Cloud: Repository settings, Branch restrictions; Bitbucket Data Center: Branch permissions). Do not require pull requests (on Data Center, leave "Prevent changes without a pull request" off), and block history rewriting and deletion.

The CI verification action fails a workflow when an event is not allowed by the vault's policy, for example a write by a revoked key. Trigger it on push to the vault branch, and on pull_request as well for a vault kept on a code branch, so an unauthorized event raises an alert at the forge as well as being rejected by clients. The action is specified but not built yet, so only its trigger is settled today.

A CI job registers the vault with vaultfold vault add <name> . --branch vaultfold, which fetches the vault branch with the job's token, and then reads it with vaultfold run. On GitHub Actions that needs contents: read, and the job's identity must be a member of the vault.

vaultfold init and vaultfold doctor read the rules with the GitHub CLI (gh) when it is installed and signed in. doctor reports rules that would block sync as sync-branch-protected (an error) and says sync-branch-unchecked when it could not look. A push that a forge refuses exits 4 with sync-protected, quotes the forge's message and keeps your events queued. The next vaultfold sync pushes them once the rule allows it.

  • doctor reads rules only for GitHub, and only through gh. For GitLab and Bitbucket a refused push is still recognized and reported.
  • Classic branch protection is reported as a warning, because its details need admin rights to read.
  • The CI verification action does not exist yet.