build.yml

---
name: build

on:
  merge_group:
    types:
      - checks_requested
  pull_request:
  push:
    branches:
      - "**"
    tags:
      - "v*.*.*"
  repository_dispatch:
    # Respond to rebuild requests. See: https://github.com/cisagov/action-apb/
    types:
      - apb
  schedule:
    - cron: "0 10 * * *"  # everyday at 10am
  workflow_dispatch:
    inputs:
      image-tag:
        default: "dispatch"
        description: "Tag to apply to pushed images"
        required: true
      remote-shell:
        default: "false"
        description: "Debug with remote shell"
        required: true

# Set a default shell for any run steps. The `-Eueo pipefail` sets errtrace,
# nounset, errexit, and pipefail. The `-x` will print all commands as they are
# run. Please see the GitHub Actions documentation for more information:
# https://docs.github.com/en/actions/using-jobs/setting-default-values-for-jobs
defaults:
  run:
    shell: bash -Eueo pipefail -x {0}

env:
  BUILDX_CACHE_DIR: ~/.cache/buildx
  IMAGE_NAME: cisagov/example
  PIP_CACHE_DIR: ~/.cache/pip
  PLATFORMS: "linux/amd64,linux/arm/v6,linux/arm/v7,\
  linux/arm64,linux/ppc64le,linux/s390x"
  PRE_COMMIT_CACHE_DIR: ~/.cache/pre-commit
  RUN_TMATE: ${{ secrets.RUN_TMATE }}
  TERRAFORM_DOCS_REPO_BRANCH_NAME: improvement/support_atx_closed_markdown_headers
  TERRAFORM_DOCS_REPO_DEPTH: 1
  TERRAFORM_DOCS_REPO_URL: https://github.com/mcdonnnj/terraform-docs.git

jobs:
  diagnostics:
    name: Run diagnostics
    # This job does not need any permissions
    permissions: {}
    runs-on: ubuntu-latest
    steps:
      # Note that a duplicate of this step must be added at the top of
      # each job.
      - uses: GitHubSecurityLab/actions-permissions/monitor@v1
        with:
          # Uses the organization variable unless overridden
          config: ${{ vars.ACTIONS_PERMISSIONS_CONFIG }}
      # Note that a duplicate of this step must be added at the top of
      # each job.
      - id: harden-runner
        name: Harden the runner
        uses: step-security/harden-runner@v2
        with:
          egress-policy: audit
      - id: github-status
        name: Check GitHub status
        uses: crazy-max/ghaction-github-status@v4
      - id: dump-context
        name: Dump context
        uses: crazy-max/ghaction-dump-context@v2
  lint:
    # Checks out the source and runs pre-commit hooks.  Detects coding errors
    # and style deviations.
    name: Lint sources
    needs:
      - diagnostics
    permissions:
      # actions/checkout needs this to fetch code
      contents: read
    runs-on: ubuntu-latest
    steps:
      - uses: GitHubSecurityLab/actions-permissions/monitor@v1
        with:
          # Uses the organization variable unless overridden
          config: ${{ vars.ACTIONS_PERMISSIONS_CONFIG }}
      - id: harden-runner
        name: Harden the runner
        uses: step-security/harden-runner@v2
        with:
          egress-policy: audit
      - id: setup-env
        uses: cisagov/setup-env-github-action@develop
      - uses: actions/checkout@v4
      - id: setup-python
        uses: actions/setup-python@v5
        with:
          python-version: ${{ steps.setup-env.outputs.python-version }}
      # We need the Go version and Go cache location for the actions/cache step,
      # so the Go installation must happen before that.
      - id: setup-go
        uses: actions/setup-go@v5
        with:
          # There is no expectation for actual Go code so we disable caching as
          # it relies on the existence of a go.sum file.
          cache: false
          go-version: ${{ steps.setup-env.outputs.go-version }}
      - id: go-cache
        name: Lookup Go cache directory
        run: |
          echo "dir=$(go env GOCACHE)" >> $GITHUB_OUTPUT
      - uses: actions/cache@v4
        env:
          BASE_CACHE_KEY: "${{ github.job }}-${{ runner.os }}-\
            py${{ steps.setup-python.outputs.python-version }}-\
            go${{ steps.setup-go.outputs.go-version }}-\
            packer${{ steps.setup-env.outputs.packer-version }}-\
            tf${{ steps.setup-env.outputs.terraform-version }}-"
        with:
          key: "${{ env.BASE_CACHE_KEY }}\
            ${{ hashFiles('**/requirements-test.txt') }}-\
            ${{ hashFiles('**/requirements.txt') }}-\
            ${{ hashFiles('**/.pre-commit-config.yaml') }}"
          # Note that the .terraform directory IS NOT included in the
          # cache because if we were caching, then we would need to use
          # the `-upgrade=true` option. This option blindly pulls down the
          # latest modules and providers instead of checking to see if an
          # update is required. That behavior defeats the benefits of caching.
          # so there is no point in doing it for the .terraform directory.
          path: |
            ${{ env.PIP_CACHE_DIR }}
            ${{ env.PRE_COMMIT_CACHE_DIR }}
            ${{ steps.go-cache.outputs.dir }}
          restore-keys: |
            ${{ env.BASE_CACHE_KEY }}
      - uses: hashicorp/setup-packer@v3
        with:
          version: ${{ steps.setup-env.outputs.packer-version }}
      - uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: ${{ steps.setup-env.outputs.terraform-version }}
      - name: Install go-critic
        env:
          PACKAGE_URL: github.com/go-critic/go-critic/cmd/gocritic
          PACKAGE_VERSION: ${{ steps.setup-env.outputs.go-critic-version }}
        run: go install ${PACKAGE_URL}@${PACKAGE_VERSION}
      - name: Install goimports
        env:
          PACKAGE_URL: golang.org/x/tools/cmd/goimports
          PACKAGE_VERSION: ${{ steps.setup-env.outputs.goimports-version }}
        run: go install ${PACKAGE_URL}@${PACKAGE_VERSION}
      - name: Install gosec
        env:
          PACKAGE_URL: github.com/securego/gosec/v2/cmd/gosec
          PACKAGE_VERSION: ${{ steps.setup-env.outputs.gosec-version }}
        run: go install ${PACKAGE_URL}@${PACKAGE_VERSION}
      - name: Install staticcheck
        env:
          PACKAGE_URL: honnef.co/go/tools/cmd/staticcheck
          PACKAGE_VERSION: ${{ steps.setup-env.outputs.staticcheck-version }}
        run: go install ${PACKAGE_URL}@${PACKAGE_VERSION}
      # TODO: https://github.com/cisagov/skeleton-generic/issues/165
      # We are temporarily using @mcdonnnj's forked branch of terraform-docs
      # until his PR: https://github.com/terraform-docs/terraform-docs/pull/745
      # is approved. This temporary fix will allow for ATX header support when
      # terraform-docs is run during linting.
      - name: Clone ATX headers branch from terraform-docs fork
        run: |
          git clone \
           --branch $TERRAFORM_DOCS_REPO_BRANCH_NAME \
           --depth $TERRAFORM_DOCS_REPO_DEPTH \
           --single-branch \
           $TERRAFORM_DOCS_REPO_URL /tmp/terraform-docs
      - name: Build and install terraform-docs binary
        run: |
          go build \
          -C /tmp/terraform-docs \
          -o $(go env GOPATH)/bin/terraform-docs
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip setuptools wheel
          pip install --upgrade --requirement requirements-test.txt
      - name: Set up pre-commit hook environments
        run: pre-commit install-hooks
      - name: Run pre-commit on all files
        run: pre-commit run --all-files
      - name: Setup tmate debug session
        uses: mxschmitt/action-tmate@v3
        if: env.RUN_TMATE
  prepare:
    # Calculates and publishes outputs that are used by other jobs.
    #
    # Outputs:
    #   created:
    #     The current date-time in RFC3339 format.
    #   repometa:
    #     The json metadata describing this repository.
    #   source_version:
    #     The source version as reported by the `bump-version show` command.
    #   tags:
    #     A comma separated list of Docker tags to be applied to the images on
    #     Docker Hub.  The tags will vary depending on:
    #     - The event that triggered the build.
    #     - The branch the build is based upon.
    #     - The git tag the build is based upon.
    #
    #     When a build is based on a git tag of the form `v*.*.*` the image will
    #     be tagged on Docker Hub with multiple levels of version specificity.
    #     For example, a git tag of `v1.2.3+a` will generate Docker tags of
    #     `:1.2.3_a`, `:1.2.3`, `:1.2`, `:1`, and `:latest`.
    #
    #     Builds targeting the default branch will be tagged with `:edge`.
    #
    #     Builds from other branches will be tagged with the branch name. Solidi
    #     (`/` characters - commonly known as slashes) in branch names are
    #     replaced with hyphen-minuses (`-` characters) in the Docker tag.  For
    #     more information about the solidus see these links:
    #       * https://www.compart.com/en/unicode/U+002F
    #       * https://en.wikipedia.org/wiki/Slash_(punctuation)#Encoding
    #
    #     Builds triggered by a push event are tagged with a short hash in the
    #     form: sha-12345678
    #
    #     Builds triggered by a pull request are tagged with the pull request
    #     number in the form pr-123.
    #
    #     Builds triggered using the GitHub GUI (workflow_dispatch) are tagged
    #     with the value specified by the user.
    #
    #     Scheduled builds are tagged with `:nightly`.
    name: Prepare build variables
    needs:
      - diagnostics
    outputs:
      created: ${{ steps.prep.outputs.created }}
      repometa: ${{ steps.repo.outputs.result }}
      source_version: ${{ steps.prep.outputs.source_version }}
      tags: ${{ steps.prep.outputs.tags }}
    permissions:
      # actions/checkout needs this to fetch code
      contents: read
    runs-on: ubuntu-latest
    steps:
      - uses: GitHubSecurityLab/actions-permissions/monitor@v1
        with:
          # Uses the organization variable unless overridden
          config: ${{ vars.ACTIONS_PERMISSIONS_CONFIG }}
      - id: harden-runner
        name: Harden the runner
        uses: step-security/harden-runner@v2
        with:
          egress-policy: audit
      - uses: actions/checkout@v4
      - name: Gather repository metadata
        id: repo
        uses: actions/github-script@v7
        with:
          script: |
            const repo = await github.rest.repos.get(context.repo)
            return repo.data
      - name: Calculate output values
        id: prep
        run: |
          VERSION=noop
          SEMVER="^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(-((0|[1-9][0-9]*|[0-9]*[a-zA-Z-][0-9a-zA-Z-]*)(\.(0|[1-9][0-9]*|[0-9]*[a-zA-Z-][0-9a-zA-Z-]*))*))?(\+([0-9a-zA-Z-]+(\.[0-9a-zA-Z-]+)*))?$"
          if [ "${{ github.event_name }}" = "schedule" ]; then
            VERSION=nightly
          elif [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
            VERSION=${{ github.event.inputs.image-tag }}
          elif [[ $GITHUB_REF == refs/tags/* ]]; then
            VERSION=${GITHUB_REF#refs/tags/}
          elif [[ $GITHUB_REF == refs/heads/* ]]; then
            VERSION=$(echo ${GITHUB_REF#refs/heads/} | sed -r 's#/+#-#g')
            if [ "${{ github.event.repository.default_branch }}" = "$VERSION" ];
              then
              VERSION=edge
            fi
          elif [[ $GITHUB_REF == refs/pull/* ]]; then
            VERSION=pr-${{ github.event.number }}
          fi
          if [[ $VERSION =~ $SEMVER ]]; then
            VERSION_NO_V=${VERSION#v}
            MAJOR="${BASH_REMATCH[1]}"
            MINOR="${BASH_REMATCH[2]}"
            PATCH="${BASH_REMATCH[3]}"
            TAGS="${IMAGE_NAME}:${VERSION_NO_V//+/_},${IMAGE_NAME}:${MAJOR}.${MINOR}.${PATCH},${IMAGE_NAME}:${MAJOR}.${MINOR},${IMAGE_NAME}:${MAJOR},${IMAGE_NAME}:latest"
          else
            TAGS="${IMAGE_NAME}:${VERSION}"
          fi
          if [ "${{ github.event_name }}" = "push" ]; then
            TAGS="${TAGS},${IMAGE_NAME}:sha-${GITHUB_SHA::8}"
          fi
          for i in ${TAGS//,/ }
          do
            TAGS="${TAGS},ghcr.io/${i}"
          done
          echo "created=$(date -u +'%Y-%m-%dT%H:%M:%SZ')" >> $GITHUB_OUTPUT
          echo "source_version=$(./bump-version show)" >> $GITHUB_OUTPUT
          echo "tags=${TAGS}" >> $GITHUB_OUTPUT
          echo tags=${TAGS}
      - name: Setup tmate debug session
        uses: mxschmitt/action-tmate@v3
        if: github.event.inputs.remote-shell == 'true' || env.RUN_TMATE
  build:
    # Builds a single test image for the native platform.  This image is saved
    # as an artifact and loaded by the test job.
    name: Build test image
    needs:
      - diagnostics
      - prepare
    permissions:
      # actions/checkout needs this to fetch code
      contents: read
    runs-on: ubuntu-latest
    steps:
      - uses: GitHubSecurityLab/actions-permissions/monitor@v1
        with:
          # Uses the organization variable unless overridden
          config: ${{ vars.ACTIONS_PERMISSIONS_CONFIG }}
      - id: harden-runner
        name: Harden the runner
        uses: step-security/harden-runner@v2
        with:
          egress-policy: audit
      - name: Checkout
        uses: actions/checkout@v4
      - name: Set up QEMU
        uses: docker/setup-qemu-action@v3
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3
      - name: Cache Docker layers
        uses: actions/cache@v4
        env:
          BASE_CACHE_KEY: buildx-${{ runner.os }}-
        with:
          key: ${{ env.BASE_CACHE_KEY }}${{ github.sha }}
          path: ${{ env.BUILDX_CACHE_DIR }}
          restore-keys: |
            ${{ env.BASE_CACHE_KEY }}
      - name: Create dist directory
        run: mkdir -p dist
      - name: Build image
        id: docker_build
        uses: docker/build-push-action@v6
        with:
          build-args: |
            VERSION=${{ needs.prepare.outputs.source_version }}
          cache-from: type=local,src=${{ env.BUILDX_CACHE_DIR }}
          cache-to: type=local,dest=${{ env.BUILDX_CACHE_DIR }}
          context: .
          file: ./Dockerfile
          labels: "\
            org.opencontainers.image.created=${{
              needs.prepare.outputs.created }}

            org.opencontainers.image.description=${{
              fromJson(needs.prepare.outputs.repometa).description }}

            org.opencontainers.image.licenses=${{
              fromJson(needs.prepare.outputs.repometa).license.spdx_id }}

            org.opencontainers.image.revision=${{ github.sha }}

            org.opencontainers.image.source=${{
              fromJson(needs.prepare.outputs.repometa).clone_url }}

            org.opencontainers.image.title=${{
              fromJson(needs.prepare.outputs.repometa).name }}

            org.opencontainers.image.url=${{
              fromJson(needs.prepare.outputs.repometa).html_url }}

            org.opencontainers.image.version=${{
              needs.prepare.outputs.source_version }}"
          outputs: type=docker,dest=dist/image.tar
          # Uncomment the following option if you are building an image for use
          # on Google Cloud Run or AWS Lambda. The current default image output
          # is unable to run on either. Please see the following issue for more
          # information: https://github.com/docker/buildx/issues/1533
          # provenance: false
          tags: ${{ env.IMAGE_NAME }}:latest  # not to be pushed
          # For a list of pre-defined annotation keys and value types see:
          # https://github.com/opencontainers/image-spec/blob/master/annotations.md
      - name: Compress image
        run: gzip dist/image.tar
      - name: Upload artifacts
        uses: actions/upload-artifact@v4
        with:
          name: dist
          path: dist
      - name: Setup tmate debug session
        uses: mxschmitt/action-tmate@v3
        if: env.RUN_TMATE
  test:
    # Executes tests on the single-platform image created in the "build" job.
    name: Test image
    needs:
      - diagnostics
      - build
    permissions:
      # actions/checkout needs this to fetch code
      contents: read
    runs-on: ubuntu-latest
    steps:
      - uses: GitHubSecurityLab/actions-permissions/monitor@v1
        with:
          # Uses the organization variable unless overridden
          config: ${{ vars.ACTIONS_PERMISSIONS_CONFIG }}
      - id: harden-runner
        name: Harden the runner
        uses: step-security/harden-runner@v2
        with:
          egress-policy: audit
      - id: setup-env
        uses: cisagov/setup-env-github-action@develop
      - uses: actions/checkout@v4
      - id: setup-python
        uses: actions/setup-python@v5
        with:
          python-version: ${{ steps.setup-env.outputs.python-version }}
      - name: Cache testing environments
        uses: actions/cache@v4
        env:
          BASE_CACHE_KEY: "${{ github.job }}-${{ runner.os }}-\
            py${{ steps.setup-python.outputs.python-version }}-"
        with:
          key: "${{ env.BASE_CACHE_KEY }}\
            ${{ hashFiles('**/requirements-test.txt') }}-\
            ${{ hashFiles('**/requirements.txt') }}"
          path: ${{ env.PIP_CACHE_DIR }}
          restore-keys: |
            ${{ env.BASE_CACHE_KEY }}
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip setuptools wheel
          pip install --upgrade --requirement requirements-test.txt
      - name: Download docker image artifact
        uses: actions/download-artifact@v4
        with:
          name: dist
          path: dist
      - name: Load docker image
        run: docker load < dist/image.tar.gz
      - name: Run tests
        env:
          RELEASE_TAG: ${{ github.event.release.tag_name }}
        run: pytest --runslow
      - name: Setup tmate debug session
        uses: mxschmitt/action-tmate@v3
        if: env.RUN_TMATE
  build-push-all:
    # Builds the final set of images for each of the platforms listed in
    # PLATFORMS environment variable.  These images are tagged with the Docker
    # tags calculated in the "prepare" job and pushed to Docker Hub and the
    # GitHub Container Registry.  The contents of README.md are pushed as the
    # image's description to Docker Hub.  This job is skipped when the
    # triggering event is a pull request.
    if: github.event_name != 'pull_request'
    name: Build and push all platforms
    needs:
      - diagnostics
      - lint
      - prepare
      - test
    permissions:
      # actions/checkout needs this to fetch code
      contents: read
      # When Dependabot creates a PR it requires this permission in
      # order to push Docker images to ghcr.io.
      packages: write
    runs-on: ubuntu-latest
    steps:
      - uses: GitHubSecurityLab/actions-permissions/monitor@v1
        with:
          # Uses the organization variable unless overridden
          config: ${{ vars.ACTIONS_PERMISSIONS_CONFIG }}
      - id: harden-runner
        name: Harden the runner
        uses: step-security/harden-runner@v2
        with:
          egress-policy: audit
      - name: Login to Docker Hub
        uses: docker/login-action@v3
        with:
          password: ${{ secrets.DOCKER_PASSWORD }}
          username: ${{ secrets.DOCKER_USERNAME }}
      - name: Login to GitHub Container Registry
        uses: docker/login-action@v3
        with:
          password: ${{ secrets.GITHUB_TOKEN }}
          registry: ghcr.io
          username: ${{ github.actor }}
      - name: Checkout
        uses: actions/checkout@v4
      - name: Set up QEMU
        uses: docker/setup-qemu-action@v3
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3
      - name: Cache Docker layers
        uses: actions/cache@v4
        env:
          BASE_CACHE_KEY: buildx-${{ runner.os }}-
        with:
          key: ${{ env.BASE_CACHE_KEY }}${{ github.sha }}
          path: ${{ env.BUILDX_CACHE_DIR }}
          restore-keys: |
            ${{ env.BASE_CACHE_KEY }}
      - name: Create cross-platform support Dockerfile-x
        run: ./buildx-dockerfile.sh
      - name: Build and push platform images to registries
        id: docker_build
        uses: docker/build-push-action@v6
        with:
          build-args: |
            VERSION=${{ needs.prepare.outputs.source_version }}
          cache-from: type=local,src=${{ env.BUILDX_CACHE_DIR }}
          cache-to: type=local,dest=${{ env.BUILDX_CACHE_DIR }}
          context: .
          file: ./Dockerfile-x
          labels: "\
            org.opencontainers.image.created=${{
              needs.prepare.outputs.created }}

            org.opencontainers.image.description=${{
              fromJson(needs.prepare.outputs.repometa).description }}

            org.opencontainers.image.licenses=${{
              fromJson(needs.prepare.outputs.repometa).license.spdx_id }}

            org.opencontainers.image.revision=${{ github.sha }}

            org.opencontainers.image.source=${{
              fromJson(needs.prepare.outputs.repometa).clone_url }}

            org.opencontainers.image.title=${{
              fromJson(needs.prepare.outputs.repometa).name }}

            org.opencontainers.image.url=${{
              fromJson(needs.prepare.outputs.repometa).html_url }}

            org.opencontainers.image.version=${{
              needs.prepare.outputs.source_version }}"
          platforms: ${{ env.PLATFORMS }}
          # Uncomment the following option if you are building an image for use
          # on Google Cloud Run or AWS Lambda. The current default image output
          # is unable to run on either. Please see the following issue for more
          # information: https://github.com/docker/buildx/issues/1533
          # provenance: false
          push: true
          tags: ${{ needs.prepare.outputs.tags }}
          # For a list of pre-defined annotation keys and value types see:
          # https://github.com/opencontainers/image-spec/blob/master/annotations.md
      - name: Publish README.md to Docker Hub
        env:
          DOCKER_PASSWORD: ${{ secrets.DOCKER_PASSWORD }}
          DOCKER_USERNAME: ${{ secrets.DOCKER_USERNAME }}
        run: ./push_readme.sh
      - name: Setup tmate debug session
        uses: mxschmitt/action-tmate@v3
        if: env.RUN_TMATE