Debugging a 403ed GitHub Actions Auto-Commit

The workflow was almost perfect: it validated, transformed, optimized, and then — the part everyone expects to be magic — pushed the optimized output back to main. The collector's last step died with two cryptic lines:

remote: Permission to owner/repo.git denied to github-actions[bot].
fatal: unable to access 'https://github.com/...': The requested URL returned error: 403
Error: Invalid status code: 128

The optimization actually did its job — the check:palette and asset steps ran fine. What failed was the final auto-commit push. The cause is boring, predictable, and fixable in two lines.

The default GITHUB_TOKEN is read-only

GitHub injects a GITHUB_TOKEN into every workflow run. For newer repositories the default this token grants is read for contents — enough to check out the repo, not enough to push back. So any step that commits and pushes falls over at the moment of truth with 403 / exit 128.

The telltale sign that you're hitting this and not an auth misconfiguration: the 403 names github-actions[bot] specifically. It's not that your login is wrong — it's that the token has no room to write.

The fix: a two-line permissions block

At the top of the workflow, before any job, declare the permission you actually need:

permissions:
  contents: write

That single block grants the workflow's GITHUB_TOKEN write access to repo contents, which is exactly what an auto-commit needs. (Use the principle of least privilege: give it contents: write only when a job genuinely commits and pushes; workflows that only read should not carry it.)

The result is immediate and boring: the auto-commit pushes, the pipeline completes, and the generated changes land on main as a real commit.

The misleading flags (least-surprise guardrails)

While diagnosing, the logs also showed two non-fatal warnings that pointed in the wrong direction if you don't know what they mean:

Unexpected inputs 'commit_if_no_changes', 'skip_check_run'
lint-staged could not find any staged files matching configured tasks.

• commit_if_no_changes and skip_check_run are inputs the action version you're using doesn't declare — harmless "unexpected input" warnings, not the cause.
• The lint-staged message is the action's pre-commit hook failing to find staged files matching its tasks. It's a warning; the action proceeds. It can make you chase a lint-staged config that isn't the problem.

Neither causes the 403. Be suspicious of both but don't fix them first.

The sequence that actually proves it

The clean diagnostic order:

1. Read the final step log and confirm the failure is at push time and names github-actions[bot] — that pins it to token scope.
2. Confirm the earlier transform/validate steps passed (they did in our case) — that rules out a data or content problem.
3. Add permissions: contents: write at the workflow root.
4. Re-run. The auto-commit now pushes successfully, and the resulting auto-generated commit on main is your proof.

A self-sustaining artifact pipeline — optimize assets, push the result, let CI revalidate — is powerful. But it quietly depends on the token having write access, and the default no longer grants it. Two lines of YAML turn a failing auto-commit into the boring background machinery it was always meant to be.