ci-cd.yml

---

name: 🧪

on:
  merge_group:
  push:  # publishes to TestPyPI pushes to the main branch
    branches-ignore:
    - dependabot/**  # Dependabot always creates PRs
    - gh-readonly-queue/**  # Temporary merge queue-related GH-made branches
    - maintenance/pip-tools-constraint-lockfiles  # Lock files through PRs
    - maintenance/pip-tools-constraint-lockfiles-**  # Lock files through PRs
    - patchback/backports/**  # Patchback always creates PRs
    - pre-commit-ci-update-config  # pre-commit.ci always creates a PR
  pull_request:
    types:
    - opened  # default
    - synchronize  # default
    - reopened  # default
    - ready_for_review  # used in PRs created from the release workflow
  schedule:
  - cron: 3 5 * * *  # Run daily at 5:03 UTC
  workflow_dispatch:
    inputs:
      release-version:
        # github.event_name == 'workflow_dispatch'
        # && github.event.inputs.release-version
        description: >-
          Target PEP440-compliant version to release.
          Please, don't prepend `v`.
        required: true
        type: string
      release-committish:
        # github.event_name == 'workflow_dispatch'
        # && github.event.inputs.release-committish
        default: ''
        description: >-
          The commit to be released to PyPI and tagged
          in Git as `release-version`. Normally, you
          should keep this empty.
        type: string
      YOLO:
        default: false
        description: >-
          Set this flag to disregard the outcome of the
          test stage. The test results will block the
          release otherwise. Only use this under
          extraordinary circumstances to ignore the test
          failures and cut the release regardless.
        type: boolean

concurrency:
  group: >-
    ${{
        github.workflow
    }}-${{
        github.ref_type
    }}-${{
        github.event.pull_request.number || github.sha
    }}
  cancel-in-progress: true

env:
  FORCE_COLOR: 1  # Request colored output from CLI tools supporting it
  MYPY_FORCE_COLOR: 1  # MyPy's color enforcement
  PIP_DISABLE_PIP_VERSION_CHECK: 1  # Hide "there's a newer pip" message
  PIP_NO_PYTHON_VERSION_WARNING: 1  # Hide "this Python is deprecated" message
  PIP_NO_WARN_SCRIPT_LOCATION: 1  # Hide "script dir is not in $PATH" message
  PRE_COMMIT_COLOR: always
  PROJECT_NAME: awx-plugins-core
  PUBLISHING_TO_TESTPYPI_ENABLED: false
  PY_COLORS: 1  # Recognized by the `py` package, dependency of `pytest`
  PYTHONIOENCODING: utf-8
  PYTHONUTF8: 1
  TOX_PARALLEL_NO_SPINNER: 1  # Disable tox's parallel run spinner animation
  TOX_TESTENV_PASSENV: >-  # Make tox-wrapped tools see color requests
    FORCE_COLOR
    MYPY_FORCE_COLOR
    NO_COLOR
    PIP_DISABLE_PIP_VERSION_CHECK
    PIP_NO_PYTHON_VERSION_WARNING
    PIP_NO_WARN_SCRIPT_LOCATION
    PRE_COMMIT_COLOR
    PY_COLORS
    PYTEST_THEME
    PYTEST_THEME_MODE
    PYTHONIOENCODING
    PYTHONLEGACYWINDOWSSTDIO
    PYTHONUTF8
  UPSTREAM_REPOSITORY_ID: >-
    836873755

run-name: >-
  ${{
    github.event_name == 'workflow_dispatch'
    && format('📦 Releasing v{0}...', github.event.inputs.release-version)
    || ''
  }}
  ${{
      github.event.pull_request.number && 'PR' || ''
  }}${{
      !github.event.pull_request.number && 'Commit' || ''
  }}
  ${{ github.event.pull_request.number || github.sha }}
  triggered by: ${{ github.event_name }} of ${{
    github.ref
  }} ${{
    github.ref_type
  }}
  (workflow run ID: ${{
    github.run_id
  }}; number: ${{
    github.run_number
  }}; attempt: ${{
    github.run_attempt
  }})

jobs:
  pre-setup:
    name: ⚙️ Pre-set global build settings

    runs-on: ubuntu-latest

    timeout-minutes: 1

    defaults:
      run:
        shell: python

    outputs:
      # NOTE: These aren't env vars because the `${{ env }}` context is
      # NOTE: inaccessible when passing inputs to reusable workflows.
      dists-artifact-name: python-package-distributions
      dist-version: >-
        ${{
            steps.request-check.outputs.release-requested == 'true'
            && github.event.inputs.release-version
            || steps.scm-version.outputs.dist-version
        }}
      is-untagged-devel: >-
        ${{ steps.untagged-check.outputs.is-untagged-devel || false }}
      release-requested: >-
        ${{
            steps.request-check.outputs.release-requested || false
        }}
      is-yolo-mode: >-
        ${{
          (
            steps.request-check.outputs.release-requested == 'true'
            && github.event.inputs.YOLO
          )
          && true || false
        }}
      cache-key-files: >-
        ${{ steps.calc-cache-key-files.outputs.files-hash-key }}
      git-tag: ${{ steps.git-tag.outputs.tag }}
      sdist-artifact-name: ${{ steps.artifact-name.outputs.sdist }}
      wheel-artifact-name: ${{ steps.artifact-name.outputs.wheel }}
      upstream-repository-id: ${{ env.UPSTREAM_REPOSITORY_ID }}
      publishing-to-testpypi-enabled: ${{ env.PUBLISHING_TO_TESTPYPI_ENABLED }}

    steps:
    - name: Switch to using Python 3.11 by default
      uses: actions/setup-python@v5
      with:
        python-version: 3.11
    - name: >-
        Mark the build as untagged '${{
            github.event.repository.default_branch
        }}' branch build
      id: untagged-check
      if: >-
        github.event_name == 'push' &&
        github.ref == format(
          'refs/heads/{0}', github.event.repository.default_branch
        )
      run: |
        from os import environ
        from pathlib import Path

        FILE_APPEND_MODE = 'a'

        with Path(environ['GITHUB_OUTPUT']).open(
                mode=FILE_APPEND_MODE,
        ) as outputs_file:
            print('is-untagged-devel=true', file=outputs_file)
    - name: Mark the build as "release request"
      id: request-check
      if: github.event_name == 'workflow_dispatch'
      run: |
        from os import environ
        from pathlib import Path

        FILE_APPEND_MODE = 'a'

        with Path(environ['GITHUB_OUTPUT']).open(
                mode=FILE_APPEND_MODE,
        ) as outputs_file:
            print('release-requested=true', file=outputs_file)
    - name: Check out src from Git
      if: >-
        steps.request-check.outputs.release-requested != 'true'
      uses: actions/checkout@v4
      with:
        fetch-depth: >-
          ${{
            steps.request-check.outputs.release-requested == 'true'
            && 1 || 0
          }}
        ref: ${{ github.event.inputs.release-committish }}
    - name: >-
        Calculate Python interpreter version hash value
        for use in the cache key
      if: >-
        steps.request-check.outputs.release-requested != 'true'
      id: calc-cache-key-py
      run: |
        from hashlib import sha512
        from os import environ
        from pathlib import Path
        from sys import version

        FILE_APPEND_MODE = 'a'

        hash = sha512(version.encode()).hexdigest()

        with Path(environ['GITHUB_OUTPUT']).open(
                mode=FILE_APPEND_MODE,
        ) as outputs_file:
            print(f'py-hash-key={hash}', file=outputs_file)
    - name: >-
        Calculate dependency files' combined hash value
        for use in the cache key
      if: >-
        steps.request-check.outputs.release-requested != 'true'
      id: calc-cache-key-files
      run: |
        from os import environ
        from pathlib import Path

        FILE_APPEND_MODE = 'a'

        with Path(environ['GITHUB_OUTPUT']).open(
                mode=FILE_APPEND_MODE,
        ) as outputs_file:
            print(
                "files-hash-key=${{
                    hashFiles(
                      'tox.ini',
                      'pyproject.toml',
                      '.pre-commit-config.yaml',
                      'pytest.ini',
                      'dependencies/**/*'
                    )
                }}",
                file=outputs_file,
            )
    - name: Get pip cache dir
      id: pip-cache-dir
      if: >-
        steps.request-check.outputs.release-requested != 'true'
      run: >-
        echo "dir=$(python -m pip cache dir)" >> "${GITHUB_OUTPUT}"
      shell: bash
    - name: Set up pip cache
      if: >-
        steps.request-check.outputs.release-requested != 'true'
      uses: actions/cache@v4
      with:
        path: ${{ steps.pip-cache-dir.outputs.dir }}
        key: >-
          ${{ runner.os }}-pip-${{
          steps.calc-cache-key-py.outputs.py-hash-key }}-${{
          steps.calc-cache-key-files.outputs.files-hash-key }}
        restore-keys: |
          ${{ runner.os }}-pip-${{
              steps.calc-cache-key-py.outputs.py-hash-key
          }}-
          ${{ runner.os }}-pip-
          ${{ runner.os }}-
    - name: Drop Git tags from HEAD for non-release requests
      if: >-
        steps.request-check.outputs.release-requested != 'true'
      run: >-
        git tag --points-at HEAD
        |
        xargs git tag --delete
      shell: bash
    - name: Set up versioning prerequisites
      if: >-
        steps.request-check.outputs.release-requested != 'true'
      run: >-
        python -m
        pip install
        --user
        setuptools-scm
      shell: bash
    - name: Set the current dist version from Git
      if: steps.request-check.outputs.release-requested != 'true'
      id: scm-version
      run: |
        from os import environ
        from pathlib import Path

        import setuptools_scm

        FILE_APPEND_MODE = 'a'

        ver = setuptools_scm.get_version(
          ${{
              steps.untagged-check.outputs.is-untagged-devel == 'true'
              && 'local_scheme="no-local-version"' || ''
          }}
        )
        with Path(environ['GITHUB_OUTPUT']).open(
                mode=FILE_APPEND_MODE,
        ) as outputs_file:
            print(f'dist-version={ver}', file=outputs_file)
            print(
                f'dist-version-for-filenames={ver.replace("+", "-")}',
                file=outputs_file,
            )
    - name: Set the target Git tag
      id: git-tag
      run: |
        from os import environ
        from pathlib import Path

        FILE_APPEND_MODE = 'a'

        with Path(environ['GITHUB_OUTPUT']).open(
                mode=FILE_APPEND_MODE,
        ) as outputs_file:
            print(
                "tag=v${{
                    steps.request-check.outputs.release-requested == 'true'
                    && github.event.inputs.release-version
                    || steps.scm-version.outputs.dist-version
                }}",
                file=outputs_file,
            )
    - name: Set the expected dist artifact names
      id: artifact-name
      run: |
        from os import environ
        from pathlib import Path

        FILE_APPEND_MODE = 'a'

        dist_file_prj_base_name = '${{ env.PROJECT_NAME }}'.replace('-', '_')
        with Path(environ['GITHUB_OUTPUT']).open(
                mode=FILE_APPEND_MODE,
        ) as outputs_file:
            print(
                f"sdist={dist_file_prj_base_name !s}-${{
                    steps.request-check.outputs.release-requested == 'true'
                    && github.event.inputs.release-version
                    || steps.scm-version.outputs.dist-version
                }}.tar.gz",
                file=outputs_file,
            )
            print(
                f"wheel={dist_file_prj_base_name !s}-${{
                    steps.request-check.outputs.release-requested == 'true'
                    && github.event.inputs.release-version
                    || steps.scm-version.outputs.dist-version
                }}-py3-none-any.whl",
                file=outputs_file,
            )

  build:
    name: >-
      📦 ${{ needs.pre-setup.outputs.git-tag }}
      [mode: ${{
        fromJSON(needs.pre-setup.outputs.is-untagged-devel)
        && 'test' || ''
      }}${{
        fromJSON(needs.pre-setup.outputs.release-requested)
        && 'release' || ''
      }}${{
        (
          !fromJSON(needs.pre-setup.outputs.is-untagged-devel)
          && !fromJSON(needs.pre-setup.outputs.release-requested)
        ) && 'nightly' || ''
      }}]
    needs:
    - pre-setup

    runs-on: ubuntu-latest

    timeout-minutes: 2

    env:
      TOXENV: cleanup-dists,build-dists

    outputs:
      dists-base64-hash: ${{ steps.dist-hashes.outputs.combined-hash }}

    steps:
    - name: Switch to using Python 3.11
      uses: actions/setup-python@v5
      with:
        python-version: 3.11

    - name: Grab the source from Git
      uses: actions/checkout@v4
      with:
        fetch-depth: >-
          ${{
              fromJSON(needs.pre-setup.outputs.release-requested)
              && 1 || 0
          }}
        ref: ${{ github.event.inputs.release-committish }}

    - name: >-
        Calculate Python interpreter version hash value
        for use in the cache key
      id: calc-cache-key-py
      run: |
        from hashlib import sha512
        from os import environ
        from pathlib import Path
        from sys import version

        FILE_APPEND_MODE = 'a'

        hash = sha512(version.encode()).hexdigest()

        with Path(environ['GITHUB_OUTPUT']).open(
                mode=FILE_APPEND_MODE,
        ) as outputs_file:
            print(f'py-hash-key={hash}', file=outputs_file)
      shell: python
    - name: Get pip cache dir
      id: pip-cache-dir
      run: >-
        echo "dir=$(python -m pip cache dir)" >> "${GITHUB_OUTPUT}"
    - name: Set up pip cache
      uses: actions/cache@v4
      with:
        path: ${{ steps.pip-cache-dir.outputs.dir }}
        key: >-
          ${{ runner.os }}-pip-${{
          steps.calc-cache-key-py.outputs.py-hash-key }}-${{
          needs.pre-setup.outputs.cache-key-files }}
        restore-keys: |
          ${{ runner.os }}-pip-${{
              steps.calc-cache-key-py.outputs.py-hash-key
          }}-
          ${{ runner.os }}-pip-

    - name: Identify tox's own lock file
      id: tox-deps
      run: >
        LOCK_FILE_PATH="dependencies/lock-files/$(
        python bin/print_lockfile_base_name.py tox
        ).txt"


        echo lock-file="$(
        ls -1 "${LOCK_FILE_PATH}"
        || >&2 echo "${LOCK_FILE_PATH}" not found, not injecting...
        )"
        >> "${GITHUB_OUTPUT}"
      shell: bash  # windows compat

    - name: Install tox
      run: >-
        python -Im pip install -r dependencies/direct/tox.in
        ${{
          steps.tox-deps.outputs.lock-file
          && format('--constraint={0}', steps.tox-deps.outputs.lock-file)
          || ''
        }}
      shell: bash  # windows compat

    - name: Pre-populate the tox env
      run: >-
        python -m
        tox
        --parallel auto
        --parallel-live
        --skip-missing-interpreters false
        --notest

    - name: Drop Git tags from HEAD for non-tag-create events
      if: >-
        !fromJSON(needs.pre-setup.outputs.release-requested)
      run: >-
        git tag --points-at HEAD
        |
        xargs git tag --delete
      shell: bash

    - name: Setup git user as [bot]
      if: >-
        fromJSON(needs.pre-setup.outputs.release-requested)
        || fromJSON(needs.pre-setup.outputs.is-untagged-devel)
      uses: fregante/setup-git-user@v2
    - name: >-
        Tag the release in the local Git repo
        as ${{ needs.pre-setup.outputs.git-tag }}
        for setuptools-scm to set the desired version
      if: >-
        fromJSON(needs.pre-setup.outputs.release-requested)
      run: >-
        git tag
        -m '${{ needs.pre-setup.outputs.git-tag }}'
        '${{ needs.pre-setup.outputs.git-tag }}'
        --
        ${{
          fromJSON(needs.pre-setup.outputs.release-requested)
          && github.event.inputs.release-committish || ''
        }}

    - name: Install tomlkit Python distribution package
      if: >-
        fromJSON(needs.pre-setup.outputs.is-untagged-devel)
      run: >-
        python -m pip install --user tomlkit
    - name: Instruct setuptools-scm not to add a local version part
      if: >-
        fromJSON(needs.pre-setup.outputs.is-untagged-devel)
      run: |
        from pathlib import Path

        import tomlkit

        pyproject_toml_path = Path.cwd() / 'pyproject.toml'
        pyproject_toml_txt = pyproject_toml_path.read_text()
        pyproject_toml = tomlkit.loads(pyproject_toml_txt)
        setuptools_scm_section = pyproject_toml['tool']['setuptools_scm']
        setuptools_scm_section['local_scheme'] = 'no-local-version'
        patched_pyproject_toml_txt = tomlkit.dumps(pyproject_toml)
        pyproject_toml_path.write_text(patched_pyproject_toml_txt)
      shell: python
    - name: Pretend that pyproject.toml is unchanged
      if: >-
        fromJSON(needs.pre-setup.outputs.is-untagged-devel)
      run: |
        git diff --color=always
        git update-index --assume-unchanged pyproject.toml

    - name: Set static timestamp for dist build reproducibility
      # ... from the last Git commit since it's immutable
      run: >-
        echo "SOURCE_DATE_EPOCH=$(git log -1 --pretty=%ct)"
        >> "${GITHUB_ENV}"
    - name: Build dists
      run: >-
        python -m
        tox
        --parallel auto
        --parallel-live
        --skip-missing-interpreters false
        --skip-pkg-install
        --quiet
    - name: Verify that the artifacts with expected names got created
      run: >-
        ls -1
        'dist/${{ needs.pre-setup.outputs.sdist-artifact-name }}'
        'dist/${{ needs.pre-setup.outputs.wheel-artifact-name }}'
    - name: Generate dist hashes to be used fore provenance
      id: dist-hashes
      run: >-
        echo "combined-hash=$(sha256sum * | base64 -w0)"
        >> "${GITHUB_OUTPUT}"
      working-directory: dist
    - name: Store the distribution packages
      uses: actions/upload-artifact@v4
      with:
        name: >-
          ${{ needs.pre-setup.outputs.dists-artifact-name }}
        # NOTE: Exact expected file names are specified here
        # NOTE: as a safety measure — if anything weird ends
        # NOTE: up being in this dir or not all dists will be
        # NOTE: produced, this will fail the workflow.
        path: |
          dist/${{ needs.pre-setup.outputs.sdist-artifact-name }}
          dist/${{ needs.pre-setup.outputs.wheel-artifact-name }}
        retention-days: >-
          ${{
              (
                fromJSON(needs.pre-setup.outputs.release-requested)
              ) && 90 || 30
          }}

  lint:
    name: 🧹 Linters${{ '' }}  # nest jobs under the same sidebar category
    needs:
    - build
    - pre-setup  # transitive, for accessing settings
    strategy:
      matrix:
        runner-vm-os:
        - ubuntu-latest
        python-version:
        - 3.11
        toxenv:
        - pre-commit
        - metadata-validation
        - build-docs
        - coverage-docs
        - doctest-docs
        - linkcheck-docs
        - spellcheck-docs
      fail-fast: false
    uses: ./.github/workflows/reusable-tox.yml
    with:
      cache-key-files: >-
        ${{ needs.pre-setup.outputs.cache-key-files }}
      dists-artifact-name: >-
        ${{ needs.pre-setup.outputs.dists-artifact-name }}
      python-version: >-
        ${{ matrix.python-version }}
      release-requested: >-
        ${{ needs.pre-setup.outputs.release-requested }}
      runner-vm-os: >-
        ${{ matrix.runner-vm-os }}
      source-tarball-name: >-
        ${{ needs.pre-setup.outputs.sdist-artifact-name }}
      timeout-minutes: 3
      toxenv: >-
        ${{ matrix.toxenv }}
      upstream-repository-id: >-
        ${{ needs.pre-setup.outputs.upstream-repository-id }}
      yolo: >-
        ${{ fromJSON(needs.pre-setup.outputs.is-yolo-mode) }}
    secrets:
      codecov-token: ${{ secrets.CODECOV_TOKEN }}

  tests:
    name: 🧪 Tests${{ '' }}  # nest jobs under the same sidebar category
    needs:
    - build
    - pre-setup  # transitive, for accessing settings
    strategy:
      matrix:
        python-version:
        # NOTE: The latest and the lowest supported Pythons are prioritized
        # NOTE: to improve the responsiveness. It's nice to see the most
        # NOTE: important results first.
        - 3.12
        - 3.11
        - ~3.13.0-0
        runner-vm-os:
        - ubuntu-24.04
        - macos-14
        - macos-13
        toxenv:
        - py

    uses: ./.github/workflows/reusable-tox.yml
    with:
      built-wheel-names: >-
        ${{ needs.pre-setup.outputs.wheel-artifact-name }}
      cache-key-files: >-
        ${{ needs.pre-setup.outputs.cache-key-files }}
      dists-artifact-name: >-
        ${{ needs.pre-setup.outputs.dists-artifact-name }}
      python-version: >-
        ${{ matrix.python-version }}
      release-requested: >-
        ${{ needs.pre-setup.outputs.release-requested }}
      runner-vm-os: >-
        ${{ matrix.runner-vm-os }}
      source-tarball-name: >-
        ${{ needs.pre-setup.outputs.sdist-artifact-name }}
      timeout-minutes: 5
      toxenv: >-
        ${{ matrix.toxenv }}
      tox-run-posargs: >-
        --cov-report=xml:.tox/.tmp/.test-results/pytest-${{
          matrix.python-version
        }}/cobertura.xml
        --junitxml=.tox/.tmp/.test-results/pytest-${{
          matrix.python-version
        }}/test.xml
      tox-rerun-posargs: >-
        --no-cov
        -vvvvv
        --lf
      upstream-repository-id: >-
        ${{ needs.pre-setup.outputs.upstream-repository-id }}
      yolo: >-
        ${{ fromJSON(needs.pre-setup.outputs.is-yolo-mode) }}
    secrets:
      codecov-token: ${{ secrets.CODECOV_TOKEN }}

  check:  # This job does nothing and is only used for the branch protection
    if: always()

    needs:
    - lint
    - pre-setup  # transitive, for accessing settings
    - tests

    runs-on: ubuntu-latest

    timeout-minutes: 1

    steps:
    - name: Decide whether the needed jobs succeeded or failed
      uses: re-actors/alls-green@release/v1
      with:
        allowed-failures: >-
          ${{
            fromJSON(needs.pre-setup.outputs.is-yolo-mode)
            && 'lint, tests'
            || ''
          }}
        jobs: ${{ toJSON(needs) }}

  publish-pypi:
    name: Publish 🐍📦 ${{ needs.pre-setup.outputs.git-tag }} to PyPI
    needs:
    - check
    - pre-setup  # transitive, for accessing settings
    if: >-
      always()
      && needs.check.result == 'success'
      && fromJSON(needs.pre-setup.outputs.release-requested)
      && needs.pre-setup.outputs.upstream-repository-id == github.repository_id

    runs-on: ubuntu-latest

    timeout-minutes: 1

    environment:
      name: pypi
      url: >-
        https://pypi.org/project/${{ env.PROJECT_NAME }}/${{
          needs.pre-setup.outputs.dist-version
        }}

    permissions:
      contents: read  # This job doesn't need to `git push` anything
      id-token: write  # PyPI Trusted Publishing (OIDC)

    steps:
    - name: Download all the dists
      uses: actions/download-artifact@v4
      with:
        name: >-
          ${{ needs.pre-setup.outputs.dists-artifact-name }}
        path: dist/
    - name: >-
        Publish 🐍📦 ${{ needs.pre-setup.outputs.git-tag }} to PyPI
      uses: pypa/gh-action-pypi-publish@release/v1

  publish-testpypi:
    name: Publish 🐍📦 ${{ needs.pre-setup.outputs.git-tag }} to TestPyPI
    needs:
    - check
    - pre-setup  # transitive, for accessing settings
    if: >-
      always()
      && needs.check.result == 'success'
      && (
        fromJSON(needs.pre-setup.outputs.is-untagged-devel)
        || fromJSON(needs.pre-setup.outputs.release-requested)
      )
      && needs.pre-setup.outputs.upstream-repository-id == github.repository_id
      && fromJSON(needs.pre-setup.outputs.publishing-to-testpypi-enabled)

    runs-on: ubuntu-latest

    timeout-minutes: 1

    environment:
      name: testpypi
      url: >-
        https://test.pypi.org/project/${{ env.PROJECT_NAME }}/${{
          needs.pre-setup.outputs.dist-version
        }}

    permissions:
      contents: read  # This job doesn't need to `git push` anything
      id-token: write  # PyPI Trusted Publishing (OIDC)

    steps:
    - name: Download all the dists
      uses: actions/download-artifact@v4
      with:
        name: >-
          ${{ needs.pre-setup.outputs.dists-artifact-name }}
        path: dist/
    - name: >-
        Publish 🐍📦 ${{ needs.pre-setup.outputs.git-tag }} to TestPyPI
      uses: pypa/gh-action-pypi-publish@release/v1
      with:
        repository-url: https://test.pypi.org/legacy/

...