You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Sign release artifacts and verify commit signatures in CI pipelines. Auths uses a limited-capability device key model so your root identity never leaves your machine.
3
+
Sign every commit. Verify every release. Auths uses a limited-capability device key model so your root identity never leaves your machine — the CI runner only ever holds a scoped, revocable token.
4
4
5
-
## Concepts
5
+
---
6
6
7
-
CI signing in Auths works through device delegation:
7
+
## GitHub Actions
8
8
9
-
1. You create a **CI device key** on your local machine.
10
-
2. You **link** that device to your identity with restricted capabilities (e.g., `sign_release` only).
11
-
3. The device key and a snapshot of your identity repository are packaged as GitHub Secrets.
12
-
4. In CI, the runner restores the identity bundle and signs artifacts using the CI device key.
13
-
5. You can **revoke** the CI device at any time without affecting your root identity.
9
+
The fastest path. Two actions, one secret, zero ongoing maintenance.
14
10
15
-
## One-time setup with `auths ci setup`
16
-
17
-
Run this from any repo with a git remote:
11
+
### Setup (one-time)
18
12
19
13
```bash
20
14
auths ci setup
21
15
```
22
16
23
-
This command will:
17
+
This creates a scoped CI device key, links it to your identity with `sign_release` capability, and sets `AUTHS_CI_TOKEN` on your repo via the `gh` CLI. If `gh` isn't authenticated, it prints the token value to paste in manually under **Repository → Settings → Secrets → Actions**.
18
+
19
+
### Sign commits
24
20
25
-
1.**Verify your identity exists** and read your identity DID and key alias.
26
-
2.**Generate a CI device key** (Ed25519) and link it to your identity with `sign_release` capability.
27
-
3.**Package everything** into a single `AUTHS_CI_TOKEN` JSON secret containing the passphrase, encrypted keychain, identity repo snapshot, and verification bundle.
28
-
4.**Set the secret** on your forge automatically via the `gh` CLI (GitHub) or print the token for manual setup (other forges).
21
+
Add to any workflow that pushes to `main`:
29
22
30
-
If the `gh` CLI is not authenticated, the command prints the token value for you to add manually via **Repository > Settings > Secrets > Actions > New secret**.
23
+
```yaml
24
+
- uses: auths-dev/sign@v1
25
+
with:
26
+
token: ${{ secrets.AUTHS_CI_TOKEN }}
27
+
commits: 'HEAD~1..HEAD'
28
+
```
31
29
32
-
### Rotating the token
30
+
### Verify commits
33
31
34
-
To refresh the token (new TTL, updated identity repo) without regenerating the device key:
32
+
Add to every pull request and push:
35
33
36
-
```bash
37
-
auths ci rotate
34
+
```yaml
35
+
- uses: auths-dev/verify@v1
36
+
with:
37
+
fail-on-unsigned: true
38
+
post-pr-comment: 'true'
39
+
github-token: ${{ secrets.GITHUB_TOKEN }}
38
40
```
39
41
40
-
### Re-running setup
42
+
No token needed — the action reads `.auths/allowed_signers` from your repo.
43
+
44
+
### Show it off
41
45
42
-
If you already have a `ci-release-device` key, `auths ci setup` detects it and reuses the existing key while regenerating the token.
46
+
Once both workflows are running, add badges to your README:
The `auths sign <file>` command detects that the target is a file (not a Git ref) and creates an attestation file at `<file>.auths.json` containing the cryptographic signature, the signer's DID, and the artifact digest.
90
+
Signing produces `myproject.tar.gz.auths.json` alongside the artifact — ship both so downstream consumers can verify.
82
91
83
-
## Signing Git commits in CI
92
+
### Rotating or revoking access
84
93
85
-
To sign Git commits (not just artifacts), configure Git to use Auths as the signing program:
94
+
To refresh the token (new TTL, updated identity snapshot):
After revocation the CI key can no longer produce valid attestations, even if the secret is still in GitHub.
101
107
102
-
Use `auths verify` to check commit signatures. For CI, the `--identity-bundle` flag enables stateless verification without needing access to the full identity repository:
108
+
---
103
109
104
-
```bash
105
-
# Export a bundle on your local machine (one-time)
106
-
auths id export-bundle \
107
-
--alias main \
108
-
--output identity-bundle.json \
109
-
--max-age-secs 7776000 # 90 days
110
+
## Manual setup (other CI platforms)
111
+
112
+
Running GitLab CI, CircleCI, Bitbucket Pipelines, or your own runner? The same `AUTHS_CI_TOKEN` approach works anywhere you can set an environment variable and install a binary.
113
+
114
+
### Install the CLI
115
+
116
+
```yaml
117
+
# Example: generic shell step
118
+
- name: Install auths
119
+
run: |
120
+
curl -fsSL https://get.auths.dev | sh
121
+
echo "$HOME/.auths/bin" >> $GITHUB_PATH # or equivalent PATH export
110
122
```
111
123
112
-
Commit this bundle to your repository (e.g., `.auths/identity-bundle.json`), then verify in CI:
124
+
### Sign commits
125
+
126
+
Configure Git to use Auths as the signing program, then any `git commit` in the workflow is signed:
113
127
114
128
```yaml
115
-
- name: Verify commit signatures
116
-
run: |
117
-
auths verify HEAD --identity-bundle .auths/identity-bundle.json
For higher assurance, combine Auths attestation chains with GitHub Actions OIDC tokens. This creates a two-factor proof: the request must originate from both a valid KERI identity holder and a specific GitHub Actions workflow.
@@ -204,15 +238,3 @@ steps:
204
238
```
205
239
206
240
The bridge verifies the KERI attestation chain, validates the GitHub OIDC token against GitHub's JWKS endpoint, and cross-references the GitHub `actor` claim against the expected KERI identity. If both pass, it issues a bridge JWT.
207
-
208
-
## Revoking CI access
209
-
210
-
To revoke a CI device at any time:
211
-
212
-
```bash
213
-
auths device revoke \
214
-
--device <ci-device-did> \
215
-
--key <your-key>
216
-
```
217
-
218
-
The device DID and identity key alias are printed by `auths ci setup` when the device is created. After revocation, the CI device key can no longer produce valid attestations, even if the secrets remain in GitHub.
0 commit comments