docker/login-action

Official actionCategory: Docker & ContainersLatest v3View on GitHub

What it does

docker/login-action authenticates the Docker CLI to a registry using credentials from secrets, so a subsequent build-push or push succeeds.

For GitHub Container Registry (ghcr.io) it can use the built-in GITHUB_TOKEN.

Usage

workflow (.yml)

steps:
  - uses: docker/login-action@v3
    with:
      registry: ghcr.io
      username: ${{ github.actor }}
      password: ${{ secrets.GITHUB_TOKEN }}

Inputs

Input	Description	Default	Required
`registry`	Registry host. Omit for Docker Hub.	`docker.io`	No
`username`	Registry username.	-	No
`password`	Registry password or token.	-	No
`logout`	Log out at the end of the job.	`true`	No

Notes

To push to ghcr.io with GITHUB_TOKEN the job needs permissions: packages: write.

Common errors

unauthorized: authentication required on push means login did not run or used the wrong registry host. Match registry to the image prefix.
GHCR pushes failing with a permission error usually lack packages: write in the job permissions:.

Security and pinning

Always source password from a secret. Prefer short-lived tokens (GITHUB_TOKEN for GHCR, OIDC for cloud registries) over long-lived credentials.

Alternatives and related

docker/build-push-actionBuild and push a Docker image using Buildx, with cache and multi-platform support. aws-actions/amazon-ecr-loginLog in to Amazon ECR so a workflow can pull and push container images.

Frequently asked questions

How do I push to GitHub Container Registry?