Commit Signing

Git creates each commit signature. Code Storage checks the signature when a verify-sig ref policy applies to an update. The Signing Keys page stores public keys for your organization. A registered key does not enable a check by itself.

How the parts work together

Part	Purpose
Git	Create an OpenPGP or SSH signature in the commit object.
Signing Keys	Store the public keys that Code Storage trusts for your organization.
`verify-sig` ref policy	Require a valid signature when a token updates a matched ref.
`getCommit()`	Return the signature and its exact payload for a client check.

Require signed commits

1. Create a signed commit

Configure Git for OpenPGP or SSH signatures. Then use -S to sign a commit.

git commit -S -m "Add the release manifest"
git log --show-signature -1

2. Register the public key

Open Signing Keys in the dashboard. Select New signing key, then paste an OpenPGP or SSH public key. Signing keys belong to the organization. Code Storage reads the current key list for each ref update.

3. Add `verify-sig` to a ref policy

This policy requires a registered signature on each commit that enters main.

const url = await repo.getRemoteURL({
  permissions: ['git:read', 'git:write'],
  refPolicies: [{ pattern: 'main', ops: ['verify-sig'] }],
});

url = await repo.get_remote_url(
    permissions=["git:read", "git:write"],
    ref_policies=[{"pattern": "main", "ops": ["verify-sig"]}],
)

url, err := repo.RemoteURL(ctx, storage.RemoteURLOptions{
    Permissions: []storage.Permission{storage.PermissionGitRead, storage.PermissionGitWrite},
    RefPolicies: storage.RefPolicyList{
        {Pattern: "main", Ops: storage.Ops{storage.OpVerifySig}},
    },
})

Use ops: ['verify-sig', 'no-force-push'] to require signatures and reject a history rewrite. See Ref Policies for rule order, patterns, and ephemeral refs.

4. Push the signed commit

Use the URL with this policy as a Git remote. Code Storage rejects the complete update if one introduced commit fails the check.

What Code Storage checks

Code Storage checks commits that the update introduces to the matched ref.

For a new ref, Code Storage checks every commit that the new tip can reach.
For a ref that already exists, Code Storage checks commits that its new tip can reach but its prior tip cannot reach.
Code Storage checks a commit again when it first enters another protected ref.

Code Storage rejects the update in these cases:

A commit has no signature.
No registered key matches the signature.
The signature data is invalid or uses an unsupported format.
The organization has no registered signing keys.

A ref deletion introduces no commits. The verify-sig operation does not reject that deletion.

Server-created commits

Do not target a verify-sig ref with createCommit, createCommitFromDiff, or merge. These methods create unsigned commits.

Use a signed Git push when a ref requires a signature. Code Storage does not create a signature for a server-created commit.

Read signature data

You can read signature data without a ref policy. getCommit() returns an armored signature and the exact payload for a signed commit.

const { commit } = await repo.getCommit({ sha: 'abc123def456' });

if (commit.signature && commit.payload) {
  checkSignature(commit.payload, commit.signature);
}

result = await repo.get_commit(sha="abc123def456")
commit = result["commit"]

if commit.get("signature") and commit.get("payload"):
    check_signature(commit["payload"], commit["signature"])

result, err := repo.GetCommit(ctx, storage.GetCommitOptions{
	SHA: "abc123def456",
})

if result.Commit.Signature != "" && result.Commit.Payload != "" {
	checkSignature(result.Commit.Payload, result.Commit.Signature)
}

This method does not return a trust result. Check the pair with an OpenPGP or SSH library. See the getCommit() reference for the complete response.

Remove a key

Delete a key. Code Storage rejects a signature from that key on the next ref update. The deletion does not change stored commits or their signatures.

Getting Started

Features

Workflows

Reference

How the parts work together

Require signed commits

1. Create a signed commit

2. Register the public key

3. Add `verify-sig` to a ref policy

4. Push the signed commit

What Code Storage checks

Server-created commits

Read signature data

Remove a key

​How the parts work together

​Require signed commits

​1. Create a signed commit

​2. Register the public key

​3. Add verify-sig to a ref policy

​4. Push the signed commit

​What Code Storage checks

​Server-created commits

​Read signature data

​Remove a key

How the parts work together

Require signed commits

1. Create a signed commit

2. Register the public key

3. Add `verify-sig` to a ref policy

4. Push the signed commit

What Code Storage checks

Server-created commits

Read signature data

Remove a key