# GitHub Actions Setup Bumpy handles CI automation through its `bumpy ci` subcommands — no separate GitHub Action or bot to install. Just call `bumpy ci` directly in your workflows. These commands facilitate the following: - **On every PR** - check that PRs have bump files, add/update a comment with the release plan, outlining which packages will be bumped from the PR - **When a regular PR merges to main** - create/update a special "release PR" which updates changelogs and version numbers, and deletes the bump files - **When release PR is merged** - trigger the release process > **Using npm / pnpm / yarn instead of bun?** All examples below use `bun` / `bunx` for brevity, but bumpy itself is package-manager agnostic. Substitute: > > - `oven-sh/setup-bun@v2` → `actions/setup-node@v6` (+ `pnpm/action-setup` if using pnpm) > - `bun install` → `npm ci` / `pnpm install --frozen-lockfile` / `yarn install --immutable` > - `bunx @varlock/bumpy@…` → `npx @varlock/bumpy@…` / `pnpm dlx @varlock/bumpy@…` / `yarn dlx @varlock/bumpy@…` > > The version-resolution shell snippets work as-is regardless of package manager — they only depend on `jq` and `git`, both preinstalled on GitHub-hosted runners. ## PR check `bumpy ci check` confirms every PR carries a bump file and posts a release-plan comment showing what will be released. The simplest setup is one step in your existing PR workflow (or a new one triggered `on: pull_request`): ```yaml - run: bunx @varlock/bumpy ci check env: GH_TOKEN: ${{ github.token }} ``` Give the job `permissions: { contents: read, pull-requests: write }` (listing any permission zeroes the rest, and checkout needs `contents: read` on private repos). This runs in the ordinary `pull_request` context — the same trust level as the rest of your CI — so there's nothing special to be careful about: you can `bun install` and run bumpy from your devDeps like any other CLI. (If the job already ran `bun install`, `bunx` picks up your pinned version from `node_modules`; otherwise it fetches the latest.) **Fork PRs get the check, but not the comment.** GitHub hands `pull_request` runs from forks a **read-only token and no secrets**, so the comment can't be posted there. `ci check` still runs and fails the job (red ✗) on a missing bump file, with the explanation in the job logs — forks stay gated correctly, you just don't get the rendered comment. For most repos that's the right trade. If you want the comment on fork PRs too, add the two-part setup below. > **Inline step vs. dedicated workflow.** Folding `ci check` into an existing CI job is the least setup and the right default for most repos. Give it its own lightweight `on: pull_request` workflow when either of these applies: > > - **Slow CI + fork comments.** The fork-comment poster below (`workflow_run`) fires on _whole-workflow_ completion, so if `ci check --emit-comment` rides inside a multi-minute CI workflow, the release-plan comment won't post until everything (lint, typecheck, build, tests) finishes. A dedicated check — no `bun install`, just `bunx @varlock/bumpy` — completes in seconds, so the comment lands almost immediately. > - **A load-bearing gate.** If `ci check` is an early step in your test job, its non-zero exit on a missing bump file fails the job and skips the remaining steps — so a contributor who pushed code before adding the bump file loses all test signal. A separate workflow (or a separate _job_) keeps the gate independent. A separate job doesn't share the test job's `bun install`, so once you're paying for an extra checkout anyway, a dedicated workflow also buys the fast comment above. ## Commenting on fork PRs **This is optional — set it up only if you want the release-plan comment to appear on PRs from forks.** The `ci check` above already runs on fork PRs and fails them red on a missing bump file; it just can't post the comment there, because GitHub gives a fork's `pull_request` run a read-only token (secrets withheld, writes blocked server-side). Posting requires a privileged run in the base-repo context, and the safe way to get one is a small extra workflow whose privileged half **never touches the fork's code or files**: 1. Your existing `pull_request` check **renders** the comment and uploads it as an artifact. 2. A small, separate `workflow_run` workflow downloads that artifact and **posts** it. The poster never checks out the PR, never runs a package manager against fork config, and never reads a fork file — it only posts pre-rendered text. (No forks to worry about? You don't need any of this.) ### 1. Render + upload (in your existing check) Add `--emit-comment` to the `ci check` step and upload what it writes: ```yaml # in your existing `on: pull_request` job - run: bunx @varlock/bumpy ci check --emit-comment ./bumpy-comment env: GH_TOKEN: ${{ github.token }} - uses: actions/upload-artifact@v4 if: always() # upload even when the check fails — the comment explains why with: name: bumpy-comment path: ./bumpy-comment ``` `--emit-comment` writes the rendered comment to `./bumpy-comment/comment.md` (an empty file when there's nothing to say, so the artifact is always present). This step stays unprivileged — on a fork PR it renders but can't post; same-repo PRs still comment directly from here. The poster below is what rescues forks. ### 2. Post it (a separate workflow_run workflow) ```yaml # .github/workflows/bumpy-comment.yaml name: Bumpy PR Comment on: workflow_run: workflows: ['CI'] # ← the NAME of the workflow that runs your check types: [completed] permissions: contents: read # checkout of your default branch (for the bumpy version in package.json) pull-requests: write jobs: comment: runs-on: ubuntu-latest steps: # TRUSTED: default branch only — never the PR. This is the privileged half. - uses: actions/checkout@v7 - uses: oven-sh/setup-bun@v2 - uses: actions/download-artifact@v4 continue-on-error: true # the check may not have produced a comment with: name: bumpy-comment # Download OUTSIDE the checkout (runner.temp) so the untrusted artifact # can't overwrite trusted files. path: ${{ runner.temp }}/bumpy-comment run-id: ${{ github.event.workflow_run.id }} github-token: ${{ github.token }} - run: | VERSION=$(jq -r '.devDependencies["@varlock/bumpy"] // .dependencies["@varlock/bumpy"]' package.json | sed 's/[\^~]//') bunx "@varlock/bumpy@$VERSION" ci comment --body-file "$RUNNER_TEMP/bumpy-comment/comment.md" env: GH_TOKEN: ${{ github.token }} ``` Point `workflows: [...]` at the **name** of whatever runs your check (your existing CI workflow, or a dedicated one). When it finishes, GitHub triggers this poster, which posts the rendered comment and exits. No bump-file changes → `ci comment` no-ops. > **Heads-up: it won't run until it's on your default branch.** `workflow_run` always uses the workflow file as it exists on the default branch, so the poster doesn't fire for the PR that _adds_ it — fork comments start working once `bumpy-comment.yaml` is merged to `main`. (Same-repo PRs are unaffected; they comment directly from the check.) > **The one safety rule.** The uploaded artifact is **untrusted** — it's produced by the unprivileged `pull_request` run from fork-controlled inputs (the comment is rendered from the PR's own bump files, and the run may execute fork code), so treat its contents as attacker-controlled. Two things keep it safe: (1) download it to `runner.temp`, **outside the checkout**, so it can't overwrite trusted files; and (2) `bumpy ci comment` uses the body only as comment text and resolves the **target PR from the trusted `workflow_run` event** (`head_sha`), never from the artifact — that's what stops a fork from redirecting the comment onto a different PR or issue. Don't override it with a `--pr` derived from artifact data. > **If CodeQL flags this step (`actions/artifact-poisoning`):** that query fires on any `workflow_run` workflow that consumes an artifact from the triggering run. Downloading to `runner.temp` as above addresses its core recommendation (extract to a folder that can't overwrite existing files). If your repo's query is strict enough to still flag the download, it's a false positive you can dismiss — the body is used only as comment text and the PR is resolved from the trusted event, never the artifact. > **Why can't the fork run post it itself?** A fork's `pull_request` token is read-only at issuance and enforced server-side — REST, GraphQL, `gh`, and raw `curl` all 403 on a comment write, and secrets aren't exposed either. The write has to originate from a privileged base-repo run, which is exactly what `workflow_run` provides. ## Dependency update PRs (Dependabot / Renovate) A dev-only update (`devDependencies`) never needs a bump file — see [change detection](configuration.md#change-detection-and-packagejson-fields). An update to `dependencies`, `peerDependencies` or `optionalDependencies` does, since it changes what your consumers install. Rather than adding those by hand, `bumpy ci deps` writes them for you (the bumpy equivalent of [changesets-dependencies-action](https://github.com/the-guild-org/changesets-dependencies-action)): - diffs each managed package's dependencies against the base branch — the same changes `bumpy check` requires a bump file for (catalog updates included; `devDependencies` only if listed in [`releaseTriggeringDevDeps`](configuration.md#release-triggering-devdependencies)) - writes one **patch** bump file per affected package, `.bumpy/deps-pr-.md`, listing each added / updated / removed dependency with a link to npm - for a [`directBump: false`](configuration.md#directbump-false--packages-that-only-follow) package, puts the bump on a fixed-group member instead (and fails if there isn't one) - commits and pushes them to the PR branch — re-running (e.g. after Dependabot rebases) rewrites the files and deletes ones that no longer apply. Generated files carry a marker comment; files without it are never touched Run it before `ci check`, in the same job, so the check sees the new files: ```yaml # .github/workflows/bumpy-deps.yaml name: Bumpy (dependency PRs) on: pull_request jobs: deps: # gate on the PR author, not github.actor — so a maintainer's push to a bot PR # (e.g. pinning or reverting the update) regenerates the files too if: contains(fromJSON('["dependabot[bot]", "renovate[bot]"]'), github.event.pull_request.user.login) runs-on: ubuntu-latest permissions: contents: write # push the bump-file commit pull-requests: write # ci check comment steps: - uses: actions/checkout@v6 with: ref: ${{ github.head_ref }} fetch-depth: 0 - uses: oven-sh/setup-bun@v2 - run: bunx @varlock/bumpy ci deps env: GH_TOKEN: ${{ github.token }} BUMPY_GH_TOKEN: ${{ secrets.BUMPY_GH_TOKEN }} - run: bunx @varlock/bumpy ci check env: GH_TOKEN: ${{ github.token }} ``` Then skip bumpy's regular PR check for those PRs (the same condition, negated), or leave it — it will pass on the re-run triggered by the pushed commit. The re-run of this workflow finds the files up to date and commits nothing, so it doesn't loop. Things to know: - **Use `BUMPY_GH_TOKEN` if checks are required.** A commit pushed with the default `GITHUB_TOKEN` doesn't trigger new workflow runs, so required status checks on the new head commit stay pending. Workflows triggered by Dependabot only see **Dependabot secrets** — add `BUMPY_GH_TOKEN` under _Settings → Secrets and variables → Dependabot_ as well as _Actions_. See [Token setup](#token-setup). - **Dependabot stops auto-rebasing PRs that have commits from someone else.** Comment `@dependabot recreate` to get a fresh branch; the workflow then regenerates the bump files. - **Fork PRs are skipped** — their branch can't be pushed to. - **PRs into a channel branch** are diffed against that branch (`GITHUB_BASE_REF`), so only this PR's dependency changes get bump files. - `ci deps` sets a `changed` step output (`true` / `false`). - Locally, `bumpy generate --deps` writes the same files (named after the branch) without committing. ## Release workflow (recommended: split jobs) The recommended release workflow splits version-PR maintenance from publishing into separate jobs. Only the publish job carries `id-token: write` and npm credentials, and it runs inside a GitHub Environment — so a rogue workflow elsewhere in the repo can't request an OIDC token that npm will accept. ```yaml # .github/workflows/bumpy-release.yml name: Bumpy Release on: push: # Add any prerelease channel branches here too, e.g. [main, next, beta]. # See the prerelease channels docs: https://github.com/dmno-dev/bumpy/blob/main/docs/prereleases.md branches: [main] concurrency: # Per-ref: serialize a branch's releases, let different branches run in parallel group: bumpy-release-${{ github.ref }} cancel-in-progress: false jobs: # Detect what `ci release` would do — no write permissions, no publish credentials. # Also resolves bumpy's version once and exposes it as an output for downstream jobs. plan: runs-on: ubuntu-latest permissions: contents: read outputs: mode: ${{ steps.plan.outputs.mode }} packages: ${{ steps.plan.outputs.packages }} bumpy_version: ${{ steps.bumpy-version.outputs.version }} steps: - uses: actions/checkout@v6 with: fetch-depth: 0 - uses: oven-sh/setup-bun@v2 # No `bun install` — bumpy reads files (package.jsons, bump files) and doesn't need your workspace deps resolved # We just pin its version from package.json and let bunx fetch it - id: bumpy-version name: Resolve bumpy version run: | VERSION=$(jq -r '.devDependencies["@varlock/bumpy"] // .dependencies["@varlock/bumpy"]' package.json | sed 's/[\^~]//') echo "version=$VERSION" >> "$GITHUB_OUTPUT" echo "BUMPY_VERSION=$VERSION" >> "$GITHUB_ENV" - id: plan run: bunx "@varlock/bumpy@$BUMPY_VERSION" ci plan env: GH_TOKEN: ${{ github.token }} # Creates/updates the Version Packages PR. No publish credentials. version-pr: needs: plan if: needs.plan.outputs.mode == 'version-pr' runs-on: ubuntu-latest permissions: contents: write pull-requests: write env: BUMPY_VERSION: ${{ needs.plan.outputs.bumpy_version }} steps: - uses: actions/checkout@v6 with: fetch-depth: 0 - uses: oven-sh/setup-bun@v2 - run: bunx "@varlock/bumpy@$BUMPY_VERSION" ci release --expect-mode version-pr env: GH_TOKEN: ${{ github.token }} BUMPY_GH_TOKEN: ${{ secrets.BUMPY_GH_TOKEN }} # so the version PR triggers CI # Publishes packages. Scoped to the `publish` environment. publish: needs: plan if: needs.plan.outputs.mode == 'publish' runs-on: ubuntu-latest environment: publish permissions: contents: write id-token: write # required for npm trusted publishing (OIDC) and provenance env: BUMPY_VERSION: ${{ needs.plan.outputs.bumpy_version }} steps: - uses: actions/checkout@v6 with: fetch-depth: 0 - uses: oven-sh/setup-bun@v2 - uses: actions/setup-node@v6 with: node-version: 24 - run: npm install -g npm@11 # ensure npm >= 11.15.0 for OIDC/staged publishing # Build steps that need to happen before publish go here. If your build # needs workspace deps, add `bun install` first: # - run: bun install # - run: bun run build - run: bunx "@varlock/bumpy@$BUMPY_VERSION" ci release --expect-mode publish env: GH_TOKEN: ${{ github.token }} BUMPY_GH_TOKEN: ${{ secrets.BUMPY_GH_TOKEN }} # so `release: published` workflows trigger ``` **How the three jobs interact:** - `plan` runs `bumpy ci plan` to determine whether the current push should update the Version Packages PR (`version-pr`), publish unpublished packages (`publish`), or do nothing. It also resolves bumpy's version from `package.json` and exposes it as the `bumpy_version` output so downstream jobs don't have to re-resolve. - Only one of `version-pr` or `publish` runs per push. The other is skipped via the `if:` condition. - The `--expect-mode` flag on `ci release` asserts that the detected mode matches what each job expects — if the runtime state ever drifts, the job fails loudly instead of silently doing the wrong thing. - Expensive build steps (compilation, tests, bundling) only run inside the `publish` job, so PR merges that just maintain the version PR stay cheap. ### Required setup 1. **Pin the npm trusted publisher to environment `publish`** on each package's npmjs.com settings → Trusted Publishers → GitHub Actions. Set the environment field to `publish`. This binds the OIDC trust to that specific environment — even if someone adds a rogue workflow file, npm will reject any token request that doesn't carry the `publish` environment claim. 2. **Set `BUMPY_GH_TOKEN`** — see [Token setup](#token-setup) below. That's it — the `publish` environment auto-creates on the first publish run, so no manual GitHub setup is required. ### Optional hardening: protection rules on the `publish` environment If you create the environment manually in repo Settings → Environments _before_ the first publish, you can attach protection rules: - **Restrict deployment branches to `main`** — recommended. Cheap defense in depth: non-`main` refs can never request an OIDC token from this environment, even if a workflow trigger is accidentally widened later. If you use [prerelease channels](prereleases.md), also add each channel branch (e.g. `next`) to the allowed list — otherwise channel publishes fail when the job can't enter the environment. - **Required reviewers** — optional. Adds a manual approval gate before each publish. Usually redundant if `npmStaged: true` is enabled (below), since you already have a 2FA approval gate on npmjs.com. **Recommended publish config** — enable provenance and staged publishing for maximum security: ```json { "publish": { "provenance": true, "npmStaged": true } } ``` > **Staged publishing:** With `npmStaged` enabled, bumpy uses `npm stage publish` to stage packages on npmjs.com, requiring manual 2FA approval before they go live — even if your CI credentials are compromised, nothing gets published without maintainer approval. See the [staged publishing docs](./configuration.md#staged-publishing) for details. ### Using `NPM_TOKEN` instead of OIDC If you can't use trusted publishing, swap `id-token: write` for an `NPM_TOKEN` secret. Scope the secret to the `publish` environment (repo Settings → Environments → publish → Add secret) so only this job can read it: ```yaml publish: needs: plan if: needs.plan.outputs.mode == 'publish' runs-on: ubuntu-latest environment: publish permissions: contents: write steps: # ... checkout/setup-bun/setup-node/install steps ... - run: bunx @varlock/bumpy ci release --expect-mode publish env: GH_TOKEN: ${{ github.token }} NPM_TOKEN: ${{ secrets.NPM_TOKEN }} BUMPY_GH_TOKEN: ${{ secrets.BUMPY_GH_TOKEN }} ``` ## Release workflow (simplified single-job) For simpler setups, you can run everything in a single job. `bumpy ci release` will smart-route between version-PR and publish based on the current state. ```yaml # .github/workflows/bumpy-release.yml name: Bumpy Release on: push: # Add any prerelease channel branches here too, e.g. [main, next, beta]. # See the prerelease channels docs: https://github.com/dmno-dev/bumpy/blob/main/docs/prereleases.md branches: [main] concurrency: # Per-ref: serialize a branch's releases, let different branches run in parallel group: bumpy-release-${{ github.ref }} cancel-in-progress: false jobs: release: runs-on: ubuntu-latest permissions: contents: write pull-requests: write id-token: write # required for npm trusted publishing (OIDC) steps: - uses: actions/checkout@v6 with: fetch-depth: 0 - uses: oven-sh/setup-bun@v2 - uses: actions/setup-node@v6 with: node-version: 24 - run: npm install -g npm@11 - run: bun install - run: bunx @varlock/bumpy ci release env: GH_TOKEN: ${{ github.token }} BUMPY_GH_TOKEN: ${{ secrets.BUMPY_GH_TOKEN }} ``` **Trade-off:** this is the shortest workflow you can write, but `id-token: write` and any publish secrets are exposed on every push to main — including pushes that only update the version PR. The split-job workflow above scopes those credentials to the publish step only. Prefer the split workflow unless you have a strong reason not to. ## Auto-publish mode (not recommended) `bumpy ci release --auto-publish` collapses version + publish into a single run, skipping the Version Packages PR. This forfeits the preview/review gate on version bumps — every merge to main with a bump file ships immediately. It's also incompatible with the [split-job pattern](#release-workflow-recommended-split-jobs) above, since both paths run in one command. Prefer the default flow. See [the CLI reference](cli.md#bumpy-ci-release) if you still need it. ## Telling issues they're merged, not released (optional) With bumpy, a fix merges to `main` well before it's published — the Version Packages PR sits in between. But when a PR says `Closes #123`, GitHub closes that issue the instant the PR merges, so anyone watching sees "closed" and reasonably assumes it shipped. It hasn't yet. **This is optional** — set it up only if that gap bothers your issue reporters. Rather than fight GitHub's auto-close (you can't defer it, and reopening spams notifications), this leaves a clarifying comment on each auto-closed issue: > ✅ A fix has been merged to `main` in #142 and will ship in the next release. GitHub auto-closed this issue on merge, but the change isn't published yet. ```yaml # .github/workflows/bumpy-issue-note.yml name: Issue Merge Note on: pull_request_target: types: [closed] branches: [main] # your stable release branch — the "next release" wording assumes it permissions: issues: write jobs: note: if: github.event.pull_request.merged == true runs-on: ubuntu-latest steps: - name: Comment on auto-closed issues env: GH_TOKEN: ${{ github.token }} REPO: ${{ github.repository }} PR: ${{ github.event.pull_request.number }} run: | set -euo pipefail # closingIssuesReferences resolves every Closes/Fixes/Resolves variant — no body parsing issues=$(gh api graphql \ -f query=' query($owner: String!, $repo: String!, $pr: Int!) { repository(owner: $owner, name: $repo) { pullRequest(number: $pr) { closingIssuesReferences(first: 50) { nodes { number } } } } }' \ -f owner="${REPO%/*}" -f repo="${REPO#*/}" -F pr="$PR" \ --jq '.data.repository.pullRequest.closingIssuesReferences.nodes[].number') [ -z "$issues" ] && { echo "PR #$PR closed no linked issues."; exit 0; } for n in $issues; do gh issue comment "$n" --repo "$REPO" --body \ "✅ A fix has been merged to \`main\` in #${PR} and will ship in the next release. GitHub auto-closed this issue on merge, but the change isn't published yet." done ``` This needs no bumpy — it's pure `gh`, so it runs in seconds with no `bun install` or build. `pull_request_target` is what grants the `issues: write` token, but the job **never checks out or runs the PR's code** — it only reads the PR's linked issues and posts a comment. The only PR-controlled value that reaches the shell is the PR number (an integer), so there's nothing to inject. > **It won't run until it's on your default branch.** Like any `pull_request_target` workflow, GitHub uses the copy on the default branch — so it doesn't fire for the PR that _adds_ it. It starts working once merged to `main`. > **Scoped to your stable branch.** The `branches: [main]` filter is on the base branch. A merge to a [prerelease channel](prereleases.md) like `next` won't trigger it, since "the next release" would be a prerelease. Add channel branches to the filter if you want them covered. > **Want a "now released" follow-up too?** You can close the loop with a second comment when the release actually publishes — your GitHub release job already fires a `release: published` event (that's what `BUMPY_GH_TOKEN` enables). A workflow on that event can post "🎉 Released in `vX.Y.Z`" linking the release. Doing it reliably means telling issue references apart from PR references in the release body, so it's a bit more involved than this snippet — but the durable, meaningful link (the release itself) lives there. ## Advanced: per-package conditional builds If you have one expensive package whose build you only want to run when that package itself is being released, use `ci plan`'s `packages` output to gate per-package steps: ```yaml - id: plan run: bunx @varlock/bumpy ci plan env: GH_TOKEN: ${{ github.token }} # Build only when this specific package is being released - if: contains(fromJSON(steps.plan.outputs.packages), 'my-expensive-package') run: bun run build --filter=my-expensive-package ``` `ci plan` outputs: | Output | Description | | ---------- | ------------------------------------------------------------- | | `mode` | `version-pr`, `publish`, or `nothing` | | `packages` | JSON array of package names (for `fromJSON()` + `contains()`) | | `json` | Full JSON output (for `fromJSON()`) | ## Concurrency Use a concurrency group on your release workflow to prevent overlapping publish runs. Without this, rapid merges to main could trigger multiple workflows that race to publish the same packages. ```yaml concurrency: group: bumpy-release-${{ github.ref }} cancel-in-progress: false # queue rather than cancel — don't skip releases ``` This is included in all the workflow examples above. Per-ref serializes each branch's releases against themselves while letting different branches publish in parallel. It's the right default everywhere: with a single release branch it behaves identically to a plain group, and once you add [prerelease channels](prereleases.md) it stops a `next` prerelease publish from queueing behind — or, with `cancel-in-progress: true`, being cancelled by — a `main` release, even though they touch different dist-tags and never conflict. ## Token setup ### `GH_TOKEN` (required) The default `${{ github.token }}` covers general API access (registry lookups, reading PRs, posting comments). **Permissions needed per job:** - `pull-requests: write` — for posting PR comments (`ci check`) or creating the version PR (`version-pr` job) - `contents: write` — for pushing commits and tags (release jobs) - `id-token: write` — for npm trusted publishing / OIDC (publish job only) ### `BUMPY_GH_TOKEN` (recommended) GitHub's anti-recursion guard prevents PRs created by the default `github.token` from triggering other workflows. This means your regular CI workflows (tests, linting, etc.) won't run automatically on the Version Packages PR — so you can't verify that the version bumps don't break anything before merging. To fix this, provide a `BUMPY_GH_TOKEN` using either a **fine-grained PAT** or a **GitHub App token**. Bumpy uses this token selectively — only for the specific operations where bypassing the anti-recursion guard matters (pushing the version branch, creating the version PR, creating the GitHub release). Everything else continues to use the default `GH_TOKEN`. > **Note:** If you're using a developer's personal PAT, the version PR will be authored by that developer. Consider using a dedicated bot account or GitHub App so the developer can still review and approve the PR. Run `bumpy ci setup` for interactive guidance, or set it up manually: #### Option 1: Fine-grained personal access token 1. Go to [GitHub → Settings → Personal access tokens → Fine-grained tokens](https://github.com/settings/personal-access-tokens) 2. Create a new token with: - **Repository access:** select your repo only - **Permissions:** - Contents: Read and write - Pull requests: Read and write - Metadata: Read (auto-selected) 3. Add it as a repository secret named `BUMPY_GH_TOKEN` #### Option 2: GitHub App token For organizations, a GitHub App avoids tying automation to a personal account: 1. Create a GitHub App with Contents and Pull Requests permissions (read & write) 2. Install it on your repository 3. Store `BUMPY_APP_ID` and `BUMPY_APP_PRIVATE_KEY` as repository secrets 4. Generate the token in your workflow: ```yaml - uses: actions/create-github-app-token@v2 id: app-token with: app-id: ${{ secrets.BUMPY_APP_ID }} private-key: ${{ secrets.BUMPY_APP_PRIVATE_KEY }} # Mint only what bumpy needs, not everything the App was installed with permission-contents: write permission-pull-requests: write - run: bunx @varlock/bumpy ci release env: GH_TOKEN: ${{ github.token }} BUMPY_GH_TOKEN: ${{ steps.app-token.outputs.token }} ``` ### `NPM_TOKEN` (if not using trusted publishing) A classic npm access token. Create one at [npmjs.com → Access Tokens](https://www.npmjs.com/settings/~/tokens) and add it as a secret on the `publish` environment (repo Settings → Environments → publish → Add secret) so only the publish job can read it. ## Environment variables summary | Variable | Required | Used by | Description | | ---------------- | ----------------- | ------------------------ | ----------------------------------------------------------------------------- | | `GH_TOKEN` | Yes | `ci check`, `ci release` | GitHub token for API access — `${{ github.token }}` is fine | | `BUMPY_GH_TOKEN` | Recommended | `ci check`, `ci release` | PAT or App token — selectively used for ops where workflow-triggering matters | | `NPM_TOKEN` | If not using OIDC | publish job | npm access token for publishing |