Maaz Zindani

Loading the index…

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

A GitHub Actions workflow builds the Docker image but cannot push it

ErrorThe build-push-action step is green but the image never shows up in the registry

Short answer

Four things stop a push from GitHub Actions: build-push-action does not push unless push is true, the Docker Hub login used a password instead of an access token, the workflow token lacks packages write for ghcr.io, or the run comes from a fork, where the token is read-only.

  • Applies to docker/build-push-action, docker/login-action, GitHub-hosted ubuntu-24.04 runner
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Open the failing step in the Actions log and check three things in the workflow file: the push input, which registry the login step targets, and which event triggered the run.

    grep -n -E "push:|registry:|username:|permissions:|on:" .github/workflows/*.yml
  2. 2Match what you see, then jump to its fix

    1. 1The build step passes and the log shows no upload, with no error at all.The push input was never set to trueFix
    2. 2The failure comes at or right after the login step and Docker Hub rejects the credentials.Docker Hub login with the account password instead of an access tokenFix
    3. 3The registry is ghcr.io, the login works, and the push is refused.Pushing to ghcr.io without write access for the workflow tokenFix
    4. 4Pushes work on your own branches and fail only for pull requests opened from a fork.The run is triggered by a pull request from a forkFix

What does the error look like?

  • The build-push-action step is green but the image never shows up in the registry
  • The push step fails right after the login step
  • The push works on a branch of your repository but not on a pull request from a fork

Cause 1 of 4

The push input was never set to true

1Check

The push input of build-push-action defaults to false; it is a shorthand for the registry output type. Without it the action only builds the image.

grep -n -B2 -A6 "build-push-action" .github/workflows/*.yml

2Fix

Set push to true and give tags that include your namespace, comma-separated.

- uses: docker/build-push-action@v7
  with:
    push: true
    tags: your-namespace/app:latest,your-namespace/app:1.0.0

3Verify

Run the workflow again; the push appears in the step log and the tag shows in the registry.

docker pull your-namespace/app:latest

Confirmed by github.com

Did this fix it?

Cause 2 of 4

Docker Hub login with the account password instead of an access token

1Check

docker/login-action asks for a username and a personal access token for Docker Hub, and says not to use the account password.

grep -n -E "DOCKERHUB|secrets\." .github/workflows/*.yml

2Fix

Create an access token in your Docker Hub account, store it as a repository secret and use it in the login step.

- uses: docker/login-action@v4
  with:
    username: ${{ vars.DOCKERHUB_USERNAME }}
    password: ${{ secrets.DOCKERHUB_TOKEN }}

3Verify

The login step passes and the push step proceeds.

docker pull your-namespace/app:latest

Confirmed by github.com

Did this fix it?

Cause 3 of 4

Pushing to ghcr.io without write access for the workflow token

1Check

For ghcr.io the login uses the registry ghcr.io, the user github.actor and the GITHUB_TOKEN. GitHub says the token needs read for contents and write for packages, set in the workflow. An existing package can also restrict which repositories may write to it.

grep -n -A4 "permissions:" .github/workflows/*.yml

2Fix

Grant the job packages write, and check the package's Actions access in its settings.

permissions:
  contents: read
  packages: write
steps:
  - uses: docker/login-action@v4
    with:
      registry: ghcr.io
      username: ${{ github.actor }}
      password: ${{ secrets.GITHUB_TOKEN }}

3Verify

The push step finishes and the package appears under the repository's Packages.

docker pull ghcr.io/your-owner/app:latest

Confirmed by docs.github.com

Did this fix it?

Cause 4 of 4

The run is triggered by a pull request from a fork

1Check

GitHub gives forks only read access to the parent repository for the workflow token, so a registry push cannot succeed there.

grep -n -E "pull_request|github.event_name" .github/workflows/*.yml

2Fix

Build on pull requests but push only on events from your own repository, such as a push to main.

- uses: docker/build-push-action@v7
  with:
    push: ${{ github.event_name != 'pull_request' }}
    tags: ghcr.io/your-owner/app:latest

3Verify

A fork pull request builds without trying to push, and a merge to main pushes.

docker pull ghcr.io/your-owner/app:latest

Confirmed by docs.github.com

Did this fix it?

How do I stop it coming back?

  • Keep registry tokens in repository secrets and give them only the scope the push needs.
  • Declare the permissions block on every job that pushes, so the token never depends on a default.
  • Push only on trusted events; let pull requests build and test without publishing.
  • Use one tag naming rule that includes your namespace so a tag never points at the wrong repository.

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.