Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

docker pull from a private GitLab registry says access forbidden

Errordenied: access forbidden

Short answer

GitLab answers access forbidden when it accepts your credentials but they carry no registry permission. Give the token the read_registry scope, use a token instead of a password if two-factor is on, and check your project role. In CI, use the job token for the same project.

  • Applies to Docker Engine 28, GitLab Container Registry
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Log in again with a token read from stdin, then pull. The login result separates a bad credential from a missing permission.

    echo "$TOKEN" | docker login registry.example.com -u <username> --password-stdin
    docker pull registry.example.com/group/project/image:tag
  2. 2Match what you see, then jump to its fix

    1. 1docker login succeeds or fails, then pull says denied: access forbiddenThe token has no registry scopeFix
    2. 2Login with the account password is rejected although the password is rightTwo-factor authentication is on and you used your passwordFix
    3. 3The job log shows access forbidden for an image path that belongs to a different projectA CI job pulls an image from another projectFix
    4. 4Valid token, role and scope, but still access forbidden, and the instance sits behind a reverse proxyA proxy strips the Authorization headerFix

What does the error look like?

  • denied: access forbidden
  • access forbidden

Cause 1 of 4

The token has no registry scope

1Check

GitLab needs read_registry to pull, and read_registry plus write_registry to push. A token made for the API or Git alone does not carry it.

echo "$TOKEN" | docker login registry.example.com -u <username> --password-stdin

2Fix

Create a new personal, project or group access token (or a deploy token) with read_registry, and use it as the password. For pushing, add write_registry.

echo "$TOKEN" | docker login registry.example.com -u <username> --password-stdin

3Verify

The pull completes.

docker pull registry.example.com/group/project/image:tag

Confirmed by docs.gitlab.com

Did this fix it?

Cause 2 of 4

Two-factor authentication is on and you used your password

1Check

When two-factor authentication is enabled on the GitLab account, GitLab does not accept the password for the registry; a token is required.

echo "$PASSWORD" | docker login registry.example.com -u <username> --password-stdin

2Fix

Log in with a token that has read_registry as the password.

echo "$TOKEN" | docker login registry.example.com -u <username> --password-stdin

3Verify

docker login prints Login Succeeded.

docker pull registry.example.com/group/project/image:tag

Confirmed by docs.gitlab.com

Did this fix it?

Cause 3 of 4

A CI job pulls an image from another project

1Check

The CI job token has read and write access to the registry of the job's own project. Other projects are controlled by the job token allowlist.

grep -n 'CI_REGISTRY\|CI_JOB_TOKEN' .gitlab-ci.yml

2Fix

For the job's own project log in with the job token. For another project, add your project to that project's job token allowlist, or log in with a deploy token.

echo "$CI_JOB_TOKEN" | docker login $CI_REGISTRY -u $CI_REGISTRY_USER --password-stdin

3Verify

Re-run the pipeline and watch the pull step pass.

docker pull $CI_REGISTRY_IMAGE:latest

Confirmed by docs.gitlab.com

Did this fix it?

Cause 4 of 4

A proxy strips the Authorization header

1Check

GitLab names a proxy that removes the Authorization header on the /jwt/auth request as a cause of this error. Look for any proxy, load balancer or WAF between Docker and GitLab, and read its header rules.

docker pull registry.example.com/group/project/image:tag

2Fix

Change the proxy or load balancer so it forwards the Authorization header to GitLab unchanged, then log in again.

echo "$TOKEN" | docker login registry.example.com -u <username> --password-stdin

3Verify

The pull works once the header reaches GitLab.

docker pull registry.example.com/group/project/image:tag

Confirmed by docs.gitlab.com

Did this fix it?

How do I stop it coming back?

  • Use one token per purpose, with only read_registry for machines that pull.
  • Store tokens as CI variables or secrets and always pass them with --password-stdin.
  • Keep a note of token expiry dates so a pull does not fail on the day a token ends.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.