Skip to content

feat(docker): support structured OCI registry inputs for separate pull, push, and cache targets #685

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
neilime merged 7 commits into from
Mar 12, 2026
Merged

feat(docker): support structured OCI registry inputs for separate pull, push, and cache targets #685

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
7db723f
feat: support structured OCI registry inputs
Copilot Mar 10, 2026
733ed59
fix: align structured registry keys with review
Copilot Mar 11, 2026
d394437
docs: clarify reviewed registry role format
Copilot Mar 11, 2026
81b7db4
docs: describe scalar registry inputs as default
Copilot Mar 11, 2026
6a40375
refactor: share docker setup and registry auth
Copilot Mar 12, 2026
f00ebb6
fix: simplify shared docker setup auth
Copilot Mar 12, 2026
33885df
fix: harden docker build-image config script
Copilot Mar 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions .github/workflows/__shared-ci.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,12 @@ jobs:
uses: ./.github/workflows/__test-workflow-docker-build-images-caching.yml
secrets: inherit

test-workflow-docker-build-images-multi-registry:
name: Test docker build images - Multi registry inputs
needs: linter
uses: ./.github/workflows/__test-workflow-docker-build-images-multi-registry.yml
secrets: inherit

test-workflow-docker-build-images-platforms-and-signing:
name: Test docker build images - Platforms and Signing
needs: linter
Expand Down
88 changes: 88 additions & 0 deletions .github/workflows/__test-workflow-docker-build-images-multi-registry.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,88 @@
---
name: Test for "docker-build-images" workflow - Multi registry inputs
run-name: Test for "docker-build-images" workflow - Multi registry inputs

on: # yamllint disable-line rule:truthy
workflow_call:

permissions:
contents: read
issues: read
packages: write
pull-requests: read
id-token: write

jobs:
act-build-images-multi-registry:
name: Act - Build images with structured registry inputs
uses: ./.github/workflows/docker-build-images.yml
secrets:
oci-registry-password: |
{"push":"${{ secrets.GITHUB_TOKEN }}","pull:private":"${{ secrets.GITHUB_TOKEN }}"}
build-secret-github-app-key: ${{ secrets.CI_BOT_APP_PRIVATE_KEY }}
with:
cache-type: "registry"
sign: false
oci-registry: |
{"pull":"docker.io","pull:private":"ghcr.io","push":"ghcr.io"}
oci-registry-username: |
{"push":"${{ github.repository_owner }}","pull:private":"${{ github.repository_owner }}"}
images: |
[
{
"name": "test-multi-registry-inputs",
"context": ".",
"dockerfile": "./tests/application/Dockerfile",
"build-args": { "BUILD_RUN_ID": "${{ github.run_id }}" },
"target": "prod",
"platforms": ["linux/amd64"]
}
]

assert-multi-registry:
name: Assert - Build images with structured registry inputs
needs: act-build-images-multi-registry
runs-on: ubuntu-latest
steps:
- name: Login to GitHub Container Registry
uses: docker/login-action@b45d80f862d83dbcd57f89517bcf500b2ab88fb2 # v4.0.0
with:
registry: ghcr.io
username: ${{ github.repository_owner }}
password: ${{ github.token }}

- name: Assert built image output and pullability
uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
env:
BUILT_IMAGES: ${{ needs.act-build-images-multi-registry.outputs.built-images }}
EXPECTED_IMAGE: ghcr.io/${{ github.repository }}/test-multi-registry-inputs
with:
script: |
const assert = require("assert");
const sha = `${{ github.sha }}`;

const builtImages = JSON.parse(process.env.BUILT_IMAGES);
const builtImage = builtImages["test-multi-registry-inputs"];

assert(builtImage, `"built-images" output does not contain "test-multi-registry-inputs" image`);
assert.equal(builtImage.registry, "ghcr.io", `"registry" output is not valid`);
assert.match(builtImage.digest, /^sha256:[0-9a-f]{64}$/, `"digest" output is not valid`);

const expectedTag = `${{ github.event_name }}` === "pull_request"
? `pr-${{ github.event.pull_request.number }}-${sha.substring(0, 7)}`
: `${{ github.ref_name }}`;

const expectedImage = `${process.env.EXPECTED_IMAGE}:${expectedTag}@${builtImage.digest}`;
assert.equal(builtImage.images[0], expectedImage, `"image" output is not valid`);

await exec.exec("docker", ["pull", expectedImage]);

- name: Assert registry cache usage with structured inputs
uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
env:
EXPECTED_CACHE_IMAGE: ghcr.io/${{ github.repository }}/test-multi-registry-inputs/cache
EXPECTED_CACHE_TAG: ${{ github.event_name == 'pull_request' && format('pr-{0}', github.event.pull_request.number) || github.ref_name }}
with:
script: |
const cacheImage = `${process.env.EXPECTED_CACHE_IMAGE}:${process.env.EXPECTED_CACHE_TAG}-linux-amd64`;
await exec.exec("docker", ["manifest", "inspect", cacheImage]);
64 changes: 52 additions & 12 deletions .github/workflows/docker-build-images.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,11 +73,18 @@ jobs:
# Default: `["ubuntu-latest"]`
runs-on: '["ubuntu-latest"]'

# OCI registry where to pull and push images
# OCI registry configuration used to pull, push and cache images.
# Accepts either a registry hostname string or a JSON object with
# `pull`, `pull:<name>`, `push` and `cache` keys.
# Example:
# `{"pull":"docker.io","pull:private":"ghcr.io","push":"ghcr.io"}`
# Default: `ghcr.io`
oci-registry: ghcr.io

# Username used to log against the OCI registry.
# Username configuration used to log against OCI registries.
# Accepts either a single username string or a JSON object using the same keys as `oci-registry`.
# Example:
# `{"pull:private":"${{ github.repository_owner }}","push":"${{ github.repository_owner }}"}`
# See https://github.com/docker/login-action#usage.
#
# Default: `${{ github.repository_owner }}`
Expand Down Expand Up @@ -165,8 +172,10 @@ jobs:
| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | ----------- | -------------------------------- |
| **`runs-on`** | Runner to use. JSON array of runners. | **false** | **string** | `["ubuntu-latest"]` |
| | See <https://docs.github.com/en/actions/using-jobs/choosing-the-runner-for-a-job>. | | | |
| **`oci-registry`** | OCI registry where to pull and push images | **false** | **string** | `ghcr.io` |
| **`oci-registry-username`** | Username used to log against the OCI registry. | **false** | **string** | `${{ github.repository_owner }}` |
| **`oci-registry`** | OCI registry configuration used to pull, push and cache images. | **false** | **string** | `ghcr.io` |
| | Accepts a single registry hostname or a JSON object with `pull`, `pull:<name>`, `push` and `cache` keys. | | | |
| **`oci-registry-username`** | Username configuration used to log against OCI registries. | **false** | **string** | `${{ github.repository_owner }}` |
| | Accepts a single username or a JSON object using the same keys as `oci-registry`. | | | |
| | See <https://github.com/docker/login-action#usage>. | | | |
| **`images`** | Images to build parameters. | **true** | **string** | - |
| | JSON array of objects. | | | |
Expand All @@ -193,17 +202,48 @@ jobs:

## Secrets

| **Secret** | **Description** | **Required** |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------ |
| **`oci-registry-password`** | Password or GitHub token (`packages:read` and `packages:write` scopes) used to log against the OCI registry. | **true** |
| | See <https://github.com/docker/login-action#usage>. | |
| **`build-secrets`** | List of secrets to expose to the build. | **false** |
| | See <https://docs.docker.com/build/ci/github-actions/secrets/>. | |
| **`build-secret-github-app-key`** | GitHub App private key to generate GitHub token to be passed as build secret env. | **false** |
| | See <https://github.com/actions/create-github-app-token>. | |
| **Secret** | **Description** | **Required** |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------ |
| **`oci-registry-password`** | Password or GitHub token (`packages:read` and `packages:write` scopes) configuration used to log against OCI registries. | **true** |
| | Accepts a single password/token or a JSON object using the same keys as `oci-registry`. | |
| | See <https://github.com/docker/login-action#usage>. | |
| **`build-secrets`** | List of secrets to expose to the build. | **false** |
| | See <https://docs.docker.com/build/ci/github-actions/secrets/>. | |
| **`build-secret-github-app-key`** | GitHub App private key to generate GitHub token to be passed as build secret env. | **false** |
| | See <https://github.com/actions/create-github-app-token>. | |

<!-- secrets:end -->

## Multiple registries

The default single-registry format still works:

```yaml
with:
oci-registry: ghcr.io
oci-registry-username: ${{ github.repository_owner }}
secrets:
oci-registry-password: ${{ github.token }}
```

To configure distinct pull, push and cache registries, pass JSON objects:

```yaml
with:
oci-registry: |
{"pull":"docker.io","pull:private":"ghcr.io","push":"ghcr.io"}
oci-registry-username: |
{"pull:private":"${{ github.repository_owner }}","push":"${{ github.repository_owner }}"}
secrets:
oci-registry-password: |
{"pull:private":"${{ github.token }}","push":"${{ github.token }}"}
```

Registry credentials are resolved by role using the same keys as `oci-registry`.
`pull` is the default pull registry, while `pull:<name>` can be repeated for additional pull registries.
When no pull registry is provided, the push registry is also used for pulls.
Optional pull registries without credentials are skipped, which is useful for public registries such as Docker Hub.

### Images entry parameters

| **Parameter** | **Description** | **Default** | **Required** |
Expand Down
19 changes: 16 additions & 3 deletions .github/workflows/docker-build-images.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,13 +15,24 @@ on: # yamllint disable-line rule:truthy
default: '["ubuntu-latest"]'
required: false
oci-registry:
description: "OCI registry where to pull and push images"
description: |
OCI registry configuration used to pull, push and cache images.
Accepts either a registry hostname string (default format) or a JSON object.
JSON example: `{"pull":"docker.io","pull:private":"ghcr.io","push":"ghcr.io"}`
JSON object keys:
- `pull`: registry used to pull public or default base images
- `pull:<name>`: additional pull registry
- `push`: registry used for published images
- `cache`: registry used when `cache-type` is `registry`
If no `pull` key is provided, the `push` registry is also used for pulls.
type: string
default: "ghcr.io"
required: false
oci-registry-username:
description: |
Username used to log against the OCI registry.
Username configuration used to log against OCI registries.
Accepts either a single username string (default format) or a JSON object using the same keys as `oci-registry`.
JSON example: `{"pull:private":"$\{{ github.repository_owner }}","push":"$\{{ github.repository_owner }}"}`
See https://github.com/docker/login-action#usage.
type: string
default: ${{ github.repository_owner }}
Expand Down Expand Up @@ -103,7 +114,9 @@ on: # yamllint disable-line rule:truthy
secrets:
oci-registry-password:
description: |
Password or GitHub token (`packages:read` and `packages:write` scopes) used to log against the OCI registry.
Password or GitHub token (`packages:read` and `packages:write` scopes) configuration used to log against OCI registries.
Accepts either a single password/token string (default format) or a JSON object using the same keys as `oci-registry`.
JSON example: `{"pull:private":"$\{{ github.token }}","push":"$\{{ github.token }}"}`
See https://github.com/docker/login-action#usage.
required: true
build-secrets:
Expand Down
2 changes: 2 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,8 @@ _Actions that operate on OCI images across their build, metadata, and lifecycle

#### - [Prune pull requests image tags](actions/docker/prune-pull-requests-image-tags/README.md)

#### - [Setup](actions/docker/setup/README.md)

#### - [Sign images](actions/docker/sign-images/README.md)

### Helm
Expand Down
Loading
Loading