Skip to content

docker-build-images.md

Latest commit

 

History

History
359 lines (283 loc) · 41.2 KB

docker-build-images.md

File metadata and controls

359 lines (283 loc) · 41.2 KB

GitHub Reusable Workflow: Docker build images

Docker build images

Release License Stars PRs Welcome

Overview

Workflow to build multiple Docker images. Build images using Docker build image. This includes multi-platform build.

Permissions

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

Usage

name: Docker build images
on:
  push:
    branches:
      - main
permissions: {}
jobs:
  docker-build-images:
    uses: hoverkraft-tech/ci-github-container/.github/workflows/docker-build-images.yml@e4bf7a12228a2a4b5993d2d36b99b4dd0ec80bf5 # 0.32.1
    permissions: {}
    secrets:
      # 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.
      #
      # This input is required.
      oci-registry-password: ""

      # List of secrets to expose to the build.
      # See https://docs.docker.com/build/ci/github-actions/secrets/.
      build-secrets: ""

      # GitHub App private key to generate GitHub token to be passed as build secret env.
      # See https://github.com/actions/create-github-app-token.
      build-secret-github-app-key: ""
    with:
      # Runner to use. JSON array of runners.
      # See https://docs.github.com/en/actions/using-jobs/choosing-the-runner-for-a-job.
      #
      # Default: `["ubuntu-latest"]`
      runs-on: '["ubuntu-latest"]'

      # 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.
      #
      # Default: `ghcr.io`
      oci-registry: ghcr.io

      # 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.
      #
      # Default: `${{ github.repository_owner }}`
      oci-registry-username: ${{ github.repository_owner }}

      # Images to build parameters.
      # JSON array of objects.
      # Example:
      # ```json
      # [
      # {
      # "name": "application",
      # "context": ".",
      # "dockerfile": "./docker/application/Dockerfile",
      # "target": "prod",
      # "build-args": {
      # "APP_PATH": "./application/",
      # "PROD_MODE": "true"
      # },
      # "secret-envs": {
      # "GH_TOKEN": "GITHUB_TOKEN"
      # },
      # "platforms": [
      # "linux/amd64",
      # {
      # "name": "darwin/amd64",
      # "runs-on": "macos-latest"
      # }
      # ]
      # }
      # ]
      # ```
      #
      # This input is required.
      images: ""

      # Enable Git LFS.
      # See https://github.com/actions/checkout?tab=readme-ov-file#usage.
      #
      # Default: `true`
      lfs: true

      # Environment variable name(s) to pass GitHub token generated by GitHub App.
      # Can be a multiline string list.
      # This is useful to pass a generated token to the build, as it is not possible to share generated secrets between jobs.
      # Needs input `build-secret-github-app-id` and secret `build-secret-github-app-key`.
      #
      # Default: `GITHUB_APP_TOKEN`
      build-secret-github-app-token-env: GITHUB_APP_TOKEN

      # GitHub App ID to generate GitHub token to be passed as build secret env.
      # See https://github.com/actions/create-github-app-token.
      build-secret-github-app-id: ""

      # The owner of the GitHub App installation.
      # See https://github.com/actions/create-github-app-token.
      #
      # Default: `${{ github.repository_owner }}`
      build-secret-github-app-owner: ${{ github.repository_owner }}

      # Cache type.
      # See https://docs.docker.com/build/cache/backends.
      #
      # Default: `gha`
      cache-type: gha

      # Inline BuildKit daemon configuration.
      # See https://github.com/docker/setup-buildx-action#inputs.
      # Example for insecure registry:
      # ```ini
      # [registry."my-registry.local:5000"]
      # http = true
      # insecure = true
      # ```
      buildkitd-config-inline: ""

      # Sign built images.
      # See [sign-images](../../actions/docker/sign-images/README.md).
      #
      # Default: `true`
      sign: true

Inputs

Workflow Call Inputs

Input Description Required Type Default
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 configuration used to pull, push and cache images. false string ghcr.io
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.
oci-registry-username Username configuration used to log against OCI registries. false string ${{ github.repository_owner }}
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.
images Images to build parameters. true string -
JSON array of objects.
Example: 
[
 {
 "name": "application",
 "context": ".",
 "dockerfile": "./docker/application/Dockerfile",
 "target": "prod",
 "build-args": {
 "APP_PATH": "./application/",
 "PROD_MODE": "true"
 },
 "secret-envs": {
 "GH_TOKEN": "GITHUB_TOKEN"
 },
 "platforms": [
 "linux/amd64",
 {
 "name": "darwin/amd64",
 "runs-on": "macos-latest"
 }
 ]
 }
]
lfs Enable Git LFS. false boolean true
See https://github.com/actions/checkout?tab=readme-ov-file#usage.
build-secret-github-app-token-env Environment variable name(s) to pass GitHub token generated by GitHub App. false string GITHUB_APP_TOKEN
Can be a multiline string list.
This is useful to pass a generated token to the build, as it is not possible to share generated secrets between jobs.
Needs input build-secret-github-app-id and secret build-secret-github-app-key.
build-secret-github-app-id GitHub App ID to generate GitHub token to be passed as build secret env. false string -
See https://github.com/actions/create-github-app-token.
build-secret-github-app-owner The owner of the GitHub App installation. false string ${{ github.repository_owner }}
See https://github.com/actions/create-github-app-token.
cache-type Cache type. false string gha
See https://docs.docker.com/build/cache/backends.
buildkitd-config-inline Inline BuildKit daemon configuration. false string -
See https://github.com/docker/setup-buildx-action#inputs.
Example for insecure registry: 
[registry."my-registry.local:5000"]
 http = true
 insecure = true
sign Sign built images. false boolean true
See sign-images.

Secrets

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 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.
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.

Multiple registries

The default single-registry format still works:

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:

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
name Image name. Must be unique. It is used as image in Docker build-image action true
repository Repository name. See Docker build-image action false
context Build context. See Docker build-image action . false
Dockerfile Location of Dockerfile. See Docker build-image action Dockerfile false
target Sets the target stage to build. See Docker build-image action true
build-args List of build-time variables. See Docker build-image action false
secret-envs List of secret environment variables to expose to the build. See Docker build-image action false
platforms List of platforms to build for. It is used as platform in Docker build-image action. Can be a string (Example: linux/amd64) or an object (Example: {"name": "darwin/amd64","runs-on": "macos-latest"}) true

Platforms entry parameters

Parameter Description Default Required
name Platform name. Example: linux/amd64 true
runs-on JSON array of runner(s) to use. See https://docs.github.com/en/actions/using-jobs/choosing-the-runner-for-a-job false
Default runs-on strategy

If a platform entry omits the runs-on field, the following default strategy applies:

  • When the main docker-build-images job uses a standard hosted runner, that runner is automatically matched to each platform.
  • If the main docker-build-images job uses a custom or self-hosted runner, all platforms use the same runner.

Outputs

Output Description
built-images Built images data.
Example: 
{
 "application": {
 "name": "application",
 "registry": "ghcr.io",
 "repository": "my-org/my-repo/application",
 "tags": ["pr-63-5222075","pr-63"],
 "images": [
 "ghcr.io/my-org/my-repo/application:pr-63-5222075@sha256:d31aa93410434ac9dcfc9179cac2cb1fd4d7c27f11527addc40299c7c675f49d",
 "ghcr.io/my-org/my-repo/application:pr-63@sha256:d31aa93410434ac9dcfc9179cac2cb1fd4d7c27f11527addc40299c7c675f49d"
 ],
 "digest": "sha256:d31aa93410434ac9dcfc9179cac2cb1fd4d7c27f11527addc40299c7c675f49d",
 "annotations": {
 "org.opencontainers.image.created": "2021-09-30T14:00:00Z",
 "org.opencontainers.image.description": "Application image"
 },
 "platforms": ["linux/amd64", "linux/arm64"]
 }
}

Contributing

Contributions are welcome! Please see the contributing guidelines for more details.

License

This project is licensed under the MIT License.

SPDX-License-Identifier: MIT

Copyright © 2026 hoverkraft-tech

For more details, see the license.

This documentation was automatically generated by CI Dokumentor.