docker-build-images.yml

# Workflow to build multiple Docker images.
# Build images using [Docker build image](https://github.com/hoverkraft-tech/ci-github-container/blob/main/actions/docker/build-image/README.md).
# This includes [multi-platform](https://docs.docker.com/build/building/multi-platform/) build.
---
name: Docker build images

on: # yamllint disable-line rule:truthy
  workflow_call:
    inputs:
      runs-on:
        description: |
          Runner to use. JSON array of runners.
          See https://docs.github.com/en/actions/using-jobs/choosing-the-runner-for-a-job.
        type: string
        default: '["ubuntu-latest"]'
        required: false
      oci-registry:
        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 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 }}
        required: false
      images:
        description: |
          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"
                }
              ]
            }
          ]
          ```
        type: string
        required: true
      lfs:
        description: |
          Enable Git LFS.
          See https://github.com/actions/checkout?tab=readme-ov-file#usage.
        type: boolean
        default: true
        required: false
      build-secret-github-app-token-env:
        description: |
          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-client-id` and secret `build-secret-github-app-key`.
        type: string
        required: false
        default: "GITHUB_APP_TOKEN"
      build-secret-github-app-client-id:
        description: |
          GitHub App client ID to generate GitHub token to be passed as build secret env.
          See https://github.com/actions/create-github-app-token.
        required: false
        type: string
      build-secret-github-app-owner:
        description: |
          The owner of the GitHub App installation.
          See https://github.com/actions/create-github-app-token.
        required: false
        type: string
        default: ${{ github.repository_owner }}
      cache-type:
        description: |
          Cache type.
          See https://docs.docker.com/build/cache/backends.
        default: "gha"
        type: string
        required: false
      buildkitd-config-inline:
        description: |
          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
          ```
        type: string
        required: false
      sign:
        description: |
          Sign built images.
          See [sign-images](../../actions/docker/sign-images/README.md).
        type: boolean
        default: true
        required: false
    secrets:
      oci-registry-password:
        description: |
          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:
        description: |
          List of secrets to expose to the build.
          See https://docs.docker.com/build/ci/github-actions/secrets/.
        required: false
      build-secret-github-app-key:
        description: |
          GitHub App private key to generate GitHub token to be passed as build secret env.
          See https://github.com/actions/create-github-app-token.
        required: false
    outputs:
      built-images:
        description: |
          Built images data.
          Example:
          ```json
          {
            "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"]
            }
          }
          ```
        value: ${{ jobs.publish-manifests.outputs.built-images }}

permissions: {}

jobs:
  prepare-variables:
    outputs:
      artifact-name: ${{ steps.define-artifact-name.outputs.artifact-name }}
      images: ${{ steps.define-images-by-platform.outputs.images }}
    runs-on: ${{ fromJson(inputs.runs-on) }}
    steps:
      - id: validate-inputs
        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
        env:
          OCI_REGISTRY_PASSWORD: ${{ secrets.oci-registry-password }} # zizmor: ignore[secrets-outside-env]
          RUNS_ON_INPUT: ${{ inputs.runs-on }}
          IMAGES_INPUT: ${{ inputs.images }}
        with:
          script: |
            const ociRegistryPassword = process.env.OCI_REGISTRY_PASSWORD;
            if (!ociRegistryPassword) {
              throw new Error(`"oci-registry-password" secret is missing`);
            }

            const runsOnInput = process.env.RUNS_ON_INPUT;
            let runsOn = null;
            try {
              runsOn = JSON.parse(runsOnInput);
            } catch (error) {
              throw new Error(`"runs-on" input is not a valid JSON: ${error}`);
            }

            // jscpd:ignore-start
            const imagesInput = process.env.IMAGES_INPUT;

            // Check if is valid Json
            let images = null;
            try {
              images = JSON.parse(imagesInput);
            } catch (error) {
              throw new Error(`"images" input is not a valid JSON: ${error}`);
            }

            // Check if is an array
            if (!Array.isArray(images)) {
              throw new Error(`"images" input is not an array`);
            }
            // jscpd:ignore-end

            // Check each item
            for (const key in images) {
              const image = images[key];
              if (typeof image !== 'object') {
                throw new Error(`"images[${key}]" input is not an object`);
              }

              // Check mandatory properties
              for (const property of ['name', 'platforms']) {
                if (!image.hasOwnProperty(property)) {
                  throw new Error(`"images[${key}].${property}" input is missing`);
                }
              }

              if (typeof image['name'] !== 'string') {
                throw new Error(`"images[${key}].name" input is not a string`);
              }

              if (!Array.isArray(image['platforms'])) {
                throw new Error(`"images[${key}].platforms" input is not an array`);
              }

              // Format build-args object to string
              if (image['build-args']) {
                const buildArgs = Object.keys(image['build-args'])
                  .map(key => `${key}=${image['build-args'][key]}`)
                  .join('\n');
                image['build-args'] = buildArgs;
              }

              // Format secret-envs object to string
              if (image['secret-envs']) {
                const secretEnvs = Object.keys(image['secret-envs'])
                  .map(key => `${key}=${image['secret-envs'][key]}`)
                  .join('\n');
                image['secret-envs'] = secretEnvs;
              }

              // Set default repository
              if (!image['repository']) {
                image['repository'] = `${context.repo.owner}/${context.repo.repo}`;
              }
            }

            core.setOutput('images', JSON.stringify(images));

      - id: define-images-by-platform
        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
        env:
          IMAGES: ${{ steps.validate-inputs.outputs.images }}
          RUNS_ON_INPUT: ${{ inputs.runs-on }}
        with:
          script: |
            const imagesInput = process.env.IMAGES;
            const images = JSON.parse(imagesInput.replace(/\n/g, '\\n'));

            const runsOnInput = process.env.RUNS_ON_INPUT;
            const isDefaultRunsOn = runsOnInput === '["ubuntu-latest"]';
            const runsOn = JSON.parse(runsOnInput);

            // See https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners
            const standardHostedRunnerByPlatform = [
              { runner: "macos-latest", platformPattern: /^darwin\// },
              { runner: "windows-latest", platformPattern: /^windows\// }
            ];

            standardHostedRunnerByPlatform.unshift(
              { runner: "ubuntu-24.04-arm", platformPattern: /^linux\/arm/ }, // FIXME: should use latest when available,
              { runner: "windows-11-arm", platformPattern: /^windows\/arm/ }
            );

            function getPlatformRunsOn(platform) {
              if (platform.hasOwnProperty('runs-on')) {
                return platform['runs-on'];
              }

              if (!isDefaultRunsOn) {
                return runsOn;
              }

              for (const { runner, platformPattern } of standardHostedRunnerByPlatform) {
                if (platformPattern.test(platform.name)) {
                  return [runner];
                }
              }

              return runsOn;
            }

            // Check each item
            const imagesByPlatform = [];
            for (const key in images) {
              const image = images[key];

              // Add image for each platform
              const platforms = image['platforms'];

              for (const platform of platforms) {
                let platformName;
                let platformRunsOn;

                // Platform can be a string or an object
                if (typeof platform === 'object') {
                  if (!platform.hasOwnProperty('name')) {
                    throw new Error(`"images[${key}].platforms[${platform}].name" input is missing`);
                  }
                  platformName = platform['name'];
                  platformRunsOn = getPlatformRunsOn(platform);
                } else if (typeof platform === 'string') {
                  platformName = platform;
                  platformRunsOn = getPlatformRunsOn({ name: platform });
                } else {
                  throw new Error(`"images[${key}].platforms[${platform}]" input is not a string or an object`);
                }

                const imageByPlatform = {
                  ...image,
                  platform: platformName,
                  "runs-on": platformRunsOn,
                  // Flag multi-platform builds so downstream steps adjust publishing behavior
                  "multi-platform": platforms.length > 1,
                };
                imagesByPlatform.push(imageByPlatform);
              }
            }

            core.debug(`Images by platform: ${JSON.stringify(imagesByPlatform, null, 2)}`);

            core.setOutput('images', JSON.stringify(imagesByPlatform));

      - id: define-artifact-name
        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
        with:
          script: |
            function uniqid(prefix = "") {
                const sec = Date.now() * 1000 + Math.random() * 1000;
                const id = sec.toString(16).replace(/\./g, "").padEnd(14, "0");
                return `${prefix}${id}`;
            };

            core.setOutput('artifact-name', uniqid("build-images-"));

  build-images:
    name: Build image ${{ matrix.image.name }} for ${{ matrix.image.platform }}
    needs: prepare-variables
    runs-on: ${{ matrix.image.runs-on }}
    strategy:
      fail-fast: false
      matrix:
        image: ${{ fromJson(needs.prepare-variables.outputs.images) }}
    permissions:
      contents: read
      pull-requests: read
      issues: read
      packages: write
    steps:
      - uses: hoverkraft-tech/ci-github-common/actions/checkout@624be17604ee0a7378488191aacb35851e7cf001 # 0.37.1
        with:
          lfs: ${{ inputs.lfs }}

      - if: inputs.lfs
        shell: bash
        run: git lfs pull

      - id: local-workflow-actions
        uses: hoverkraft-tech/ci-github-common/actions/local-workflow-actions@624be17604ee0a7378488191aacb35851e7cf001 # 0.37.1
        with:
          actions-path: actions

      - uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
        if: inputs.build-secret-github-app-client-id
        id: generate-token
        with:
          client-id: ${{ inputs.build-secret-github-app-client-id }}
          owner: ${{  inputs.build-secret-github-app-owner }}
          private-key: ${{ secrets.build-secret-github-app-key }} # zizmor: ignore[secrets-outside-env]

      - id: prepare-secret-envs
        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
        env:
          SECRET_ENVS: ${{ matrix.image.secret-envs }}
          GITHUB_APP_TOKEN: ${{ steps.generate-token.outputs.token }}
          BUILD_SECRET_GITHUB_APP_TOKEN_ENV: ${{ inputs.build-secret-github-app-token-env }}
        with:
          script: |
            const githubAppTokenEnvName = 'GITHUB_APP_TOKEN';

            let secretEnvs = process.env.SECRET_ENVS || '';
            const githubAppToken = process.env.GITHUB_APP_TOKEN || '';

            if (!githubAppToken) {
              if (secretEnvs) {
                core.setOutput('secret-envs', secretEnvs);
              }
              return;
            }

            core.exportVariable(githubAppTokenEnvName, githubAppToken);

            const buildSecretGithubAppTokenEnv = (process.env.BUILD_SECRET_GITHUB_APP_TOKEN_ENV || '').trim();
            if (!buildSecretGithubAppTokenEnv.length) {
              throw new Error(`"build-secret-github-app-token-env" input is empty`);
            }

            const mappedBuildSecretGithubAppTokenEnv = buildSecretGithubAppTokenEnv
            .split('\n')
            .map(key => key.trim())
            .filter(Boolean)
            .map(key => `${key}=${githubAppTokenEnvName}`).join('\n')

            secretEnvs = secretEnvs.trim() + '\n' + mappedBuildSecretGithubAppTokenEnv.trim();

            core.setOutput('secret-envs', secretEnvs.trim());

      - id: build
        uses: ./../self-workflow/actions/docker/build-image
        with:
          oci-registry: ${{ inputs.oci-registry }}
          oci-registry-username: ${{ inputs.oci-registry-username }}
          oci-registry-password: ${{ secrets.oci-registry-password }} # zizmor: ignore[secrets-outside-env]
          repository: ${{ matrix.image.repository }}
          image: ${{ matrix.image.name }}
          tag: ${{ matrix.image.tag }}
          context: ${{ matrix.image.context }}
          dockerfile: ${{ matrix.image.dockerfile }}
          build-args: ${{ matrix.image.build-args }}
          target: ${{ matrix.image.target }}
          platform: ${{ matrix.image.platform }}
          secret-envs: ${{ steps.prepare-secret-envs.outputs.secret-envs }}
          secrets: ${{ secrets.build-secrets }} # zizmor: ignore[secrets-outside-env]
          cache-type: ${{ inputs.cache-type }}
          buildkitd-config-inline: ${{ inputs.buildkitd-config-inline }}
          multi-platform: ${{ matrix.image.multi-platform }}

      # FIXME: Set built images infos in file to be uploaded as artifacts, because github action does not handle job outputs for matrix
      # https://github.com/orgs/community/discussions/26639
      - uses: hoverkraft-tech/ci-github-common/actions/set-matrix-output@624be17604ee0a7378488191aacb35851e7cf001 # 0.37.1
        with:
          artifact-name: ${{ needs.prepare-variables.outputs.artifact-name }}
          value: ${{ steps.build.outputs.built-image }}

  publish-manifests:
    name: Publish images manifests
    permissions:
      contents: read
      packages: write
      id-token: write # Needed for signing images
    needs: [prepare-variables, build-images]
    runs-on: ${{ fromJson(inputs.runs-on) }}
    outputs:
      built-images: ${{ steps.create-images-manifests.outputs.built-images }}
    steps:
      - id: get-matrix-outputs
        uses: hoverkraft-tech/ci-github-common/actions/get-matrix-outputs@624be17604ee0a7378488191aacb35851e7cf001 # 0.37.1
        with:
          artifact-name: ${{ needs.prepare-variables.outputs.artifact-name }}

      - id: built-images
        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
        env:
          BUILT_IMAGES_INPUT: ${{ steps.get-matrix-outputs.outputs.result }}
        with:
          script: |
            const builtImagesInput = process.env.BUILT_IMAGES_INPUT;
            let builtImages = null;
            try {
              builtImages = JSON.parse(builtImagesInput);
            } catch (error) {
              throw new Error(`"built-images" input is not a valid JSON: ${error}`);
            }

            // Group by image name
            const images = {};
            builtImages.forEach(builtImage => {
              const { name, image, platform, ...rest } = builtImage;
              if (!images[name]) {
                images[name] = {
                  name,
                  images: [image],
                  platforms: [platform],
                  ...rest,
                };
              } else {
                images[name].images = [...new Set([...images[name].images, image])];
                images[name].platforms = [...new Set([...images[name].platforms, platform])];
              }
            });

            core.setOutput('built-images', JSON.stringify(images));

      - id: local-workflow-actions
        uses: hoverkraft-tech/ci-github-common/actions/local-workflow-actions@624be17604ee0a7378488191aacb35851e7cf001 # 0.37.1
        with:
          actions-path: actions

      - id: create-images-manifests
        uses: ./../self-workflow/actions/docker/create-images-manifests
        with:
          oci-registry: ${{ inputs.oci-registry }}
          oci-registry-username: ${{ inputs.oci-registry-username }}
          oci-registry-password: ${{ secrets.oci-registry-password }} # zizmor: ignore[secrets-outside-env]
          built-images: ${{ steps.built-images.outputs.built-images }}

      - id: get-images-to-sign
        if: inputs.sign
        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
        env:
          BUILT_IMAGES_INPUT: ${{ steps.create-images-manifests.outputs.built-images }}
        with:
          script: |
            const builtImagesInput = process.env.BUILT_IMAGES_INPUT;
            let builtImages = null;
            try {
              builtImages = JSON.parse(builtImagesInput);
            } catch (error) {
              throw new Error(`"built-images" input is not a valid JSON: ${error}`);
            }

            // Get images to sign
            const imagesToSign = Object.values(builtImages).map(image => image.images).flat();
            core.setOutput('images-to-sign', JSON.stringify(imagesToSign));

      - uses: ./../self-workflow/actions/docker/sign-images
        if: steps.get-images-to-sign.outputs.images-to-sign
        with:
          images: ${{ steps.get-images-to-sign.outputs.images-to-sign }}
          github-token: ${{ secrets.GITHUB_TOKEN }}