Skip to content

Commit 7d5eb07

Browse files
tadasantclaude
andcommitted
docs(github-actions): add CI token-hardening guidance for org publishing
The token that authenticates to an org namespace can publish and overwrite any server under io.github.<org>/*, and by default it is reachable by every repository writer (not just org Owners) via branch or tag pushes. Document how to contain that blast radius: - store the token as an Environment secret (update the PAT example to use `environment:`) - restrict the environment to the default branch / release tags and protect that branch with required reviews - optionally require an environment reviewer for per-publish approval - avoid pull_request_target-with-checkout and self-hosted runners on public repos Also clarify that the PAT's read:org scope is what authorizes org publishing and that no repository scopes are needed. Refs #982. Co-Authored-By: Claude Opus 4.8 <[email protected]>
1 parent 5ecbbda commit 7d5eb07

1 file changed

Lines changed: 22 additions & 1 deletion

File tree

‎docs/modelcontextprotocol-io/github-actions.mdx‎

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -81,6 +81,10 @@ on:
8181
jobs:
8282
publish:
8383
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
8488
permissions:
8589
contents: read
8690

@@ -195,13 +199,30 @@ jobs:
195199
You may need to add a secret to the repository depending on which authentication method you choose:
196200
197201
- **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).
199203
- **DNS Authentication**: Add a `MCP_PRIVATE_KEY` secret with your Ed25519 private key.
200204

201205
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.
202206

203207
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).
204208

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+
205226
## Step 3: Tag and Release
206227

207228
Create and push a version tag to trigger the workflow:

0 commit comments

Comments
 (0)