|
81 | 81 | jobs: |
82 | 82 | publish: |
83 | 83 | runs-on: ubuntu-latest |
| 84 | + # Source MCP_GITHUB_TOKEN from a protected Environment, not a plain repo |
| 85 | + # secret, and restrict that environment to your default branch / release |
| 86 | + # tags. See "Securing your registry token in CI" below for why this matters. |
| 87 | + environment: mcp-registry-publish |
84 | 88 | permissions: |
85 | 89 | contents: read |
86 | 90 |
|
@@ -195,13 +199,30 @@ jobs: |
195 | 199 | You may need to add a secret to the repository depending on which authentication method you choose: |
196 | 200 |
|
197 | 201 | - **GitHub OIDC Authentication**: No dedicated secret necessary. |
198 | | -- **GitHub PAT Authentication**: Add a `MCP_GITHUB_TOKEN` secret with a GitHub Personal Access Token (PAT) that has `read:org` and `read:user` scopes. |
| 202 | +- **GitHub PAT Authentication**: Add a `MCP_GITHUB_TOKEN` secret with a GitHub Personal Access Token (PAT) that has `read:org` and `read:user` scopes. The `read:org` scope is what lets the registry confirm you are an **Owner** of the organization before granting its namespace; the token needs **no** repository scopes (the registry never reads or writes your code). |
199 | 203 | - **DNS Authentication**: Add a `MCP_PRIVATE_KEY` secret with your Ed25519 private key. |
200 | 204 |
|
201 | 205 | You may also need to add secrets for your package registry. For example, the workflow above needs an `NPM_TOKEN` secret with your npm token. |
202 | 206 |
|
203 | 207 | For information about how to add secrets to a repository, see [Using secrets in GitHub Actions](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets). |
204 | 208 |
|
| 209 | +### Securing your registry token in CI |
| 210 | + |
| 211 | +Whichever token you use to authenticate, treat it as a high-value credential. When you authenticate to an **organization** namespace, the resulting registry token can publish — and overwrite — **any** server under `io.github.<org>/*`, not just the one in this repository. The relevant question for your threat model is therefore: *who can cause code to run in a job where this secret is exposed?* By default that is **every repository writer** (via branch or tag pushes), not only org Owners — so a plain repo secret quietly widens publish access to everyone with write access. |
| 212 | + |
| 213 | +GitHub gives you the tools to close that gap. We recommend, in increasing order of strength: |
| 214 | + |
| 215 | +1. **Store the token as an [Environment secret](https://docs.github.com/en/actions/how-tos/deploy/configure-and-manage-deployments/manage-environments), not a repository or organization secret.** A job only receives it when it declares `environment:` (as the PAT example above does). |
| 216 | +2. **Restrict that environment to your default branch and/or release tags** with a [deployment branch rule](https://docs.github.com/en/actions/how-tos/deploy/configure-and-manage-deployments/manage-environments#deployment-branches-and-tags), and protect that branch with [required pull request reviews](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches). Now only reviewed, maintainer-approved code can ever reach the token. |
| 217 | +3. **(Strongest) Add a [required reviewer](https://docs.github.com/en/actions/how-tos/deploy/configure-and-manage-deployments/manage-environments#required-reviewers) to the environment** so each publish pauses for an explicit human approval. |
| 218 | + |
| 219 | +Two pitfalls to avoid regardless of the above: |
| 220 | + |
| 221 | +- **Never publish from a `pull_request_target` workflow that checks out PR-head code.** That trigger runs with your secrets in the base-repo context, so an untrusted fork PR could exfiltrate the token. Environment branch rules do **not** protect you here (the ref is still your base branch) — only required reviewers do. |
| 222 | +- **Avoid self-hosted runners for the publish job on public repositories**, where fork PRs may be able to schedule jobs onto them. |
| 223 | + |
| 224 | +By default, pull requests **from forks** receive no secrets and cannot push branches, so external contributors cannot reach the token without one of the misconfigurations above. |
| 225 | + |
205 | 226 | ## Step 3: Tag and Release |
206 | 227 |
|
207 | 228 | Create and push a version tag to trigger the workflow: |
|
0 commit comments