reusable.build-container-image.yml

---
# Copyright 2024 Specter Ops, Inc.
#
# Licensed under the Apache License, Version 2.0
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
# SPDX-License-Identifier: Apache-2.0

name: Container Image Builder Pipeline

on:
  workflow_call:
    inputs:
      build_context:
        type: string
        description: |-
          Specifies the build context directory for Docker.
          Choose your build context carefully to:
          - Control which files are available during build
          - Optimize build performance by limiting included files
          - Ensure security by excluding sensitive files
          - Support multi-stage builds with specific contexts
      container_image_repository_name:
        type: string
        required: true
        description: |-
          The name of the repository where the container image will be stored in the container registry.
          This repository name uniquely identifies the image within the registry.

          Example: 'docker.io/specterops/bloodhound'.
      dockerfile:
        type: string
        description: |-
          The name of the Dockerfile used for building the container image.
          If not specified, it defaults to 'Dockerfile' in the repository root.

          Example: 'Dockerfile.prod' for a production-specific Dockerfile.
      build_target:
        type: string
        description: |-
          The build stage target for multi-stage Docker builds, if applicable.
          Specify this if your Dockerfile has multiple stages, and you want to
          build a specific one.

          Example: 'production' for a multi-stage Dockerfile with a 'production'
          stage.
      build_args:
        type: string
        description: |-
          Build-time variables that customize the container build process.
          Use build args to:
          - Inject version information at build time
          - Configure build-specific settings without modifying Dockerfile
          - Support different configurations for dev/staging/prod
          - Pass secrets safely during build (using --secret)

          Predefined values may already be present, and any inputs provided here will be appended.

          Example: 'VERSION=${GITHUB_SHA}' to embed git commit information
      build_contexts:
        type: string
        description: |-
          Additional named build contexts for multi-stage builds.
          Use multiple build contexts when you need to:
          - Separate build dependencies from runtime dependencies
          - Include files from different locations without copying
          - Optimize layer caching for different build stages
          - Support complex multi-stage build patterns

          In Dockerfile, access these contexts using FROM name or --from=name.
          Note: These contexts override same-named stages in the Dockerfile.

          Example: 'deps=/path/to/dependencies,assets=/path/to/static-files'
      build_outputs:
        type: string
        required: true
        description: |-
          Specifies the output configuration for the Docker BuildKit build process.
          Define the type and location of build outputs, such as:
          - Container images to be pushed to registries
          - Local tar archives for artifact storage
          - Cache exports for future builds
          - Custom output types for specialized needs

          Format should follow BuildKit syntax, e.g.:
          - 'type=image,name=registry/image:tag,push=false'
          - 'type=docker,dest=/path/to/image.tar'
          - 'type=registry,ref=registry/image:tag'

          Multiple outputs can be specified using comma separation.
      image_provenance:
        type: string
        description: |-
          Controls inclusion of SLSA provenance in image metadata.
          Enable provenance when you need to:
          - Meet supply chain security requirements
          - Provide audit trails for compliance
          - Verify image build authenticity
          - Support automated security policy enforcement

          Provenance data includes build source, tooling, and environment details.
      image_sbom:
        type: string
        default: "false"
        description: |-
          Controls generation of Software Bill of Materials (SBOM) for the image.
          Enable SBOM generation to:
          - Track and audit all software dependencies
          - Identify and respond to security vulnerabilities
          - Meet compliance requirements for software transparency
          - Support automated vulnerability scanning
          - Enable dependency analysis and lifecycle management

      image_flavor:
        type: string
        description: |-
          See: https://github.com/docker/metadata-action#flavor-input

      image_tags:
        type: string
        description: |-
          See: https://github.com/docker/metadata-action#tags-input

      image_cache_from:
        type: string
        description: |-
          The source image repository from which to cache layers during the build.
          This can help improve build speed by reusing layers from a previously built image.

          Example: 'docker.io/my-app:cache' to cache from a specific image.
      image_cache_to:
        type: string
        description: |-
          The destination image cache settings to optimize the caching strategy during the build.
          This input specifies where to store cached layers and how they are scoped.
          Values provided here will be appended to any default cache settings.

          Predefined values may already be present, and any inputs provided here will be appended.

          Example: "type=gha,mode=max,scope=\$\{\{ github.workflow \}\}"
      build_output_tar_dir:
        type: string
        description: |-
          The directory path where the tar file of the built image will be saved,
          to be used as an artifact upload location with the `actions/upload-artifact@v4` GitHub Action.
          This tar archive can then be retrieved from the workflow artifacts for further use or distribution.
        default: "/tmp"
      push_image:
        type: boolean
        default: false
        description: |-
          Whether to push the built container image to the registry after building.
          Set this to 'true' if you want to automatically push the image.

          Example: 'true' to push the image to the registry, 'false' to skip pushing.
    secrets:
      dockerhub_account:
        required: true
      dockerhub_token:
        required: true
      ghcr_account:
        required: true
      ghcr_token:
        required: true
      gh_access_token:
        required: true
    outputs:
      image_reference:
        value: ${{ jobs.build-container-image.outputs.image_reference }}
      image_name:
        value: ${{ jobs.build-container-image.outputs.image_name }}

jobs:
  build-container-image:
    name: Build and Package ${{ inputs.image_repository }} Container
    runs-on: ubuntu-latest
    outputs:
      image_reference: ${{ steps.container-image-metadata.outputs.image_reference }}
      image_name: ${{ steps.container-image-metadata.outputs.image_name }}
    steps:
      - name: Checkout Source Code Repository
        uses: actions/checkout@v4
        with:
          submodules: recursive

      # TODO: don't pull actions but instead reference them from the source repo
      # May need to adjust repo actions permissions to allow access from other org repos
      # https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#allowing-access-to-components-in-a-private-repository
      - if: ${{ github.repository != 'SpecterOps/BloodHound' && github.event.repository.fork == false }}
        name: Checkout Reusable Workflows and Composite Actions
        uses: actions/checkout@v4
        with:
          clean: false
          repository: SpecterOps/BloodHound
          ref: main
          token: ${{ secrets.gh_access_token }}
          sparse-checkout-cone-mode: false
          sparse-checkout: .github/actions

      - id: container-image-metadata
        uses: ./.github/actions/container-image-metadata
        with:
          container_image_repository_name: ${{ inputs.container_image_repository_name }}
          image_flavor: ${{ inputs.image_flavor }}
          image_tags: ${{ inputs.image_tags }}

      - id: build-container-image
        uses: ./.github/actions/build-container-image
        # TODO: verify if this breaks anything
        # env:
        #   DOCKER_CONTENT_TRUST: 1
        with:
          dockerhub_account: ${{ secrets.dockerhub_account }}
          dockerhub_token: ${{ secrets.dockerhub_token }}
          ghcr_account: ${{ secrets.ghcr_account }}
          ghcr_token: ${{ secrets.ghcr_token }}
          build_args: |
            BUILDTIME=${{ fromJSON(steps.container-image-metadata.outputs.json).labels['org.opencontainers.image.created'] }}
            VERSION=${{ steps.container-image-metadata.outputs.version }}
            REVISION=${{ steps.container-image-metadata.outputs.revision }}
            ${{ inputs.build_args }}
          build_context: ${{ inputs.build_context }}
          build_contexts: ${{ inputs.build_contexts }}
          build_target: ${{ inputs.build_target }}
          build_outputs: ${{ inputs.build_outputs }}
          cache_from: ${{ inputs.image_cache_from }}
          cache_to: ${{ inputs.image_cache_to }}
          dockerfile: ${{ inputs.dockerfile }}
          image_labels: |
            org.opencontainers.image.authors=https://github.com/orgs/SpecterOps/teams/bloodhound-engineering
            org.opencontainers.image.licenses=Apache License, Version 2.0
            org.opencontainers.image.vendor=SpecterOps
          image_provenance: ${{ inputs.image_provenance }}
          image_sbom: ${{ inputs.image_sbom }}
          image_tags: ${{ steps.container-image-metadata.outputs.tags }}