For two weeks my release pipeline did exactly half of its job. A bump job ran on every merge to main, wrote a new version, pushed a v* tag, and finished green. A second workflow, release.yml, was supposed to wake up on that tag, build the artifacts and publish a GitHub Release.

Eleven tags went out. Zero releases came back. The Actions tab didn't show a failed run or a skipped run. It showed nothing, as if the tags had never been pushed. The cause is a rule that surprises almost everyone the first time: GITHUB_TOKEN doesn't trigger workflows. Anything a workflow does with that token is invisible to every other workflow's on: block.

TL;DR

  • Events caused by the built-in GITHUB_TOKEN (pushes, tags, opened PRs, published releases, labels) do not start new workflow runs. GitHub does this on purpose to stop infinite loops.
  • The only exceptions are workflow_dispatch and repository_dispatch. Those still fire when sent with GITHUB_TOKEN.
  • No error is logged anywhere. The downstream run simply never exists.
  • Best fix with zero secrets: call the downstream workflow directly with workflow_call, or dispatch it with gh workflow run.
  • If you truly need the push itself to trigger things (for example, CI on a bot-opened PR), push with a GitHub App installation token instead.

Why doesn't a push made with GITHUB_TOKEN trigger my workflow?

Because GitHub deliberately drops workflow triggers for events created by GITHUB_TOKEN, except workflow_dispatch and repository_dispatch. The reasoning is simple: a workflow that runs on push and also pushes a commit would retrigger itself forever. Rather than asking every user to write loop guards, GitHub cut the link at the token level.

The token still works. Your push lands, your tag exists, your PR opens. The event is recorded in the repository. It's just never delivered to the workflow scheduler.

That's what makes it nasty. Nothing fails. Your logs say * [new tag] v1.4.0 -> v1.4.0 and the job ends with a green check.

What did my broken setup look like?

Here's the bump workflow, trimmed down:

# .github/workflows/bump.yml name: bump on: push: branches: [main] permissions: contents: write jobs: bump: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: fetch-depth: 0 - name: Tag next version run: | NEXT=$(./scripts/next-version.sh) git tag "v$NEXT" git push origin "v$NEXT" 

And the release workflow that never ran:

# .github/workflows/release.yml name: release on: push: tags: ['v*'] 

The trap is hidden in actions/checkout. By default it uses GITHUB_TOKEN and leaves it in the local git config (persist-credentials: true). So when the script later runs a plain git push, it pushes as github-actions[bot] with GITHUB_TOKEN. You never typed the token name, but you used it.

If I had pushed that same tag from my laptop, release.yml would have fired instantly. That's the quickest way to confirm you're hitting this rule: push the same thing by hand and watch it work.

Which GitHub Actions events still fire from GITHUB_TOKEN?

Only two do directly. Everything else that the token creates is silent.

Action taken with GITHUB_TOKEN Starts a new workflow run?
git push to a branch No
git push of a tag No
Opening or updating a pull request No
Publishing a release (release: published) No
Adding a label, opening an issue No
workflow_dispatch (e.g. gh workflow run) Yes
repository_dispatch (API call) Yes

There's also workflow_run, which fires when another workflow completes. It keys off the finished run of bump.yml (which a human push started), not off the tag, so it does fire. It's a usable workaround, but it gives you awkward context: the downstream run sees the upstream commit, not your tag, and you have to dig the version back out.

The pull request row is the one that bites the most people. Tools that open "chore: bump dependencies" PRs from inside a workflow with GITHUB_TOKEN produce PRs where required checks sit on "Waiting for status to be reported" forever. CI was never asked to run.

How do I fix it without adding any secrets?

Call the release workflow yourself instead of hoping the tag wakes it up. There are two clean ways, and neither needs a personal token.

Fix 1: make release a reusable workflow (workflow_call)

This is what I shipped. The release workflow accepts a tag as input:

# .github/workflows/release.yml name: release on: workflow_call: inputs: tag: required: true type: string push: tags: ['v*'] # keep this so manual tag pushes still work  jobs: release: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: ref: ${{ inputs.tag || github.ref }} - run: ./scripts/build-and-publish.sh "${{ inputs.tag || github.ref_name }}" 

And the bump workflow calls it as a second job:

jobs: bump: runs-on: ubuntu-latest outputs: tag: ${{ steps.tag.outputs.tag }} steps: - uses: actions/checkout@v4 with: fetch-depth: 0 - id: tag run: | NEXT="v$(./scripts/next-version.sh)" git tag "$NEXT" && git push origin "$NEXT" echo "tag=$NEXT" >> "$GITHUB_OUTPUT" release: needs: bump uses: ./.github/workflows/release.yml with: tag: ${{ needs.bump.outputs.tag }} secrets: inherit 

Two details matter here. First, a called workflow runs with the caller's github context, so github.ref is still refs/heads/main, not your tag. That's why I pass the tag in explicitly. Second, the called workflow can't have more GITHUB_TOKEN permissions than the caller grants, so if the release step uploads assets, the caller needs contents: write.

Fix 2: dispatch it with gh workflow run

If you'd rather keep the workflows separate, workflow_dispatch is one of the two exempt events. Add it to the release workflow's triggers, then from the bump job:

permissions: contents: write actions: write # required to dispatch workflows  # ...after pushing the tag: - run: gh workflow run release.yml --ref "$NEXT" env: GH_TOKEN: ${{ github.token }} 

Dispatching with --ref set to the tag means the release run checks out the tag and sees github.ref as refs/tags/v1.4.0, exactly like a real tag push would. It shows up in the Actions tab as a separate run, which I find easier to read than nested jobs.

When do I actually need a different token?

When the event itself has to trigger things you don't control, like required CI checks on a bot-opened pull request. You can't workflow_call your way into a PR's status checks. The push has to come from an identity that isn't GITHUB_TOKEN.

Fix 3: a GitHub App installation token (recommended)

Create a small GitHub App with contents and pull request permissions, install it on the repo, store its ID and private key as secrets, then mint a short-lived token per run:

- uses: actions/create-github-app-token@v1 id: app with: app-id: ${{ vars.RELEASE_APP_ID }} private-key: ${{ secrets.RELEASE_APP_KEY }} - uses: actions/checkout@v4 with: token: ${{ steps.app.outputs.token }} 

Because checkout persists whatever token you give it, every later git push in that job now uses the App token, and the resulting events trigger workflows normally. The token expires after an hour and isn't tied to any person's account.

Fix 4: a personal access token (fastest, worst)

Same pattern, with token: ${{ secrets.RELEASE_PAT }}. It works in two minutes. It also means your release pipeline is now logged in as you, breaks when the token expires, and gets whatever access your account has unless you scope a fine-grained token carefully. I use this only for throwaway repos.

How do I avoid infinite loops after switching tokens?

You just removed the safety net GitHub gave you, so add your own. If a workflow on push to main also pushes to main with an App token, it will retrigger itself.

Three guards that work:

  • Put [skip ci] in bot commit messages. GitHub skips push and pull_request runs for commits that contain it.
  • Filter on the actor: if: github.actor != 'my-release-app[bot]' at the job level.
  • Push tags only, and trigger the loop-prone workflow on branches only. A tag push doesn't match branches: [main].

Pick at least one before you merge. A self-triggering release loop burns minutes fast and spams your Releases page with versions you'll have to delete.

How can I tell this is my problem in under a minute?

Check three things. Is there no run at all in the Actions tab for the expected trigger (not skipped, not failed, just absent)? Was the commit, tag or PR created by github-actions[bot]? Does the same action performed by hand trigger the workflow? Three yeses means you've hit the GITHUB_TOKEN rule and nothing in your YAML filters is wrong.

So why did 11 tags produce 0 release runs?

Because the tags were pushed with GITHUB_TOKEN, and in GitHub Actions any event created by GITHUB_TOKEN (pushes, tags, pull requests, releases) never starts a new workflow run, with only workflow_dispatch and repository_dispatch exempt. GitHub does this to prevent recursive runs, and it logs nothing when it drops the trigger. The fix is to stop relying on the event: call the downstream workflow with workflow_call or gh workflow run, which needs no extra secrets. If the event itself must trigger other workflows, such as CI on a bot-opened PR, push with a GitHub App installation token and add your own loop guard.

Written by the developer behind Preterview, an interview prep platform.