---
title: "Scope id-token to one job: safer OIDC in GitHub Actions"
description: "Declaring id-token: write at the workflow level mints an OIDC publish token for every job. Scope it to the publish job only, with copyable YAML."
url: https://starsling.dev/best-practices/github-actions/scope-id-token-per-job
canonicalUrl: https://starsling.dev/best-practices/github-actions/scope-id-token-per-job
---

# Scope id-token: write to the publishing job

Best practice: Security. Last updated: 2026-07-15

In GitHub Actions, declare `id-token: write` in the specific publishing job's `permissions:` block, never at the workflow's top level, so an OIDC publish token isn't minted for jobs that run untrusted code.

## Table of contents

- [Do this](#do-this)
- [Avoid this](#avoid-this)
- [Seen in the wild](#seen-in-the-wild)
- [Why it matters](#why-it-matters)
- [When to use](#when-to-use)
- [Verify on your repo](#verify)
- [Sources](#sources)

<a id="do-this"></a>

## Do this

The workflow's top-level `permissions:` grants no `id-token`. Only the publish job requests `id-token: write`, ideally behind a protected `environment`. Jobs that run tests or install dependencies, where untrusted third-party code executes, never have a publish-capable token in memory to steal.

_id-token scoped to the publish job_

```yaml
permissions:
  contents: read           # workflow default: no id-token

jobs:
  test:
    runs-on: ubuntu-latest
    permissions:
      contents: read        # explicit: no OIDC token minted here
    steps:
      - uses: actions/checkout@v7
      - run: npm test
  publish:
    needs: test
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write       # scoped to the publish job only
    environment: release
    steps:
      - uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0
```

<a id="avoid-this"></a>

## Avoid this

Any job, including untrusted test code, can read the publish token out of runner memory.

_id-token at workflow scope: every job gets it_

```yaml
permissions:
  contents: read
  id-token: write     # a publish token exists for every job and every step

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - run: npm test   # runs untrusted dep code with the token in memory
  publish:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0
```

<a id="seen-in-the-wild"></a>

## Seen in the wild

Real workflow files from public projects.

### browser-use/browser-use - .github/workflows/docker.yml

```yaml
  build_publish_image:
    runs-on: ubuntu-latest
    permissions:
      packages: write
      contents: read
      attestations: write
      id-token: write
```

Key line: `id-token: write`.

Four narrowly scoped permissions on the publish job, id-token among them, and none declared at the workflow level.

Source: [browser-use/browser-use `.github/workflows/docker.yml` lines 21-27](https://github.com/browser-use/browser-use/blob/f78585575905b11692186783c770f5f3f2feeb9a/.github/workflows/docker.yml#L21-L27) at commit `f785855`.

### vitejs/vite - .github/workflows/publish.yml

```yaml
    if: github.repository == 'vitejs/vite'
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write
```

Key line: `id-token: write`.

id-token: write is granted on the publish job. The workflow declares no top-level permissions block, so no other job can mint a token.

Source: [vitejs/vite `.github/workflows/publish.yml` lines 13-17](https://github.com/vitejs/vite/blob/d2e467d8b68525ea111d7c3f6bae24ebd7afe672/.github/workflows/publish.yml#L13-L17) at commit `d2e467d`.

### fastapi/fastapi - .github/workflows/publish.yml

```yaml
permissions: {}
# ...
  publish:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
```

Key line: `id-token: write`.

The workflow denies everything with a top-level permissions: {}, then the publish job alone requests id-token: write for trusted publishing to PyPI.

Source: [fastapi/fastapi `.github/workflows/publish.yml` lines 8-8,11-15](https://github.com/fastapi/fastapi/blob/7cb06f360dd44efac059848df1a9beee7643b018/.github/workflows/publish.yml#L8-L15) at commit `7cb06f3`, non-adjacent lines joined by `# ...`.

### better-auth/better-auth - .github/workflows/release.yml

```yaml
permissions: {}
# ...
    environment: Release
    permissions:
      contents: write
      pull-requests: write
      id-token: write
```

Key line: `id-token: write`.

The release job opts into exactly three permissions -- contents and pull-requests to raise the version PR, and id-token to publish -- while the workflow's top-level default grants nothing at all.

Source: [better-auth/better-auth `.github/workflows/release.yml` lines 28-28,44-48](https://github.com/better-auth/better-auth/blob/f23ce5012ea47fac1a69b1dad203dfdef3830fd0/.github/workflows/release.yml#L28-L48) at commit `f23ce50`, non-adjacent lines joined by `# ...`.

<a id="why-it-matters"></a>

## Why it matters

When `id-token: write` sits at the workflow level, the runner mints a publish-capable OIDC token for the entire run, including the test job that executes untrusted dependency code. Any code that runs before the real publish step can read that token out of runner memory and publish a malicious package. This was the third leg of the [TanStack 2026 supply-chain compromise](https://tanstack.com/blog/npm-supply-chain-compromise-postmortem): a poisoned cache dumped runner memory and used the workflow-level OIDC token to publish 84 malicious versions. Per-job scoping shrinks the window during which the token exists.

<a id="when-to-use"></a>

## When to use

**Use it when:** Any workflow that uses OIDC trusted publishing (npm, PyPI, cloud deploys) and also runs tests, linting, or dependency installs in the same run.

**Be careful when:** Per-job scoping limits blast radius across jobs, not within the publish job itself, malware restored into the publish job's own cache can still read its token. Combine with cache-integrity hygiene, and where feasible split publishing into its own trigger-gated workflow.

<a id="verify"></a>

## Verify on your repo

Hand this prompt to your coding agent to audit and fix this practice in your own repo:

Inspect this repo's .github/workflows for `id-token: write` declared in a top-level `permissions:` block, which mints an OIDC publish token for every job including ones that run untrusted test or dependency code. Move `id-token: write` out of the workflow level and into only the specific publishing job's `permissions:` block, and leave the other jobs with no `id-token` (or an explicit `contents: read`). Do not touch hardened spellings like `id-token: none` or `id-token: read` elsewhere: only the workflow-level `write` is the finding. Show me the diff and open a PR rather than applying it blindly.

Ground these changes in the upstream docs before you edit: https://docs.github.com/en/actions/reference/security/oidc. If you cannot fetch them, say so rather than guessing, and cite what you used in the PR description.

Prefer to check by hand:

- Check whether `id-token: write` appears in a top-level `permissions:` block: `grep -rn 'id-token' .github/workflows/`.
- If it's at workflow scope, move it into the publish job's `permissions:` and leave other jobs with no `id-token` declaration.
- Confirm hardened spellings elsewhere (`id-token: none`/`read`) are untouched, only the workflow-level `write` is the finding.

<a id="more-best-practices"></a>

## More best practices for GitHub Actions

- [Pin GitHub Actions to commit SHAs](https://starsling.dev/best-practices/github-actions/pin-action-shas)
- [All CI best practices](https://starsling.dev/best-practices/github-actions)

<a id="faq"></a>

## FAQ

### Does per-job scoping fully protect the publish token?

No, it limits blast radius across jobs, not within the publish job. If malware is restored into the publish job's own cache, it can still read the token there. Scope per job as a baseline, keep untrusted code out of the publish job, and pair it with cache-integrity checks.

### Why not just remove id-token entirely?

OIDC trusted publishing needs `id-token: write` in the job that publishes. The goal isn't to remove it but to confine it, grant it only where the publish happens, not to every job in the run.

<a id="sources"></a>

## Sources

1. [GitHub - OIDC reference: scoping id-token to one job](https://docs.github.com/en/actions/reference/security/oidc)
2. [GitHub - OpenID Connect (OIDC) for Actions](https://docs.github.com/en/actions/concepts/security/openid-connect)
3. [GitHub - security hardening for GitHub Actions](https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions)

<a id="get-started"></a>

## Get started

Only give the publish token to the publish job.