release.yml

name: Release

# RELEASE PROCESS
#
# === Automated activities ===
#
# 1.  [Seal] Bump to release version and export source code with integrity hash
# 2.  [Quality check] Restore sealed source code, run tests, linting, security and complexity base line
# 3.  [Build] Restore sealed source code, create and export hashed build artifact for PyPi release (wheel, tarball)
# 4.  [Release] Restore built artifact, and publish package to PyPi prod repository
# 5.  [Create Tag] Restore sealed source code, and create a new git tag using released version
# 6.  [PR to bump version] Restore sealed source code, and create a PR to update trunk with latest released project metadata
# 7.  [Publish Layer] Compile Layer and kick off pipeline for beta, prod, and canary releases
# 8.  [Publish Layer] Update docs with latest Layer ARNs and Changelog
# 9.  [Publish Layer] Create PR to update trunk so staged docs also point to the latest Layer ARN, when merged
# 10. [Publish Layer] Builds a new user guide and API docs with release version; update /latest pointing to newly released version
# 11. [Post release] Close all issues labeled "pending-release" and notify customers about the release
#
# === Manual activities ===
#
# 1. Kick off this workflow with the intended version
# 2. Update draft release notes after this workflow completes
# 3. If not already set, use `v<new version>` as a tag, e.g., v1.26.4, and select develop as target branch

# See MAINTAINERS.md "Releasing a new version" for release mechanisms

env:
  RELEASE_COMMIT: ${{ github.sha }}
  RELEASE_TAG_VERSION: ${{ inputs.version_to_publish }}

on:
  workflow_dispatch:
    inputs:
      version_to_publish:
        description: "Version to be released in PyPi, Docs, and Lambda Layer, e.g. v2.0.0, v2.0.0a0 (pre-release)"
        default: v2.0.0
        required: true
      skip_pypi:
        description: "Skip publishing to PyPi as it can't publish more than once. Useful for semi-failed releases"
        default: false
        type: boolean
        required: false
      skip_code_quality:
        description: "Skip tests, linting, and baseline. Only use if release fail for reasons beyond our control and you need a quick release."
        default: false
        type: boolean
        required: false
      pre_release:
        description: "Publishes documentation using a pre-release tag (v2.0.0a0). You are still responsible for passing a pre-release version tag to the workflow."
        default: false
        type: boolean
        required: false

jobs:

  # This job bumps the package version to the release version
  # creates an integrity hash from the source code
  # uploads the artifact with the integrity hash as the key name
  # so subsequent jobs can restore from a trusted point in time to prevent tampering
  seal:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    outputs:
        SOURCE_CODE_HASH: ${{ steps.integrity.outputs.SOURCE_CODE_HASH }}
        RELEASE_VERSION: ${{ steps.release_version.outputs.RELEASE_VERSION }}
    steps:
      - name: Export release version
        id: release_version
        # transform tag format `v<version` to `<version>`
        run: |
          RELEASE_VERSION="${RELEASE_TAG_VERSION:1}"
          echo "RELEASE_VERSION=${RELEASE_VERSION}" >> "$GITHUB_OUTPUT"

      - uses: actions/checkout@8e5e7e5ab8b370d6c329ec480221332ada57f0ab  # v3.5.2
        with:
          ref: ${{ env.RELEASE_COMMIT }}

      # We use a pinned version of Poetry to be certain it won't modify source code before we create a hash
      - name: Install poetry
        run: |
          pipx install git+https://github.com/python-poetry/poetry@68b88e5390720a3dd84f02940ec5200bfce39ac6 # v1.5.0
          pipx inject poetry git+https://github.com/monim67/poetry-bumpversion@ef49c63acef7fe8680789ddb31f376cc898f0012 # v0.3.0

      - name: Bump package version
        id: versioning
        run: poetry version "${RELEASE_VERSION}"
        env:
          RELEASE_VERSION: ${{ steps.release_version.outputs.RELEASE_VERSION}}

      - name: Create integrity hash
        id: integrity
        run: echo "SOURCE_CODE_HASH=${HASH}" >> "$GITHUB_OUTPUT"
        env:
          # paths to hash and why they're important to protect
          #
          # aws_lambda_powertools/  - source code
          # pyproject.toml          - project metadata
          # poetry.lock             - project dependencies
          # layer/                  - layer infrastructure and pipeline
          # .github/                - github scripts and actions used in the release
          # docs/                   - user guide documentation
          # examples/               - user guide code snippets
          HASH: ${{ hashFiles('aws_lambda_powertools/**', 'pyproject.toml', 'poetry.lock', 'layer/**', '.github/**', 'docs/**', 'examples/**')}}

      - name: Upload sealed source code
        uses: ./.github/actions/upload-artifact
        with:
          name: source-${{ steps.integrity.outputs.SOURCE_CODE_HASH }}
          path: .


  # This job runs our automated test suite, complexity and security baselines
  # it ensures previously merged have been tested as part of the pull request process
  #
  # NOTE
  #
  # we don't upload the artifact after testing to prevent any tampering of our source code dependencies
  quality_check:
    needs: seal
    runs-on: ubuntu-latest
    permissions:
      contents: read
    env:
      SOURCE_INTEGRITY_HASH: ${{ needs.seal.outputs.SOURCE_CODE_HASH }}
    steps:
      # NOTE: we need actions/checkout to configure git first (pre-commit hooks in make dev)
      - uses: actions/checkout@8e5e7e5ab8b370d6c329ec480221332ada57f0ab  # v3.5.2
        with:
          ref: ${{ env.RELEASE_COMMIT }}

      - name: Restore sealed source code
        uses: ./.github/actions/download-artifact
        with:
          name: source-${{ env.SOURCE_INTEGRITY_HASH }}
          path: .

      - name: Debug cache restore
        run: cat pyproject.toml

      - name: Install poetry
        run: pipx install git+https://github.com/python-poetry/poetry@68b88e5390720a3dd84f02940ec5200bfce39ac6 # v1.5.0
      - name: Set up Python
        uses: actions/setup-python@bd6b4b6205c4dbad673328db7b31b7fab9e241c0 # v4.6.1
        with:
          python-version: "3.10"
          cache: "poetry"
      - name: Install dependencies
        run: make dev
      - name: Run all tests, linting and baselines
        run: make pr

  # This job creates a release artifact (tar.gz, wheel)
  # it checks out code from release commit for custom actions to work
  # then restores the sealed source code (overwrites any potential tampering)
  # it's done separately from release job to enforce least privilege.
  # We export just the final build artifact for release (release-<integrity-hash>)
  build:
    runs-on: ubuntu-latest
    needs: [quality_check, seal]
    permissions:
      contents: read
    outputs:
      BUILD_INTEGRITY_HASH: ${{ steps.integrity.outputs.BUILD_INTEGRITY_HASH }}
    env:
      SOURCE_INTEGRITY_HASH: ${{ needs.seal.outputs.SOURCE_CODE_HASH }}
    steps:
      # NOTE: we need actions/checkout to configure git first (pre-commit hooks in make dev)
      - uses: actions/checkout@8e5e7e5ab8b370d6c329ec480221332ada57f0ab  # v3.5.2
        with:
          ref: ${{ env.RELEASE_COMMIT }}

      - name: Restore sealed source code
        uses: ./.github/actions/download-artifact
        with:
          name: source-${{ env.SOURCE_INTEGRITY_HASH }}
          path: .

      - name: Install poetry
        run: pipx install git+https://github.com/python-poetry/poetry@68b88e5390720a3dd84f02940ec5200bfce39ac6 # v1.5.0
      - name: Set up Python
        uses: actions/setup-python@bd6b4b6205c4dbad673328db7b31b7fab9e241c0 # v4.6.1
        with:
          python-version: "3.10"
          cache: "poetry"

      - name: Build python package and wheel
        run: poetry build

      # NOTE: Ran out of time to create a composite action out of this
      # because GitHub Action inputs do not support arrays and it became fragile to join multiple strings then split
      # keeping these hard coded for now until we have a cleaner way to reuse files/dirs we want to hash
      - name: Source code tampering check
        run: test "${SOURCE_INTEGRITY_HASH}" = "${CURRENT_HASH}" || exit 1
        env:
          CURRENT_HASH: ${{ hashFiles('aws_lambda_powertools/**', 'pyproject.toml', 'poetry.lock', 'layer/**', '.github/**', 'docs/**', 'examples/**')}}

      - name: Create integrity hash for build artifact
        id: integrity
        run: echo "BUILD_INTEGRITY_HASH=${HASH}" >> "$GITHUB_OUTPUT"
        env:
          # paths to hash and why they're important to protect
          #
          # dist/  - package distribution build
          HASH: ${{ hashFiles('dist/**')}}

      - name: Upload build artifact
        uses: ./.github/actions/upload-artifact
        with:
          name: build-${{ steps.integrity.outputs.BUILD_INTEGRITY_HASH}}
          path: dist/

  # This job uses release artifact to publish to PyPi
  # it exchanges JWT tokens with GitHub to obtain PyPi credentials
  # since it's already registered as a Trusted Publisher.
  # It uses the sealed build artifact (.whl, .tar.gz) to release it
  release:
    needs: [build, seal]
    environment: release
    runs-on: ubuntu-latest
    permissions:
      id-token: write # OIDC for PyPi Trusted Publisher feature
    env:
      RELEASE_VERSION: ${{ needs.seal.outputs.RELEASE_VERSION }}
      BUILD_INTEGRITY_HASH: ${{ needs.build.outputs.BUILD_INTEGRITY_HASH }}
    steps:
      # NOTE: we need actions/checkout in order to use our local actions (e.g., ./.github/actions)
      - uses: actions/checkout@8e5e7e5ab8b370d6c329ec480221332ada57f0ab  # v3.5.2
        with:
          ref: ${{ env.RELEASE_COMMIT }}

      - name: Restore sealed build
        uses: ./.github/actions/download-artifact
        with:
          name: build-${{ env.BUILD_INTEGRITY_HASH }}
          path: .

      - name: Source code tampering check
        run: test "${BUILD_INTEGRITY_HASH}" = "${CURRENT_HASH}" || exit 1
        env:
          CURRENT_HASH: ${{ hashFiles('dist/**')}}

      - name: Upload to PyPi prod
        if: ${{ !inputs.skip_pypi }}
        uses: pypa/gh-action-pypi-publish@a56da0b891b3dc519c7ee3284aff1fad93cc8598 # v1.8.6

      # March 1st: PyPi test is under maintenance....
      # - name: Upload to PyPi test
      #   if: ${{ !inputs.skip_pypi }}
      #   uses: pypa/gh-action-pypi-publish@a56da0b891b3dc519c7ee3284aff1fad93cc8598 # v1.8.6
      #   with:
      #     repository-url: https://test.pypi.org/legacy/

  # We create a Git Tag using our release version (e.g., v2.16.0)
  # using our sealed source code we created earlier.
  # Because we bumped version of our project as part of CI
  # we need to add this into git before pushing the tag
  # otherwise the release commit will be used as the basis for the tag.
  # Later, we create a PR to update trunk with our newest release version (e.g., bump_version job)
  create_tag:
    needs: [release, seal]
    runs-on: ubuntu-latest
    permissions:
      contents: write
    env:
      SOURCE_INTEGRITY_HASH: ${{ needs.seal.outputs.SOURCE_CODE_HASH }}
    steps:
      # NOTE: we need actions/checkout to authenticate and configure git first
      - uses: actions/checkout@8e5e7e5ab8b370d6c329ec480221332ada57f0ab  # v3.5.2
        with:
          ref: ${{ env.RELEASE_COMMIT }}

      - name: Restore sealed source code
        uses: ./.github/actions/download-artifact
        with:
          name: source-${{ env.SOURCE_INTEGRITY_HASH }}
          path: .

      # NOTE: Ran out of time to create a composite action out of this
      # because GitHub Action inputs do not support arrays and it became fragile when making it reusable with strings
      # keeping these hard coded for now until we have a cleaner way to reuse files/dirs we want to hash
      - name: Source code tampering check
        run: test "${SOURCE_INTEGRITY_HASH}" = "${CURRENT_HASH}" || exit 1
        env:
          CURRENT_HASH: ${{ hashFiles('aws_lambda_powertools/**', 'pyproject.toml', 'poetry.lock', 'layer/**', '.github/**', 'docs/**', 'examples/**')}}

      - id: setup-git
        name: Git client setup and refresh tip
        run: |
          git config user.name "Powertools for AWS Lambda (Python) bot"
          git config user.email "aws-lambda-powertools-feedback@amazon.com"
          git config remote.origin.url >&-

      - name: Create Git Tag
        run: |
          git add pyproject.toml aws_lambda_powertools/shared/version.py
          git commit -m "chore: version bump"
          git tag -a v"${RELEASE_VERSION}" -m "release_version: v${RELEASE_VERSION}"
          git push origin v"${RELEASE_VERSION}"
        env:
          RELEASE_VERSION: ${{ needs.seal.outputs.RELEASE_VERSION }}

  # Creates a PR with the latest version we've just released
  # since our trunk is protected against any direct pushes from automation
  bump_version:
    needs: [release, seal]
    permissions:
      contents: write  # create-pr action creates a temporary branch
      pull-requests: write # create-pr action creates a PR using the temporary branch
    runs-on: ubuntu-latest
    env:
      SOURCE_INTEGRITY_HASH: ${{ needs.seal.outputs.SOURCE_CODE_HASH }}
    steps:
      # NOTE: we need actions/checkout to authenticate and configure git first
      - uses: actions/checkout@8e5e7e5ab8b370d6c329ec480221332ada57f0ab  # v3.5.2
        with:
          ref: ${{ env.RELEASE_COMMIT }}

      - name: Restore sealed source code
        uses: ./.github/actions/download-artifact
        with:
          name: source-${{ env.SOURCE_INTEGRITY_HASH }}
          path: .

      # NOTE: Ran out of time to create a composite action out of this
      # because GitHub Action inputs do not support arrays and it became fragile when making it reusable with strings
      # keeping these hard coded for now until we have a cleaner way to reuse files/dirs we want to hash
      - name: Source code tampering check
        run: test "${SOURCE_INTEGRITY_HASH}" = "${CURRENT_HASH}" || exit 1
        env:
          CURRENT_HASH: ${{ hashFiles('aws_lambda_powertools/**', 'pyproject.toml', 'poetry.lock', 'layer/**', '.github/**', 'docs/**', 'examples/**')}}

      - name: Create PR
        id: create-pr
        uses: ./.github/actions/create-pr
        with:
          files: "pyproject.toml aws_lambda_powertools/shared/version.py"
          temp_branch_prefix: "ci-bump"
          pull_request_title: "chore(ci): bump version to ${{ needs.seal.outputs.RELEASE_VERSION }}"
          github_token: ${{ secrets.GITHUB_TOKEN }}

  # This job compiles a Lambda Layer optimized for space and speed (e.g., Cython)
  # It then deploys to Layer's Beta and Prod account, including SAR Beta and Prod account.
  # It uses canaries to attest Layers can be used and imported between stages.
  # Lastly, it updates our documentation with the latest Layer ARN for all regions
  #
  # NOTE
  #
  # Watch out for the depth limit of 4 nested workflow_calls.
  # publish_layer -> publish_v2_layer -> reusable_deploy_v2_layer_stack
  publish_layer:
    needs: [seal, release, create_tag]
    secrets: inherit
    permissions:
      id-token: write
      contents: write
      pages: write
      pull-requests: write
    uses: ./.github/workflows/publish_v2_layer.yml
    with:
      latest_published_version: ${{ needs.seal.outputs.RELEASE_VERSION }}
      pre_release: ${{ inputs.pre_release }}

  post_release:
    needs: [seal, release, publish_layer]
    permissions:
      contents: read
      issues: write
      discussions: write
      pull-requests: write
    runs-on: ubuntu-latest
    env:
      RELEASE_VERSION: ${{ needs.seal.outputs.RELEASE_VERSION }}
    steps:
      - uses: actions/checkout@8e5e7e5ab8b370d6c329ec480221332ada57f0ab  # v3.5.2
        with:
          ref: ${{ env.RELEASE_COMMIT }}
      - name: Close issues related to this release
        uses: actions/github-script@d7906e4ad0b1822421a7e6a35d5ca353c962f410 # v6.4.1
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          script: |
            const post_release = require('.github/scripts/post_release.js')
            await post_release({github, context, core})