Skip to content

README.md

Latest commit

 

History

History
277 lines (214 loc) · 22.1 KB

README.md

File metadata and controls

277 lines (214 loc) · 22.1 KB

Icon GitHub Action: Docker - Build image

Docker - Build image

Marketplace Release License Stars PRs Welcome

Overview

Action to build and push a "raw" image with Docker for a specific platform. This action uses the Docker Buildx plugin to build the image. It supports caching. It returns the image digest URI, tags, and annotations, but does not handle it itself.

Permissions

If default GitHub token is used, the following permissions are required:

permissions:
  contents: read
  packages: write

Usage

- uses: hoverkraft-tech/ci-github-container/actions/docker/build-image@e4bf7a12228a2a4b5993d2d36b99b4dd0ec80bf5 # 0.32.1
  with:
    # 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.
    #
    # This input is required.
    # 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.
    #
    # This input is required.
    # Default: `${{ github.repository_owner }}`
    oci-registry-username: ${{ github.repository_owner }}

    # Password or personal access token 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 }}"}`
    # Can be passed in using `secrets.GITHUB_TOKEN`.
    # See https://github.com/docker/login-action#usage.
    #
    # This input is required.
    # Default: `${{ github.token }}`
    oci-registry-password: ${{ github.token }}

    # Repository name.
    # Example: `my-org/my-repo`.
    # See [Docker get-image-metadata action](../get-image-metadata/README.md).
    #
    # Default: `${{ github.repository }}`
    repository: ${{ github.repository }}

    # Additional image name.
    # Example: `application`.
    # See [Docker get-image-metadata action](../get-image-metadata/README.md).
    image: ""

    # Force image tag to publish
    tag: ""

    # Platform to build for. Example: `linux/amd64`.
    # See https://github.com/docker/build-push-action#inputs.
    #
    # This input is required.
    platform: ""

    # Build's context is the set of files located in the specified PATH or URL.
    # See https://github.com/docker/build-push-action#inputs.
    #
    # Default: `.`
    context: .

    # Location of Dockerfile (defaults to Dockerfile).
    # See https://github.com/docker/build-push-action#inputs.
    #
    # Default: `Dockerfile`
    dockerfile: Dockerfile

    # List of build-time variables.
    # See https://github.com/docker/build-push-action#inputs.
    build-args: ""

    # Sets the target stage to build.
    # See https://github.com/docker/build-push-action#inputs.
    target: ""

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

    # List of secret environment variables to expose to the build (e.g., `key=envname, MY_SECRET=MY_ENV_VAR`).
    # See https://docs.docker.com/build/ci/github-actions/secrets/.
    secret-envs: ""

    # 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: ""

    # Whether this build participates in a multi-platform image publication.
    # When true, the image is pushed by digest only so manifests can be assembled later.
    # When false, the image is pushed with its tags directly.
    multi-platform: ""

Inputs

Input Description Required Default
oci-registry OCI registry configuration used to pull, push and cache images. true 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. true ${{ 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.
oci-registry-password Password or personal access token configuration used to log against OCI registries. true ${{ github.token }}
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 }}"}
Can be passed in using secrets.GITHUB_TOKEN.
See https://github.com/docker/login-action#usage.
repository Repository name. false ${{ github.repository }}
Example: my-org/my-repo.
See Docker get-image-metadata action.
image Additional image name. false -
Example: application.
See Docker get-image-metadata action.
tag Force image tag to publish false -
platform Platform to build for. Example: linux/amd64. true -
See https://github.com/docker/build-push-action#inputs.
context Build's context is the set of files located in the specified PATH or URL. false .
See https://github.com/docker/build-push-action#inputs.
dockerfile Location of Dockerfile (defaults to Dockerfile). false Dockerfile
See https://github.com/docker/build-push-action#inputs.
build-args List of build-time variables. false -
See https://github.com/docker/build-push-action#inputs.
target Sets the target stage to build. false -
See https://github.com/docker/build-push-action#inputs.
secrets List of secrets to expose to the build. false -
See https://docs.docker.com/build/ci/github-actions/secrets/.
secret-envs List of secret environment variables to expose to the build (e.g., key=envname, MY_SECRET=MY_ENV_VAR). false -
See https://docs.docker.com/build/ci/github-actions/secrets/.
cache-type Cache type. false gha
See https://docs.docker.com/build/cache/backends.
buildkitd-config-inline Inline BuildKit daemon configuration. false -
See https://github.com/docker/setup-buildx-action#inputs.
Example for insecure registry: 
[registry."my-registry.local:5000"]
 http = true
 insecure = true
multi-platform Whether this build participates in a multi-platform image publication. false false
When true, the image is pushed by digest only so manifests can be assembled later.
When false, the image is pushed with its tags directly.

Outputs

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

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

For more details, see the license.

This documentation was automatically generated by CI Dokumentor.