build.yml

---
name: build

on:  # yamllint disable-line rule:truthy
  merge_group:
    types:
      - checks_requested
  pull_request:
  push:
  repository_dispatch:
    types:
      - apb

# 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:
  PIP_CACHE_DIR: ~/.cache/pip
  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.
      - name: Apply standard cisagov job preamble
        uses: cisagov/action-job-preamble@v1
        with:
          check_github_status: "true"
          # This functionality is poorly implemented and has been
          # causing problems due to the MITM implementation hogging or
          # leaking memory.  As a result we disable it by default.  If
          # you want to temporarily enable it, simply set
          # monitor_permissions equal to "true".
          #
          # TODO: Re-enable this functionality when practical.  See
          # cisagov/skeleton-generic#207 for more details.
          monitor_permissions: "false"
          output_workflow_context: "true"
          # Use a variable to specify the permissions monitoring
          # configuration. By default this will yield the
          # configuration stored in the cisagov organization-level
          # variable, but if you want to use a different configuration
          # then simply:
          # 1. Create a repository-level variable with the name
          # ACTIONS_PERMISSIONS_CONFIG.
          # 2. Set this new variable's value to the configuration you
          # want to use for this repository.
          #
          # Note in particular that changing the permissions
          # monitoring configuration *does not* require you to modify
          # this workflow.
          permissions_monitoring_config: ${{ vars.ACTIONS_PERMISSIONS_CONFIG }}
  lint:
    needs:
      - diagnostics
    permissions:
      # actions/checkout needs this to fetch code
      contents: read
    runs-on: ubuntu-latest
    steps:
      - name: Apply standard cisagov job preamble
        uses: cisagov/action-job-preamble@v1
        with:
          # This functionality is poorly implemented and has been
          # causing problems due to the MITM implementation hogging or
          # leaking memory.  As a result we disable it by default.  If
          # you want to temporarily enable it, simply set
          # monitor_permissions equal to "true".
          #
          # TODO: Re-enable this functionality when practical.  See
          # cisagov/skeleton-generic#207 for more details.
          monitor_permissions: "false"
          # Use a variable to specify the permissions monitoring
          # configuration. By default this will yield the
          # configuration stored in the cisagov organization-level
          # variable, but if you want to use a different configuration
          # then simply:
          # 1. Create a repository-level variable with the name
          # ACTIONS_PERMISSIONS_CONFIG.
          # 2. Set this new variable's value to the configuration you
          # want to use for this repository.
          #
          # Note in particular that changing the permissions
          # monitoring configuration *does not* require you to modify
          # this workflow.
          permissions_monitoring_config: ${{ vars.ACTIONS_PERMISSIONS_CONFIG }}
      - id: setup-env
        uses: cisagov/setup-env-github-action@v1
      - uses: actions/checkout@v6
      - id: setup-python
        uses: actions/setup-python@v6
        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@v6
        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:
          # We do not use '**/setup.py' in the cache key so only the 'setup.py'
          # file in the root of the repository is used. This is in case a Python
          # package were to have a 'setup.py' as part of its internal codebase.
          key: ${{ env.BASE_CACHE_KEY }}\
            ${{ hashFiles('**/requirements-test.txt') }}-\
            ${{ hashFiles('**/requirements.txt') }}-\
            ${{ hashFiles('**/.pre-commit-config.yaml') }}-\
            ${{ hashFiles('setup.py') }}
          # 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
  test:
    name: test source - py${{ matrix.python-version }} - ${{ matrix.platform }}
    needs:
      - diagnostics
    permissions:
      # actions/checkout needs this to fetch code
      contents: read
    runs-on: ${{ matrix.platform }}
    strategy:
      fail-fast: false
      matrix:
        include:
          - platform: ubuntu-22.04
            python-version: "3.7"
        # We test on all of the latest platforms available to use with GitHub-
        # hosted runners for public repositories.
        platform:
          - macos-latest
          - ubuntu-24.04-arm
          - ubuntu-latest
          - windows-latest
        python-version:
          - "3.8"
          - "3.9"
          - "3.10"
          - "3.11"
          - "3.12"
          - "3.13"
          - "3.14"
    steps:
      - name: Apply standard cisagov job preamble
        uses: cisagov/action-job-preamble@v1
        with:
          # This functionality is poorly implemented and has been
          # causing problems due to the MITM implementation hogging or
          # leaking memory.  As a result we disable it by default.  If
          # you want to temporarily enable it, simply set
          # monitor_permissions equal to "true".
          #
          # TODO: Re-enable this functionality when practical.  See
          # cisagov/skeleton-python-library#149 for more details.
          monitor_permissions: "false"
          # Use a variable to specify the permissions monitoring
          # configuration. By default this will yield the
          # configuration stored in the cisagov organization-level
          # variable, but if you want to use a different configuration
          # then simply:
          # 1. Create a repository-level variable with the name
          # ACTIONS_PERMISSIONS_CONFIG.
          # 2. Set this new variable's value to the configuration you
          # want to use for this repository.
          #
          # Note in particular that changing the permissions
          # monitoring configuration *does not* require you to modify
          # this workflow.
          permissions_monitoring_config: ${{ vars.ACTIONS_PERMISSIONS_CONFIG }}
      - uses: actions/checkout@v6
      - id: setup-python
        uses: actions/setup-python@v6
        with:
          python-version: ${{ matrix.python-version }}
      - uses: actions/cache@v4
        env:
          BASE_CACHE_KEY: ${{ github.job }}-\
            ${{ runner.os }}-${{ runner.arch }}-\
            py${{ steps.setup-python.outputs.python-version }}-
        with:
          path: ${{ env.PIP_CACHE_DIR }}
          # We do not use '**/setup.py' in the cache key so only the 'setup.py'
          # file in the root of the repository is used. This is in case a Python
          # package were to have a 'setup.py' as part of its internal codebase.
          key: ${{ env.BASE_CACHE_KEY }}\
            ${{ hashFiles('**/requirements-test.txt') }}-\
            ${{ hashFiles('**/requirements.txt') }}-\
            ${{ hashFiles('setup.py') }}
          restore-keys: |
            ${{ env.BASE_CACHE_KEY }}
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install --upgrade --requirement requirements-test.txt
      - name: Run tests
        env:
          RELEASE_TAG: ${{ github.event.release.tag_name }}
        run: pytest
      - name: Upload coverage report
        uses: coverallsapp/github-action@v2
        with:
          flag-name: py${{ matrix.python-version }} - ${{ matrix.platform }}
          parallel: true
        if: success()
      - name: Setup tmate debug session
        uses: mxschmitt/action-tmate@v3
        if: env.RUN_TMATE
  coveralls-finish:
    permissions:
      # actions/checkout needs this to fetch code
      contents: read
    runs-on: ubuntu-latest
    needs:
      - diagnostics
      - test
    steps:
      - name: Apply standard cisagov job preamble
        uses: cisagov/action-job-preamble@v1
        with:
          # This functionality is poorly implemented and has been
          # causing problems due to the MITM implementation hogging or
          # leaking memory.  As a result we disable it by default.  If
          # you want to temporarily enable it, simply set
          # monitor_permissions equal to "true".
          #
          # TODO: Re-enable this functionality when practical.  See
          # cisagov/skeleton-python-library#149 for more details.
          monitor_permissions: "false"
          # Use a variable to specify the permissions monitoring
          # configuration. By default this will yield the
          # configuration stored in the cisagov organization-level
          # variable, but if you want to use a different configuration
          # then simply:
          # 1. Create a repository-level variable with the name
          # ACTIONS_PERMISSIONS_CONFIG.
          # 2. Set this new variable's value to the configuration you
          # want to use for this repository.
          #
          # Note in particular that changing the permissions
          # monitoring configuration *does not* require you to modify
          # this workflow.
          permissions_monitoring_config: ${{ vars.ACTIONS_PERMISSIONS_CONFIG }}
      - uses: actions/checkout@v6
      - name: Finished coveralls reports
        uses: coverallsapp/github-action@v2
        with:
          parallel-finished: true
      - name: Setup tmate debug session
        uses: mxschmitt/action-tmate@v3
        if: env.RUN_TMATE
  build:
    name: build wheel - py${{ matrix.python-version }}
    needs:
      - diagnostics
      - lint
      - test
    permissions:
      # actions/checkout needs this to fetch code
      contents: read
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        include:
          - os: ubuntu-22.04
            python-version: "3.7"
        os:
          - ubuntu-latest
        python-version:
          - "3.8"
          - "3.9"
          - "3.10"
          - "3.11"
          - "3.12"
          - "3.13"
          - "3.14"
    steps:
      - name: Apply standard cisagov job preamble
        uses: cisagov/action-job-preamble@v1
        with:
          # This functionality is poorly implemented and has been
          # causing problems due to the MITM implementation hogging or
          # leaking memory.  As a result we disable it by default.  If
          # you want to temporarily enable it, simply set
          # monitor_permissions equal to "true".
          #
          # TODO: Re-enable this functionality when practical.  See
          # cisagov/skeleton-python-library#149 for more details.
          monitor_permissions: "false"
          # Use a variable to specify the permissions monitoring
          # configuration. By default this will yield the
          # configuration stored in the cisagov organization-level
          # variable, but if you want to use a different configuration
          # then simply:
          # 1. Create a repository-level variable with the name
          # ACTIONS_PERMISSIONS_CONFIG.
          # 2. Set this new variable's value to the configuration you
          # want to use for this repository.
          #
          # Note in particular that changing the permissions
          # monitoring configuration *does not* require you to modify
          # this workflow.
          permissions_monitoring_config: ${{ vars.ACTIONS_PERMISSIONS_CONFIG }}
      - uses: actions/checkout@v6
      - id: setup-python
        uses: actions/setup-python@v6
        with:
          python-version: ${{ matrix.python-version }}
      - uses: actions/cache@v4
        env:
          BASE_CACHE_KEY: ${{ github.job }}-${{ runner.os }}-\
            py${{ steps.setup-python.outputs.python-version }}-
        with:
          path: ${{ env.PIP_CACHE_DIR }}
          # We do not use '**/setup.py' in the cache key so only the 'setup.py'
          # file in the root of the repository is used. This is in case a Python
          # package were to have a 'setup.py' as part of its internal codebase.
          key: ${{ env.BASE_CACHE_KEY }}\
            ${{ hashFiles('**/requirements.txt') }}-\
            ${{ hashFiles('setup.py') }}
          restore-keys: |
            ${{ env.BASE_CACHE_KEY }}
      - name: Install build dependencies
        run: |
          python -m pip install --upgrade pip setuptools wheel
          python -m pip install --upgrade build
      - name: Build artifacts
        run: python -m build
      - name: Upload artifacts
        uses: actions/upload-artifact@v6
        with:
          name: dist-${{ matrix.python-version }}
          path: dist
      - name: Setup tmate debug session
        uses: mxschmitt/action-tmate@v3
        if: env.RUN_TMATE
  test-build:
    name: test built wheel - py${{ matrix.python-version }} - ${{ matrix.platform }}
    needs:
      - diagnostics
      - build
    permissions:
      # actions/checkout needs this to fetch code
      contents: read
    runs-on: ${{ matrix.platform }}
    strategy:
      fail-fast: false
      matrix:
        include:
          - platform: ubuntu-22.04
            python-version: "3.7"
        # We test on all of the latest platforms available to use with GitHub-
        # hosted runners for public repositories.
        platform:
          - macos-latest
          - ubuntu-24.04-arm
          - ubuntu-latest
          - windows-latest
        python-version:
          - "3.8"
          - "3.9"
          - "3.10"
          - "3.11"
          - "3.12"
          - "3.13"
          - "3.14"
    steps:
      - name: Apply standard cisagov job preamble
        uses: cisagov/action-job-preamble@v1
        with:
          # This functionality is poorly implemented and has been
          # causing problems due to the MITM implementation hogging or
          # leaking memory.  As a result we disable it by default.  If
          # you want to temporarily enable it, simply set
          # monitor_permissions equal to "true".
          #
          # TODO: Re-enable this functionality when practical.  See
          # cisagov/skeleton-python-library#149 for more details.
          monitor_permissions: "false"
          # Use a variable to specify the permissions monitoring
          # configuration. By default this will yield the
          # configuration stored in the cisagov organization-level
          # variable, but if you want to use a different configuration
          # then simply:
          # 1. Create a repository-level variable with the name
          # ACTIONS_PERMISSIONS_CONFIG.
          # 2. Set this new variable's value to the configuration you
          # want to use for this repository.
          #
          # Note in particular that changing the permissions
          # monitoring configuration *does not* require you to modify
          # this workflow.
          permissions_monitoring_config: ${{ vars.ACTIONS_PERMISSIONS_CONFIG }}
      - uses: actions/checkout@v6
      - id: setup-python
        uses: actions/setup-python@v6
        with:
          python-version: ${{ matrix.python-version }}
      - uses: actions/cache@v4
        env:
          BASE_CACHE_KEY: ${{ github.job }}-\
            ${{ runner.os }}-${{ runner.arch }}-\
            py${{ steps.setup-python.outputs.python-version }}-
        with:
          path: ${{ env.PIP_CACHE_DIR }}
          # We do not use '**/setup.py' in the cache key so only the 'setup.py'
          # file in the root of the repository is used. This is in case a Python
          # package were to have a 'setup.py' as part of its internal codebase.
          key: ${{ env.BASE_CACHE_KEY }}\
            ${{ hashFiles('**/requirements.txt') }}-\
            ${{ hashFiles('setup.py') }}
          restore-keys: |
            ${{ env.BASE_CACHE_KEY }}
      - name: Retrieve the built wheel
        uses: actions/download-artifact@v7
        with:
          name: dist-${{ matrix.python-version }}
          path: dist
      - id: find-wheel
        name: Get the name of the retrieved wheel (there should only be one)
        run: echo "wheel=$(ls dist/*whl)" >> $GITHUB_OUTPUT
      - name: Update core Python packages
        run: python -m pip install --upgrade pip setuptools wheel
      - name: Install the built wheel (along with testing dependencies)
        run: python -m pip install ${{ steps.find-wheel.outputs.wheel }}[test]
      - name: Run tests
        env:
          RELEASE_TAG: ${{ github.event.release.tag_name }}
        run: pytest
      - name: Setup tmate debug session
        uses: mxschmitt/action-tmate@v3
        if: env.RUN_TMATE