Why does my Bitbucket pipeline fail with a permission denied error when accessing Docker registry?

Why the error appears

When docker push returns permission denied, the Docker daemon has authenticated with the registry but the target repository or image name is not allowed for the supplied credentials. In Pipelines this usually means one of three things:

• The docker login step never ran or used the wrong username/password.
• The credentials are correct but lack push rights for the repository.
• Network or TLS issues cause the login to succeed locally but fail when the daemon talks to the registry from the runner.

Confirm that the Docker daemon is using the right credentials

Insert a short diagnostic step immediately after the login command:

script:
  - docker login -u $DOCKER_USER -p $DOCKER_PASSWORD $REGISTRY
  - docker info | grep "Username"
  - docker config inspect | grep -i $REGISTRY

The docker info output should show the logged‑in user. The docker config inspect command will list the auth entry for your registry; confirm the auth field is present and not empty. If the user line is missing, the login failed silently – check that the environment variables are correctly named and marked as secured in the repo settings.

Verify network connectivity and TLS trust

From the same step, run:

script:
  - curl -v https://$REGISTRY
  - docker pull $REGISTRY/hello-world:latest

If curl fails with a TLS error, you need to trust the registry’s certificate on the runner. Add the CA to the Docker daemon’s ca.crt file or use the --tls-verify=false flag for testing (not recommended for production).

Common TLS pitfalls

• Self‑signed certs: copy the cert into /etc/docker/certs.d/$REGISTRY/ca.crt on the runner.
• Intermediary proxies: ensure the runner can reach the registry endpoint without going through a proxy that strips TLS.

Check the registry’s permission model

Log into the registry’s web UI or API with the same credentials and verify that the user has push rights for the target repository. For example, in Harbor you can inspect the role assignments for the account.

Also confirm the image name and tag you are pushing match the repository exactly. A common mistake is a missing organization prefix or a mistyped tag.

Bitbucket Pipeline logs that help

• Enable docker login --debug to see the full authentication exchange.
• Look for the DOCKER_USER and DOCKER_PASSWORD in the pipeline log – they should appear as masked values (e.g., ****).
• If the runner is self‑hosted, check its firewall rules to ensure outbound traffic on port 443 (or 5000 for HTTP) is allowed.

Quick checklist before re‑running

1. Verify secured variables: DOCKER_USER, DOCKER_PASSWORD, REGISTRY.
2. Run docker login manually on the runner and confirm you can pull and push a test image.
3. Confirm the registry’s TLS certificate is trusted or disable verification for a test run.
4. Ensure the user’s role includes push rights for the target repo.
5. Re‑run the pipeline with --debug flags turned on for Docker commands.

Follow‑up question

If the error persists after these checks, please let us know whether your registry uses a self‑signed certificate or requires a bearer token instead of a username/password. That will determine whether you need to add a custom ~/.docker/config.json entry or switch to docker login --username $DOCKER_USER --password-stdin with a token.