build-container-images.yml

---
name: "Build Container Images"
on:
  # GHA does not support "shared_inputs" or some other form of workflow_call and workflow_dispatch
  # input consolidation; instead, we must duplicate the input definitions for each event
  # FUTURE: Consolidate the input definitions whenever possible
  workflow_call:
    inputs:
      branch:
        description: "The branch on which the build is based."
        type: string
        required: true
      versionTag:
        description: "The string to be used for the container image tag."
        type: string
        required: true
      awsRegion:
        description: "Override the AWS Region destination for uploaded artifacts. Default to `us-east-1`."
        default: us-east-1
        type: string
        required: true
      imagesCsv:
        description: "Comma-separated list of image names to build. Defaults to all images ('*')"
        default: "*"
        type: string
        required: true
      tagLatest:
        description: Tags all images with the "latest" tag before upload; assumes immutable ECR
        type: boolean
        default: false
      skipBasePull:
        description: >-
          If true, skips pulling base images. Use when building only base images to significantly
          speed up build time
        type: boolean
        default: false
      cleanupImageArtifacts:
        description: >-
          If true, the built Image GitHub Artifacts will be immediately deleted once pushed to ECR.
          Defaults to true
        type: boolean
        default: true
      baseImagesVersion:
        description: >-
          Version string tag for the Base Images that will be used to build application images.
          If omitted, the latest GitHub release version will be used.
        type: string
        required: false
  workflow_dispatch:
    inputs:
      branch:
        description: >-
          branch: Override the branch on which the build is based.
          Default to selected reference in the `Use workflow from` drop-down when empty.
        required: false
      versionTag:
        description: >-
          versionTag: the string to be used for the container image tag.
        required: true
        default: X.Y.Z
      awsRegion:
        description: >-
          awsRegion: Override the AWS Region destination for uploaded artifacts.
          Default to `us-east-1`.
        default: us-east-1
        type: choice
        options:
          - us-east-1
          - us-west-2
        required: true
      imagesCsv:
        description: "Comma-separated list of image names to build. Defaults to all images ('*')"
        default: "*"
        type: string
        required: true
      tagLatest:
        description: Tags all images with the "latest" tag before upload; assumes immutable ECR
        type: boolean
        default: false
      skipBasePull:
        description: >-
          If true, skips pulling base images. Use when building only base images to significantly
          speed up build time
        type: boolean
        default: false
      cleanupImageArtifacts:
        description: >-
          If true, the built Image GitHub Artifacts will be immediately deleted once pushed to ECR.
          Defaults to true
        type: boolean
        default: true
      baseImagesVersion:
        description: >-
          Version string tag for the Base Images that will be used to build application images.
          If omitted, the latest GitHub release version will be used.
        type: string
        required: false

permissions:
  id-token: write # This is required for requesting the AWS IAM OIDC JWT
  contents: read # This is required for actions/checkout

env:
  AWS_REGION: ${{ inputs.awsRegion }}
  NON_PROD_ACCOUNT_ID: ${{ secrets.NON_PROD_ACCOUNT_ID }}
  PROD_ACCOUNT_ID: ${{ secrets.PROD_ACCOUNT_ID }}
  BASE_IMAGES: |
    [
      "bfd-platform-base-java",
      "bfd-platform-base-python"
    ]
  ACCOUNT_ROLE_MAP: |
    {
      "prod": "${{ secrets.PROD_ACCOUNT_GHA_ROLE_ARN }}",
      "non-prod": "${{ secrets.NON_PROD_ACCOUNT_GHA_ROLE_ARN }}"
    }

defaults:
  run:
    shell: bash

jobs:
  compute-matrix-and-version:
    runs-on: ubuntu-24.04
    outputs:
      matrix: ${{ steps.set-matrix.outputs.matrix }}
      base-images-version: ${{ inputs.baseImagesVersion || steps.determine-latest-release.outputs.release }}
    steps:
      - name: Validate Inputs
        run: |
          echo "Validating inputs to ensure they conform to expected formats..."
          echo "${{ inputs.versionTag }}" | grep -P '^\d+\.\d+\.\d+$|^\d+\.\d+\.\d+-[a-zA-Z0-9-]+|v3\.\d{4}.\d{2}.\d{2}.\d+.*$'

      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0
          ref: ${{ inputs.branch || github.ref_name }}

      - name: Determine latest release version
        if: inputs.baseImagesVersion == ''
        id: determine-latest-release
        uses: pozetroninc/github-action-get-latest-release@2a61c339ea7ef0a336d1daa35ef0cb1418e7676c # v0.8.0
        with:
          repository: ${{ github.repository }}
          token: ${{ secrets.GITHUB_TOKEN }}

      # Generates a JSON string array of JMESPath contains expression "fragments".
      # Given an input like:
      #    image1, image2
      # The following JSON string will be the output:
      #    ["contains('image1', name)", "contains('image2', name)"]
      - name: Mutate images list for JMESPath
        if: inputs.imagesCsv != '*'
        id: mutate-images-csv
        env:
          IMAGES_CSV: ${{ inputs.imagesCsv }}
        run: |
          images_jmespath_fragments="$(jq -cR $'gsub("\\\\s*"; "") | split(",") | map("contains(\'"+.+"\', name)")' <<< "$IMAGES_CSV")"
          echo "images_jmespath_fragments=$images_jmespath_fragments" >> $GITHUB_OUTPUT

      # Consumes the output of the previous step and generates a full JMESPath expression that will
      # be used to filter the list of images.
      # Given an input like:
      #    ["contains('image1', name)", "contains('image2', name)"]
      # Generates a JMESPath expression like:
      #    [?contains('image1', name) || contains('image2', name)]
      - name: Generate JMESPath
        if: inputs.imagesCsv != '*'
        id: gen-jmespath
        run: |
          jmes_path="[?${{ join(fromJson(steps.mutate-images-csv.outputs.images_jmespath_fragments), ' || ') }}]"
          echo "jmes_path=$jmes_path" >> $GITHUB_OUTPUT

      # Uses the above JMESPath expression to filter the list of buildable images based upon their
      # names.
      - name: Setup CI jobs matrix
        id: set-matrix
        uses: JoshuaTheMiller/conditional-build-matrix@81b51eb8d89e07b86404934b5fecde1cea1163a5 # main
        with:
          filter: "${{ steps.gen-jmespath.outputs.jmes_path || '[]' }}"
          addInclude: "false"
          inputFile: ".github/workflows/build_container_images_matrix.json"

  pull-base-images:
    if: needs.compute-matrix-and-version.outputs.matrix != '[]'
    needs: compute-matrix-and-version
    # This step is a no-op if "skipBasePull" is true, so we don't want to launch a codebuild runner
    # if we don't need to
    runs-on: ${{ !inputs.skipBasePull && format('codebuild-bfd-non-prod-platform-docker-{0}-{1}', github.run_id, github.run_attempt)  || 'ubuntu-24.04' }}
    steps:
      - name: Configure AWS credentials
        if: ${{ !inputs.skipBasePull }}
        uses: aws-actions/configure-aws-credentials@e6de054238d6b7531b4efff3b6587d9aade6a06c # v6
        with:
          role-to-assume: ${{ secrets.NON_PROD_ACCOUNT_GHA_ROLE_ARN }}
          role-session-name: build-container-images-${{ github.run_id }}-${{ github.run_attempt }}
          aws-region: ${{ env.AWS_REGION }}

      - name: Login to ECR
        if: ${{ !inputs.skipBasePull }}
        id: ecr-login
        uses: aws-actions/amazon-ecr-login@d539f0932e70871a027e9d5a9d8fc38589180a64 # v2

      - name: Pull base images
        if: ${{ !inputs.skipBasePull }}
        env:
          REGISTRY: ${{ steps.ecr-login.outputs.registry }}
          BASE_IMAGES_VERSION: ${{ needs.compute-matrix-and-version.outputs.base-images-version }}
        run: |
          echo "::add-mask::$REGISTRY"

          readarray -t images < <(echo "$BASE_IMAGES" | jq -r -c '.[]')
          for image in "${images[@]}"
          do
            docker pull "${REGISTRY}/${image}:${BASE_IMAGES_VERSION}"

            docker tag "${REGISTRY}/${image}:${BASE_IMAGES_VERSION}" "${image}:${BASE_IMAGES_VERSION}"
            docker rmi "${REGISTRY}/${image}:${BASE_IMAGES_VERSION}"

            docker save "${image}:${BASE_IMAGES_VERSION}" > "${{ runner.temp }}/${image}_${BASE_IMAGES_VERSION}.tar"
          done

      - name: Upload base image artifacts
        if: ${{ !inputs.skipBasePull }}
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        with:
          name: base-images
          path: ${{ runner.temp }}/*.tar
          retention-days: 1

  build-images:
    if: needs.compute-matrix-and-version.outputs.matrix != '[]'
    needs: [compute-matrix-and-version, pull-base-images]
    services:
      registry:
        image: registry:3
        ports:
          - 5000:5000
    strategy:
      matrix:
        image: ${{ fromJson(needs.compute-matrix-and-version.outputs.matrix) }}
    runs-on: ${{ matrix.image.platform == 'linux/arm64' && 'ubuntu-24.04-arm' || 'ubuntu-24.04' }}
    env:
      BASE_IMAGES_VERSION: ${{ needs.compute-matrix-and-version.outputs.base-images-version }}
    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0
          ref: ${{ inputs.branch || github.ref_name }}

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4
        with:
          driver-opts: network=host

      - name: Download base image artifacts
        if: ${{ !inputs.skipBasePull }}
        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
        with:
          name: base-images
          path: ${{ runner.temp }}

      - name: Load base images
        if: ${{ !inputs.skipBasePull }}
        run: |
          readarray -t images < <(echo "$BASE_IMAGES" | jq -r -c '.[]')
          for image in "${images[@]}"
          do
            docker load --input "${image}_${BASE_IMAGES_VERSION}.tar"

            docker tag "${image}:${BASE_IMAGES_VERSION}" "localhost:5000/${image}:${BASE_IMAGES_VERSION}"
            docker push "localhost:5000/${image}:${BASE_IMAGES_VERSION}"
          done
        working-directory: ${{ runner.temp }}

      - name: Generate build-contexts
        if: ${{ !inputs.skipBasePull }}
        id: gen-build-contexts
        env:
          NAMED_CONTEXTS: ${{ toJSON(matrix.image.namedContexts) || '{}' }}
        run: |
          build_contexts=()

          readarray -t images < <(echo "$BASE_IMAGES" | jq -r -c '.[]')
          for image in "${images[@]}"
          do
            build_contexts+=("${image}:${BASE_IMAGES_VERSION}=docker-image://localhost:5000/${image}:${BASE_IMAGES_VERSION}")
            build_contexts+=("${image}:latest=docker-image://localhost:5000/${image}:${BASE_IMAGES_VERSION}")
          done

          readarray -t named_contexts < <(echo "$NAMED_CONTEXTS" | jq -rc '. // {} | to_entries[]')
          for named_context in "${named_contexts[@]}"
          do
            context_name="$(jq -rc '.key' <<<"$named_context")"
            context_path="$(jq -rc '.value' <<<"$named_context")"

            build_contexts+=("${context_name}=${context_path}")
          done

          build_contexts_json="$(jq -c -n '$ARGS.positional' --args "${build_contexts[@]}")"

          echo "build-contexts=$build_contexts_json" >> "$GITHUB_OUTPUT"

      # TODO: This becomes just "build" and push is within codebuild. "build" emits a .tar.gz artifact
      - name: Build image
        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
        with:
          file: ${{ matrix.image.dockerfile }}
          context: ${{ matrix.image.contextDir }}
          push: false
          # Not obvious, but the only way to emit a newline is by, literally, using a newline.
          # See https://github.com/orgs/community/discussions/26263#discussioncomment-3251069
          build-contexts: |-
            ${{ join(fromJson(steps.gen-build-contexts.outputs.build-contexts || '[]'), '
            ') }}
          build-args: |
            base_version=${{ needs.compute-matrix-and-version.outputs.base-images-version }}
          tags: ${{ matrix.image.name }}:${{ inputs.versionTag }}
          # AWS Lambda does not support multi-platform images, something that is enabled by default
          # by this Action via the "provenance" flag. Until AWS Lambda supports this feature
          # properly, we must explicitly disable provenance and specify the platform directly.
          # See https://github.com/docker/buildx/issues/1533
          provenance: false
          platforms: ${{ matrix.image.platform }}
          cache-from: type=gha
          cache-to: type=gha,mode=max
          outputs: type=docker,dest=${{ runner.temp }}/${{ matrix.image.name }}.tar
        env:
          DOCKER_BUILDKIT: 1

      - name: Upload image as artifact
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        with:
          name: build-images.${{ matrix.image.name }}
          path: ${{ runner.temp }}/${{ matrix.image.name }}.tar
          retention-days: 1

  push-images:
    if: needs.compute-matrix-and-version.outputs.matrix != '[]'
    needs: [compute-matrix-and-version, pull-base-images, build-images]
    strategy:
      matrix:
        account: ["prod", "non-prod"]
    runs-on: codebuild-bfd-${{ matrix.account }}-platform-docker-${{ github.run_id }}-${{ github.run_attempt }}
    steps:
      - name: Get role ARN
        id: get-role-arn
        run: |
          role_arn="$(jq -r --arg account_type "${{ matrix.account }}" '.[$account_type]' <<<"$ACCOUNT_ROLE_MAP")"

          echo "::add-mask::$role_arn"
          echo "role-arn=$role_arn" >> "$GITHUB_OUTPUT"

      - name: Download all built image artifacts
        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
        with:
          pattern: build-images.*
          path: ${{ runner.temp }}
          merge-multiple: true

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@e6de054238d6b7531b4efff3b6587d9aade6a06c # v6
        with:
          role-to-assume: ${{ steps.get-role-arn.outputs.role-arn }}
          role-session-name: build-container-images-${{ github.run_id }}-${{ github.run_attempt }}
          aws-region: ${{ env.AWS_REGION }}

      - name: Login to ECR
        id: ecr-login
        uses: aws-actions/amazon-ecr-login@d539f0932e70871a027e9d5a9d8fc38589180a64 # v2

      - name: Push built image(s)
        env:
          TAG: ${{ inputs.versionTag }}
          REGISTRY: ${{ steps.ecr-login.outputs.registry }}
          PUSH_LATEST: ${{ inputs.tagLatest }}
        run: |
          echo "::add-mask::$REGISTRY"

          for image_filename in ./*.tar
          do
            docker load --input "$image_filename"

            image="$(basename "$image_filename" .tar)"
            docker tag "$image:$TAG" "$REGISTRY/$image:$TAG"
            if [[ $PUSH_LATEST == "true" ]]; then
              # Remove the "latest" tag from the existing latest image
              aws ecr batch-delete-image --repository-name "$image" --image-ids imageTag=latest &>/dev/null || true
              # Tag the new release image as "latest"
              docker tag "$image:$TAG" "$REGISTRY/$image:latest"
              # Push "latest" tag
              docker push "$REGISTRY/$image:latest"
            fi

            docker push "$REGISTRY/$image:$TAG"
          done
        working-directory: ${{ runner.temp }}

  cleanup-artifacts:
    if: ${{ !cancelled() && inputs.cleanupImageArtifacts }}
    needs: push-images
    runs-on: ubuntu-24.04
    steps:
      - name: Delete all image artifacts
        uses: GeekyEggo/delete-artifact@176a747ab7e287e3ff4787bf8a148716375ca118 # v6
        with:
          name: '*'
          failOnError: false