push-to-registry

Push-to-registry is a GitHub Action for pushing a container image or an image manifest to an image registry, such as Dockerhub, quay.io, the GitHub Container Registry, or an OpenShift integrated registry.

This action only runs on Linux, as it uses podman to perform the push. GitHub's Ubuntu action runners come with Podman preinstalled. If you are not using those runners, you must first install Podman.

You can log in to your container registry for the entire job using the podman-login action. Otherwise, use the username and password inputs to log in for this step.

Action Inputs

Refer to the podman push documentation for more information.

Input Name	Description	Default
image	Name of the image or manifest you want to push. Eg. username/imagename or imagename. Refer to Image and Tag Inputs. Automatically lowercased per OCI spec.	Required - unless all tags include registry and image name
tags	The tag or tags of the image or manifest to push. For multiple tags, separate by whitespace. Refer to Image and Tag Inputs. Tag case is preserved (OCI spec allows uppercase in tags).	latest
registry	Hostname and optional namespace to push the image to. Eg. quay.io or quay.io/username. Refer to Image and Tag Inputs. Automatically lowercased per OCI spec.	Required - unless all tags include registry and image name
username	Username with which to authenticate to the registry. Required unless already logged in to the registry.	None
password	Password, encrypted password, or access token to use to log in to the registry. Required unless already logged in to the registry.	None
tls-verify	Verify TLS certificates when contacting the registry. Set to false to skip certificate verification.	true
digestfile	After copying the image, write the digest of the resulting image to the file. The contents of this file are the digest output.	Auto-generated from image and tag
sigstore-private-key	Sigstore private key to use to sign container images.	None
sign-passphrase	Passphrase to unlock the Sigstore private key.	None
remote	Use podman in remote mode (--remote). When true, Docker image storage checks are skipped.	false
podman-args	Global args to be passed to all podman commands (before the subcommand). Use this for options like --storage-driver=vfs. Separate arguments by newline.	None
extra-args	Extra args to be passed to podman push. Separate arguments by newline. Do not use quotes.	None

Image, Tag and Registry Inputs

The push-to-registry image and tag input work very similarly to buildah-build.

However, when using push-to-registry when the tags input are not fully qualified, the registry input must also be set.

So, for push-to-registry the options are as follows:

Option 1: Provide registry, image, and tags inputs. The image(s) will be pushed to ${registry}/${image}:${tag}.

For example:

registry: quay.io/my-namespace
image: my-image
tags: v1 v1.0.0

will push the image tags: quay.io/my-namespace/my-image:v1 and quay.io/my-namespace/my-image:v1.0.0.

Option 2: Provide only the tags input, including the fully qualified image name in each tag. In this case, the registry and image inputs are ignored.

For example:

# 'registry' and 'image' inputs are not set
tags: quay.io/my-namespace/my-image:v1 quay.io/my-namespace/my-image:v1.0.0

will push the image tags: quay.io/my-namespace/my-image:v1 and quay.io/my-namespace/my-image:v1.0.0.

If the tags input does not have image names in the ${registry}/${name}:${tag} form, then the registry and image inputs must be set.

Multi-line tags: You can also provide tags on multiple lines using YAML pipe syntax:

tags: |
  v1
  v1.0.0
  latest

This is equivalent to tags: v1 v1.0.0 latest. Each line is treated as a separate tag.

Action Outputs

digest: The pushed image digest, as written to the digestfile.
For example:

sha256:66ce924069ec4181725d15aa27f34afbaf082f434f448dc07a42daa3305cdab3

For multiple tags, the digest is the same.

registry-paths: A JSON array of registry paths to which the tag(s) were pushed.

For example:

[ "quay.io/username/spring-image:v1", "quay.io/username/spring-image:latest" ]

registry-path: The first element of registry-paths, as a string.

Required Permissions

The permissions required depend on the target registry:

GitHub Container Registry (GHCR):

permissions:
  contents: read
  packages: write

• packages: write is required to push images to ghcr.io
• contents: read is required if you use actions/checkout in your workflow

Other registries (Quay.io, Docker Hub, private registries):

permissions:
  contents: read

• Authentication is handled via the username and password inputs, or by using podman-login beforehand
• No special GitHub token permissions are needed beyond contents: read for checkout

Pushing Manifest

If multiple tags are provided, either all tags must point to manifests, or none of them. i.e., you cannot push both manifests are regular images in one push-to-registry step.

Refer to Manifest Build and Push example for a sophisticated example of building and pushing a manifest.

Multi-architecture manifests: If you are building for architectures like arm64 or ppc64le, you need qemu-user-static installed. Use runs-on: ubuntu-24.04 which ships with qemu 8.2, as older versions have known issues with ppc64le (see #85).

Examples

The example below shows how the push-to-registry action can be used to push an image created by the buildah-build action.

name: Build and Push Image
on: [ push ]

permissions:
  contents: read

jobs:
  build:
    name: Build and push image
    runs-on: ubuntu-24.04

    steps:
    - uses: actions/checkout@v7

    - name: Build Image
      id: build-image
      uses: redhat-actions/buildah-build@v3
      with:
        image: my-app
        tags: latest ${{ github.sha }}
        containerfiles: |
          ./Containerfile

    # Podman Login action (https://github.com/redhat-actions/podman-login) also be used to log in,
    # in which case 'username' and 'password' can be omitted.
    - name: Push To quay.io
      id: push-to-quay
      uses: redhat-actions/push-to-registry@v3
      with:
        image: ${{ steps.build-image.outputs.image }}
        tags: ${{ steps.build-image.outputs.tags }}
        registry: quay.io/quay-user
        username: quay-user
        password: ${{ secrets.REGISTRY_PASSWORD }}

    - name: Print image url
      run: echo "Image pushed to ${{ steps.push-to-quay.outputs.registry-paths }}"

Refer to GHCR push example for complete example of push to GitHub Container Registry (GHCR).

Note about images built with Docker

This action uses Podman to push, but can also push images built with Docker. However, Docker and Podman store their images in different locations, and Podman can only push images in its own storage.

If the image to push is present in the Docker image storage but not in the Podman image storage, it will be pulled into Podman's storage.

If the image to push is present in both the Docker and Podman image storage, the action will push the image which was more recently built, and log a warning.

If the action pulled an image from the Docker image storage into the Podman storage, it will be cleaned up from the Podman storage before the action exits.

Podman Remote Mode

If you are using podman --remote (e.g. with a wrapper or a remote podman server), set remote: true:

- uses: redhat-actions/push-to-registry@v3
  with:
    image: my-image
    tags: latest
    registry: quay.io/my-namespace
    remote: true

When remote is enabled:

• --remote is automatically passed to all podman commands
• Docker image storage checks are skipped (the Docker daemon is not accessible over the remote connection)
• All image tags must be present in the remote Podman image storage
• Temporary local storage creation is skipped (not relevant for remote operations)

Note about GitHub runners and Podman

We recommend using runs-on: ubuntu-24.04 since it has a newer version of Podman.

If you are on ubuntu-22.04 or any other older versions of ubuntu your workflow will use an older version of Podman and may encounter issues such as #26.

Troubleshooting

Note that quay.io repositories are private by default.

This means that if you push an image for the first time, you will have to authenticate before pulling it, or go to the repository's settings and change its visibility.

Similarly, if you receive a 403 Forbidden from GHCR, you may have to update the Package Settings. Refer to this issue.