|
1 | 1 | # auths-dev/sign |
2 | 2 |
|
3 | 3 | [](https://github.com/auths-dev/verify) |
4 | | -[](https://github.com/auths-dev/sign/actions/workflows/verify-commits.yml?query=branch%3Amain+event%3Apush) |
5 | | -[](https://github.com/auths-dev/sign/actions/workflows/sign-commits.yml?query=branch%3Amain) |
6 | 4 |
|
7 | | -Sign build artifacts in CI with [Auths](https://github.com/auths-dev/auths) identity keys. Produces `.auths.json` attestation files that anyone can verify. |
| 5 | +Sign build artifacts and commits in CI using ephemeral keys. **No secrets needed.** |
8 | 6 |
|
9 | | -## Quick start |
| 7 | +## Quick Start |
10 | 8 |
|
11 | 9 | ```yaml |
12 | 10 | - uses: auths-dev/sign@v1 |
13 | 11 | with: |
14 | | - token: ${{ secrets.AUTHS_CI_TOKEN }} |
15 | | - files: 'dist/index.js' |
16 | | - verify: true |
| 12 | + files: | |
| 13 | + dist/*.tar.gz |
| 14 | + dist/*.zip |
17 | 15 | ``` |
18 | 16 |
|
19 | | -This signs `dist/index.js`, creates `dist/index.js.auths.json`, and verifies the signature in one step. |
| 17 | +No tokens. No secrets. The action generates a throwaway key per run, signs your artifacts, and discards the key. Trust is anchored to the commit, not to a CI credential. |
20 | 18 |
|
21 | | -## Setup |
| 19 | +## How It Works |
22 | 20 |
|
23 | | -### 1. Install the Auths CLI |
| 21 | +1. Installs the `auths` CLI |
| 22 | +2. Runs `auths artifact sign --ci --commit $GITHUB_SHA` for each matched file |
| 23 | +3. Produces `.auths.json` attestation files alongside your artifacts |
| 24 | +4. Verifiers trace: artifact ← ephemeral key ← commit SHA ← maintainer signature |
24 | 25 |
|
25 | | -```bash |
26 | | -brew tap auths-dev/auths-cli |
27 | | -brew install auths # macOS |
28 | | -# or download from https://github.com/auths-dev/auths/releases |
29 | | -``` |
30 | | - |
31 | | -### 2. Initialize your identity (if you haven't already) |
32 | | - |
33 | | -```bash |
34 | | -auths init |
35 | | -``` |
36 | | - |
37 | | -### 3. Set up CI secrets |
| 26 | +## Usage |
38 | 27 |
|
39 | | -From the repo you want to sign artifacts in: |
| 28 | +### Sign release artifacts |
40 | 29 |
|
41 | | -```bash |
42 | | -auths ci setup |
| 30 | +```yaml |
| 31 | +- name: Sign artifacts |
| 32 | + uses: auths-dev/sign@v1 |
| 33 | + with: |
| 34 | + files: | |
| 35 | + dist/*.tar.gz |
| 36 | + dist/*.zip |
| 37 | + note: "Release ${{ github.ref_name }}" |
43 | 38 | ``` |
44 | 39 |
|
45 | | -This creates a limited-capability CI device key and sets a single `AUTHS_CI_TOKEN` GitHub secret automatically. |
46 | | - |
47 | | -### 4. Add the action to your release workflow |
| 40 | +### Sign commits |
48 | 41 |
|
49 | 42 | ```yaml |
50 | | -name: Release |
51 | | -
|
52 | | -on: |
53 | | - push: |
54 | | - tags: ['v*.*.*'] |
55 | | -
|
56 | | -permissions: |
57 | | - contents: write |
58 | | -
|
59 | | -jobs: |
60 | | - release: |
61 | | - runs-on: ubuntu-latest |
62 | | - steps: |
63 | | - - uses: actions/checkout@v4 |
64 | | -
|
65 | | - - name: Build |
66 | | - run: npm run build # or your build command |
67 | | -
|
68 | | - - name: Sign artifacts |
69 | | - uses: auths-dev/sign@v1 |
70 | | - with: |
71 | | - token: ${{ secrets.AUTHS_CI_TOKEN }} |
72 | | - files: 'dist/*.js' |
73 | | - verify: true |
74 | | - note: 'Release ${{ github.ref_name }}' |
75 | | -
|
76 | | - - name: Create release |
77 | | - uses: softprops/action-gh-release@v2 |
78 | | - with: |
79 | | - files: | |
80 | | - dist/*.auths.json |
| 43 | +- name: Sign commits |
| 44 | + uses: auths-dev/sign@v1 |
| 45 | + with: |
| 46 | + commits: HEAD~1..HEAD |
81 | 47 | ``` |
82 | 48 |
|
83 | 49 | ## Inputs |
84 | 50 |
|
85 | 51 | | Input | Required | Default | Description | |
86 | 52 | |-------|----------|---------|-------------| |
87 | | -| `token` | No* | | `AUTHS_CI_TOKEN` JSON containing all credentials | |
88 | | -| `files` | **Yes** | | Glob patterns for files to sign (one per line) | |
89 | | -| `verify` | No | `false` | Verify each file immediately after signing | |
90 | | -| `device-key` | No | `ci-release-device` | Device key alias to sign with | |
| 53 | +| `files` | No | | Glob patterns for files to sign, one per line | |
| 54 | +| `commits` | No | | Git revision range to sign | |
| 55 | +| `commit-sha` | No | `$GITHUB_SHA` | Commit SHA to anchor attestation to | |
91 | 56 | | `note` | No | | Note to include in the attestation | |
92 | | -| `auths-version` | No | latest | Pin a specific Auths CLI version | |
| 57 | +| `auths-version` | No | latest | Auths CLI version to use | |
93 | 58 |
|
94 | | -*`token` is the `AUTHS_CI_TOKEN` secret generated by `auths ci setup`. |
| 59 | +At least one of `files` or `commits` must be provided. |
95 | 60 |
|
96 | 61 | ## Outputs |
97 | 62 |
|
98 | 63 | | Output | Description | |
99 | 64 | |--------|-------------| |
100 | 65 | | `signed-files` | JSON array of signed file paths | |
101 | | -| `attestation-files` | JSON array of `.auths.json` attestation file paths | |
102 | | -| `verified` | `true`/`false` when `verify: true`, empty otherwise | |
103 | | - |
104 | | -### Using outputs in subsequent steps |
105 | | - |
106 | | -```yaml |
107 | | -- uses: auths-dev/sign@v1 |
108 | | - id: sign |
109 | | - with: |
110 | | - token: ${{ secrets.AUTHS_CI_TOKEN }} |
111 | | - files: 'dist/**/*.tar.gz' |
112 | | -
|
113 | | -- name: Upload attestations |
114 | | - uses: actions/upload-artifact@v4 |
115 | | - with: |
116 | | - name: attestations |
117 | | - path: ${{ fromJSON(steps.sign.outputs.attestation-files) }} |
118 | | -``` |
119 | | - |
120 | | -## Glob patterns |
121 | | - |
122 | | -The `files` input supports glob patterns, one per line: |
123 | | - |
124 | | -```yaml |
125 | | -files: | |
126 | | - dist/*.tar.gz |
127 | | - dist/*.zip |
128 | | - build/output/**/*.whl |
129 | | -``` |
130 | | - |
131 | | -Patterns follow [@actions/glob](https://github.com/actions/toolkit/tree/master/packages/glob) syntax. Symlinks are not followed. Paths outside the workspace are rejected. |
132 | | - |
133 | | -## Verification |
134 | | - |
135 | | -When `verify: true`, the action runs `auths artifact verify` on each signed file immediately after signing. This proves the full round-trip works and catches signing misconfigurations before they reach consumers. |
136 | | - |
137 | | -Consumers can verify your artifacts independently: |
138 | | - |
139 | | -```bash |
140 | | -auths artifact verify dist/index.js --identity-bundle bundle.json |
141 | | -``` |
142 | | - |
143 | | -Or using the [auths-dev/verify](https://github.com/auths-dev/verify) action: |
144 | | - |
145 | | -```yaml |
146 | | -- uses: auths-dev/verify@v1 |
147 | | - with: |
148 | | - identity: ${{ secrets.AUTHS_CI_TOKEN }} |
149 | | - artifact-paths: 'dist/index.js' |
150 | | -``` |
151 | | - |
152 | | -## Security model |
153 | | - |
154 | | -- The CI device key has **limited capabilities** (`sign_release` only) -- it cannot impersonate your root identity, link devices, or perform other privileged operations |
155 | | -- Credentials are extracted to temp files that are **always cleaned up**, even on failure |
156 | | -- The passphrase is **masked** from all GitHub Actions logs via `core.setSecret` |
157 | | -- Glob results are **contained to the workspace** -- paths outside `$GITHUB_WORKSPACE` are rejected |
158 | | -- You can **revoke CI access** at any time: `auths device revoke --device-did <DID> --key <ALIAS>` |
159 | | - |
160 | | -## Revoking CI access |
161 | | - |
162 | | -If the CI device key is compromised: |
163 | | - |
164 | | -```bash |
165 | | -auths device revoke --device-did <DEVICE_DID> --key <KEY_ALIAS> |
166 | | -``` |
167 | | - |
168 | | -The device DID and key alias are printed by `auths ci setup` during initial setup. After revocation, existing attestations remain valid (they were legitimate when signed), but the device can no longer produce new ones. |
169 | | - |
170 | | -## License |
171 | | - |
172 | | -Apache-2.0 |
| 66 | +| `attestation-files` | JSON array of `.auths.json` paths | |
| 67 | +| `signed-commits` | JSON array of signed commit SHAs | |
0 commit comments