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.
Prerequisites
Section titled “Prerequisites”- 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.
GitHub
Section titled “GitHub”Create a ruleset (Settings, Rules, Rulesets, New ruleset, New branch ruleset).
- Add a target "Include by pattern" for
vaultfold, or the name you gave--branch. - 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. - 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. - Leave "Require a pull request before merging" and "Require status checks to pass" off for this branch. Either one blocks every sync.
- If another ruleset targets all branches ("Include all branches",
~ALLin the API, or a*pattern), add an "Exclude by pattern" entry forvaultfoldto 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.
GitLab
Section titled “GitLab”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.
Bitbucket
Section titled “Bitbucket”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.
Verify pushes in CI
Section titled “Verify pushes in CI”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.
Check your setup
Section titled “Check your setup”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.
Current limitations
Section titled “Current limitations”doctorreads rules only for GitHub, and only throughgh. 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.