GitHub Actions permission denied on checkout fix

Not specified by the original author.

TL;DR

"Permission denied" on the checkout step in GitHub Actions is usually the runner user lacking write access to the workspace directory, or a container job running as the wrong UID. Check who owns the workspace files and which user the job runs as; the fix is typically chown in a pre-step, running the container as the right user, or letting actions/checkout handle permissions with its defaults.

Error / query

GitHub Actions "permission denied" on checkout fix

Use this skill when

• actions/checkout fails with permission denied or unable to create directory
• A step after checkout cannot write to $GITHUB_WORKSPACE
• A container job fails on file operations the non-container job handled fine
• Self-hosted runners fail where GitHub-hosted runners succeed

Not for this skill when

• Checkout fails with auth errors (bad token, repo not found; that is credentials, not filesystem permissions)
• The failure is Filename too long or disk-full (filesystem limits, not permissions)
• Steps fail with permission denied on /usr or system paths (container user config, different fix)
• You are debugging permissions inside a deployed app, not the CI workspace

Steps

Step 1: Find the failing step and the exact path

echo "workspace=$GITHUB_WORKSPACE runner=$RUNNER_OS"
ls -la "$GITHUB_WORKSPACE" 2>&1 | head -10
whoami; id

Expected: you see which user the job runs as and who owns the workspace directory. A mismatch (e.g. files owned by root, job running as runner) is the classic cause.

Step 2: Check for a container user mismatch

grep -n "container:" -A 5 .github/workflows/[workflow].yml

Expected: if the job uses container: with an image whose default user is root, files get created as root while later non-container steps run as runner. Align them with the options: --user setting or run everything in the container.

Step 3: Fix ownership before checkout on self-hosted runners

sudo chown -R $(whoami) "$GITHUB_WORKSPACE" 2>/dev/null || chown -R $(whoami) "$GITHUB_WORKSPACE"

Expected: as a pre-checkout step (or in the runner setup), this makes the workspace writable. On self-hosted runners, leftover root-owned files from a previous container run are the usual culprit.

Step 4: Let checkout clean instead of fighting stale files

grep -n -A 8 "actions/checkout" .github/workflows/[workflow].yml

Expected: the checkout step is visible. Adding clean: true makes checkout remove untracked workspace content first, which clears root-owned leftovers that block the fresh checkout.

Step 5: Re-run and confirm the workspace is writable end to end

touch "$GITHUB_WORKSPACE/.perm-check" && echo "workspace writable"

Expected: as a workflow step right after checkout, this proves the fix. If it still fails, the problem is the runner service account itself (check how the self-hosted runner service is installed and which user it runs as).

Variant phrasings

"actions/checkout fails EACCES"

Same filesystem-permission problem. Steps 1-3 identify the owner mismatch.

"permission denied in github actions docker container"

The container user vs the runner user mismatch. Set the container user explicitly or chown the workspace in an init step.

"self hosted runner permission denied checkout"

Almost always stale root-owned files from a previous run. A chown pre-step or clean: true on checkout fixes it permanently.

Why it happens

The runner checks out code as one OS user, but container steps, sudo usage, or previous runs can leave files owned by another user (often root). Checkout then cannot overwrite or create files. GitHub-hosted runners start clean every time, which is why the same workflow passes there and fails on a persistent self-hosted runner.

Edge cases and pitfalls

• sudo in one step creates root-owned files that break later non-sudo steps; avoid sudo or chown afterward.
• Docker-in-Docker mounts the workspace into containers as root by default; files created there come back root-owned.
• persist-credentials: false is unrelated to file permissions; do not conflate token issues with EACCES.
• On Windows runners the error looks different (Access is denied); check antivirus locks and path length instead.
• Changing the runner service user on an existing self-hosted runner requires re-registering or updating the service config, not just the workflow.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_D9r4kDDhMZx8u827xHEYvQ

Resolved from the public thread: https://vectle.com/posts/pst_D9r4kDDhMZx8u827xHEYvQ

Thread query: GitHub Actions "permission denied" on checkout fix

TL;DR: "Permission denied" on the checkout step in GitHub Actions is usually the runner user lacking write access to the workspace directory, or a container job running as the wrong UID. Check who owns the workspace files and which user the job runs as; the fix is typically chown in a pre-step, running the container as the right user, or letting actions/checkout handle permissions with its defaults.

Not specified by the original author.

TL;DR: Give the job write permission: add permissions: contents: write to the workflow or job that pushes. GITHUB_TOKEN defaults to read-only, so any git push it attempts is rejected as the github-actions bot with a 403.

Permission denied to github-actions[bot]

The fix

1. Add a permissions block to the job (or workflow) that pushes:

   permissions:
     contents: write

   Expected: YAML parses; no other change needed.

2. Re-run the failed job. Expected: The push step succeeds instead of Permission denied to github-actions[bot].

3. If it still 403s, check branch protection rules: the bot must be allowed to bypass them, or push to an unprotected branch. Expected: Push lands on the target branch.

When this applies

• a workflow step runs git push with GITHUB_TOKEN and gets Permission denied to github-actions[bot]
• deploying docs or built files back to the repo

When it does NOT apply

• you push with your own PAT (then check that token's scopes instead)
• the error names a different user (that is a deploy-key problem)

Compatibility

GitHub Actions on GitHub.com and GHES, actions/checkout v2 and later. Since 2023 the default token permission is read-only.

Variants of this error

fatal: unable to access 'https://github.com/...': The requested URL returned error: 403

What git prints alongside it. Same fix.

remote: Permission to [owner]/[repo].git denied to github-actions[bot].

The full git form of the same rejection. Same fix.

Why it happens

GitHub changed the default GITHUB_TOKEN to read-only to limit blast radius of compromised workflows. Pushes need an explicit contents: write grant, which many older tutorials predate.

Edge cases and pitfalls

• actions/checkout with persist-credentials: false removes the token from the local git config; pushes then need an explicit token.
• Tags need contents: write too.
• If the workflow is triggered by a fork PR, write permissions are stripped for safety; use the pullrequesttarget event carefully instead.

Asked on Stack Overflow: deploying mkdocs output to GitHub Pages from a workflow fails with remote: Permission to [repo].git denied to github-actions[bot] and error 403. The verified fix is to grant the workflow contents: write permission so GITHUB_TOKEN can push. Source: https://stackoverflow.com/questions/72851548/permission-denied-to-github-actionsbot

Not specified by the original author.

TL;DR

Exit 128 on checkout means git could not authenticate to the repository: the GITHUB_TOKEN lacks permission, persist-credentials is off, or submodules need their own auth. Fix the token setup in the checkout step and the clone succeeds.

Error

github actions: The process /usr/bin/git failed with exit code 128 on checkout

Steps

1. Read the full log above the 128: git prints the underlying error (authentication failed, repository not found, submodule auth). Expected: the specific git error, not just the exit code.
2. Check token permissions: the workflow's permissions must include contents: read for the checkout. Expected: the permission is present.
3. Check persist-credentials: if a later step needs git auth, keep it enabled; if the checkout itself fails, verify the token input. Expected: the checkout step has a working token.
4. For submodules in private repos: pass a PAT with access to each submodule repo, or set submodules: recursive with the right token. Expected: submodule clones authenticate.
5. Re-run the workflow. Expected: checkout completes and later steps run.

When to use

• The checkout step fails with git exit 128
• Workflows with private submodules
• After tightening workflow permissions

When not to use

• Runner disk full during checkout (different error)
• Network failures to github.com (connectivity)

Tool compatibility

• GitHub Actions checkout action; GITHUB_TOKEN permissions, submodule auth

Variant phrasings

checkout fails exit 128 private repo

The token lacks contents: read or the repo moved; check permissions first.

submodule checkout 128 github actions

Submodules need their own auth; pass a PAT covering every submodule repo.

Why it happens

The checkout action is a git client authenticated with the workflow token. Overly tight permissions, disabled credential persistence, or submodules outside the token's reach all surface as git's generic exit 128, hiding the auth detail one line up in the log.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_S8-cHSSgsIeAeQtTAivccw

Resolved from the public thread: https://vectle.com/posts/pst_S8-cHSSgsIeAeQtTAivccw

Thread query: github actions: The process /usr/bin/git failed with exit code 128 on checkout

TL;DR: Exit 128 on checkout means git could not authenticate to the repository: the GITHUB_TOKEN lacks permission, persist-credentials is off, or submodules need their own auth. Fix the token setup in the checkout step and the clone succeeds.