release.yml

name: Release

on:
  workflow_call:
    inputs:
      prepare-command:
        type: string
        default: ""
        description: Bash command that updates files before the release. Pixi is on PATH. Empty skips the prepare stage.
      release-branch:
        type: string
        default: ""
        description: Branch that gets the prepare commit. Its tip must be the tag commit. Empty means the default branch.
      prepare-commit-message:
        type: string
        default: ""
        description: "Commit message of the prepare commit. Empty means `[github-actions.ci] prepare release <tag>`."
      test:
        type: boolean
        default: true
        description: Run test.yml before the build.
      test-inputs:
        type: string
        default: "{}"
        description: JSON object with test.yml inputs (string values for string inputs, true/false for boolean inputs).
      build:
        type: boolean
        default: true
        description: Build and verify the sdist and wheel (artifact Packages-release). Set false for repos without a Python package.
      pypi:
        type: boolean
        default: true
        description: Publish to PyPI. Needs build.
      testpypi:
        type: boolean
        default: false
        description: Publish to TestPyPI and run a smoke check before the GitHub release and PyPI.
      smoke-command:
        type: string
        default: ""
        description: Command for the TestPyPI smoke check. Empty means `python -c "import <top-level module>"`.
      tag:
        type: string
        default: ""
        description: Release tag. Empty means the ref name of the trigger.
      release-notes-file:
        type: string
        default: ""
        description: File with the release body. Empty means generated release notes.
      release-notes-url:
        type: string
        default: ""
        description: URL put in a line above the release body.
      github-release:
        type: boolean
        default: true
        description: Create the GitHub release.
      dry-run:
        type: boolean
        default: false
        description: Build and verify only. Skip the TestPyPI upload, the GitHub release and PyPI.
      working-directory:
        type: string
        default: .
        description: Directory of the package, relative to the repo root.
    secrets:
      CDSAPI_KEY:
        required: false
      EARTHDATAHUB_API_KEY:
        required: false
      MOSEKLM_LICENSE_FILE:
        required: false
      GUROBI_LIC:
        required: false
    outputs:
      ready:
        description: "`true` if all checks passed and the run is not a dry run. A caller-side publish job gates on it."
        value: ${{ jobs.ready.outputs.ready }}

permissions: {}

env:
  TAG: ${{ inputs.tag || github.ref_name }}

jobs:
  prepare:
    if: inputs.prepare-command != '' && !inputs.dry-run
    runs-on: ubuntu-latest
    environment: release
    permissions:
      contents: read
    outputs:
      prepared: ${{ steps.check.outputs.prepared }}
    steps:
      - uses: step-security/harden-runner@46b06cea07f9e64621fdf066ba77ac6915163d43 # v2.22.3
        with:
          egress-policy: audit
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0
          persist-credentials: false
      - id: check
        env:
          MESSAGE: ${{ inputs.prepare-commit-message }}
          BRANCH: ${{ inputs.release-branch || github.event.repository.default_branch }}
        run: |
          set -euo pipefail
          message="${MESSAGE:-[github-actions.ci] prepare release $TAG}"
          { echo "message<<EOF_MESSAGE"; echo "$message"; echo "EOF_MESSAGE"; } >> "$GITHUB_OUTPUT"
          if [ "$(git log -1 --pretty=%B)" = "$message" ]; then
            echo "prepared=true" >> "$GITHUB_OUTPUT"
            exit 0
          fi
          echo "prepared=false" >> "$GITHUB_OUTPUT"
          [ -n "$BRANCH" ] || { echo "::error::release branch unknown, set release-branch"; exit 1; }
          git rev-parse -q --verify "refs/remotes/origin/$BRANCH" > /dev/null || { echo "::error::branch $BRANCH not found"; exit 1; }
          git merge-base --is-ancestor HEAD "refs/remotes/origin/$BRANCH" || { echo "::error::branch $BRANCH does not contain $TAG"; exit 1; }
          echo "branch=$BRANCH" >> "$GITHUB_OUTPUT"
          echo "commit=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        if: steps.check.outputs.prepared == 'false'
        with:
          ref: ${{ steps.check.outputs.branch }}
          fetch-depth: 0
          persist-credentials: false
      - if: steps.check.outputs.prepared == 'false'
        env:
          BRANCH: ${{ steps.check.outputs.branch }}
          COMMIT: ${{ steps.check.outputs.commit }}
        run: |
          set -euo pipefail
          [ "$(git rev-parse HEAD)" = "$COMMIT" ] || { echo "::error::$BRANCH has commits after $TAG. Tag the tip of $BRANCH."; exit 1; }
      - uses: prefix-dev/setup-pixi@ad1da6449d9e506fd127fd67ab2d054a769f6a94 # v0.11.2
        if: steps.check.outputs.prepared == 'false'
        with:
          pixi-version: v0.81.0
          run-install: false
      - if: steps.check.outputs.prepared == 'false'
        working-directory: ${{ inputs.working-directory }}
        env:
          PREPARE_COMMAND: ${{ inputs.prepare-command }}
        run: bash -euo pipefail -c "$PREPARE_COMMAND"
      - uses: actions/create-github-app-token@64ab729a6294000f5aa4a4bc0b73d1f32bc45510 # v3.3.0
        id: token
        if: steps.check.outputs.prepared == 'false'
        with:
          app-id: ${{ vars.PYPSA_BOT_ID }}
          private-key: ${{ secrets.PYPSA_BOT_PRIVATE_KEY }}
          permission-contents: write
      - if: steps.check.outputs.prepared == 'false'
        env:
          GH_TOKEN: ${{ steps.token.outputs.token }}
          APP_SLUG: ${{ steps.token.outputs.app-slug }}
          MESSAGE: ${{ steps.check.outputs.message }}
          BRANCH: ${{ steps.check.outputs.branch }}
        run: |
          set -euo pipefail
          user_id=$(gh api "/users/${APP_SLUG}%5Bbot%5D" -q .id)
          git config user.name "${APP_SLUG}[bot]"
          git config user.email "${user_id}+${APP_SLUG}[bot]@users.noreply.github.com"
          git add -A
          git commit --allow-empty -m "$MESSAGE"
          git tag -f -a "$TAG" -m "$TAG"
          GIT_CONFIG_COUNT=1 \
            GIT_CONFIG_KEY_0="http.$GITHUB_SERVER_URL/.extraheader" \
            GIT_CONFIG_VALUE_0="AUTHORIZATION: basic $(printf 'x-access-token:%s' "$GH_TOKEN" | base64 -w0)" \
            git push --atomic origin "HEAD:refs/heads/$BRANCH" "+refs/tags/$TAG"
          echo "Pushed the prepare commit and moved $TAG. The new tag starts the release run." >> "$GITHUB_STEP_SUMMARY"

  test:
    needs: prepare
    if: always() && inputs.test && (needs.prepare.result == 'skipped' || needs.prepare.outputs.prepared == 'true')
    uses: $/.github/workflows/test.yml
    permissions:
      contents: read
      id-token: write
    secrets:
      CDSAPI_KEY: ${{ secrets.CDSAPI_KEY }}
      EARTHDATAHUB_API_KEY: ${{ secrets.EARTHDATAHUB_API_KEY }}
      MOSEKLM_LICENSE_FILE: ${{ secrets.MOSEKLM_LICENSE_FILE }}
      GUROBI_LIC: ${{ secrets.GUROBI_LIC }}
    with:
      extras: ${{ fromJSON(inputs.test-inputs).extras || 'dev' }}
      pixi-add: ${{ fromJSON(inputs.test-inputs).pixi-add || '' }}
      uv-locked: ${{ fromJSON(inputs.test-inputs).uv-locked == true }}
      cooldown: ${{ fromJSON(inputs.test-inputs).cooldown == null && '7d' || fromJSON(inputs.test-inputs).cooldown }}
      matrix: ${{ fromJSON(inputs.test-inputs).matrix || 'auto' }}
      python-versions: ${{ fromJSON(inputs.test-inputs).python-versions || '' }}
      os-full: ${{ fromJSON(inputs.test-inputs).os-full || '["ubuntu-latest","macos-latest","windows-latest"]' }}
      pytest-args: ${{ fromJSON(inputs.test-inputs).pytest-args || '' }}
      test-command: ${{ fromJSON(inputs.test-inputs).test-command || '' }}
      pixi-task: ${{ fromJSON(inputs.test-inputs).pixi-task || '' }}
      pixi-environments: ${{ fromJSON(inputs.test-inputs).pixi-environments || '["default"]' }}
      manifest-path: ${{ fromJSON(inputs.test-inputs).manifest-path || '' }}
      pixi-version: ${{ fromJSON(inputs.test-inputs).pixi-version || 'v0.81.0' }}
      cache-path: ${{ fromJSON(inputs.test-inputs).cache-path || '' }}
      cache-key: ${{ fromJSON(inputs.test-inputs).cache-key || '' }}
      cov-source: ${{ fromJSON(inputs.test-inputs).cov-source || '' }}
      artifact-suffix: -release-test
      coverage: ${{ fromJSON(inputs.test-inputs).coverage == true }}
      coverage-file: ${{ fromJSON(inputs.test-inputs).coverage-file || 'coverage.xml' }}
      vars-env: ${{ fromJSON(inputs.test-inputs).vars-env || '' }}
      working-directory: ${{ fromJSON(inputs.test-inputs).working-directory || inputs.working-directory }}

  build:
    needs: [prepare, test]
    if: >-
      always() && inputs.build
      && (needs.prepare.result == 'skipped' || needs.prepare.outputs.prepared == 'true')
      && (needs.test.result == 'success' || (!inputs.test && needs.test.result == 'skipped'))
    runs-on: ubuntu-latest
    permissions:
      contents: read
    outputs:
      dist-name: ${{ steps.baipp.outputs.package_name }}
      version: ${{ steps.verify.outputs.version }}
      import-name: ${{ steps.verify.outputs.import-name }}
      python-version: ${{ steps.verify.outputs.python-version }}
    steps:
      - uses: step-security/harden-runner@46b06cea07f9e64621fdf066ba77ac6915163d43 # v2.22.3
        with:
          egress-policy: audit
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0
          persist-credentials: false
      - env:
          DRY_RUN: ${{ inputs.dry-run }}
        run: |
          set -euo pipefail
          if git rev-parse -q --verify "refs/tags/$TAG" > /dev/null; then
            git checkout -q "refs/tags/$TAG"
          elif [ "$DRY_RUN" = true ]; then
            git tag "$TAG"
          else
            echo "::error::tag $TAG not found"
            exit 1
          fi
      - uses: hynek/build-and-inspect-python-package@67230f7b8410ae0052b39c1efc89d89fff43ff10 # v3.0.2
        id: baipp
        with:
          path: ${{ inputs.working-directory }}
          upload-name-suffix: -release
      - id: verify
        env:
          DIST: ${{ steps.baipp.outputs.dist }}
          PYTHONS: ${{ steps.baipp.outputs.supported_python_classifiers_json_array }}
        run: |
          set -euo pipefail
          wheel=$(ls "$DIST"/*.whl)
          version=$(basename "$wheel" | cut -d- -f2)
          [ "$version" = "${TAG#v}" ] || { echo "::error::wheel version $version does not match tag $TAG"; exit 1; }
          import_name=$(unzip -Z1 "$wheel" | cut -d/ -f1 | sed 's/\.py$//' | grep -E '^[A-Za-z_][A-Za-z0-9_]*$' | sort -u | head -n 1)
          {
            echo "version=$version"
            echo "import-name=$import_name"
            echo "python-version=$(jq -r '.[-1] // empty' <<< "${PYTHONS:-[]}")"
          } >> "$GITHUB_OUTPUT"

  testpypi:
    needs: build
    if: always() && needs.build.result == 'success' && inputs.testpypi && !inputs.dry-run
    runs-on: ubuntu-latest
    environment:
      name: testpypi
      url: https://test.pypi.org/project/${{ needs.build.outputs.dist-name }}/${{ needs.build.outputs.version }}
    permissions:
      id-token: write
    steps:
      - uses: step-security/harden-runner@46b06cea07f9e64621fdf066ba77ac6915163d43 # v2.22.3
        with:
          egress-policy: audit
      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
        with:
          name: Packages-release
          path: dist
      - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3
        with:
          repository-url: https://test.pypi.org/legacy/
          skip-existing: true

  smoke:
    needs: [build, testpypi]
    if: always() && needs.testpypi.result == 'success'
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: step-security/harden-runner@46b06cea07f9e64621fdf066ba77ac6915163d43 # v2.22.3
        with:
          egress-policy: audit
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
        with:
          name: Packages-release
          path: ${{ runner.temp }}/wheels
      - uses: $/.github/actions/setup-env
        with:
          mode: library
          python-version: ${{ needs.build.outputs.python-version }}
          extras: ""
          wheel-dir: ${{ runner.temp }}/wheels
          working-directory: ${{ inputs.working-directory }}
      - env:
          DIST_NAME: ${{ needs.build.outputs.dist-name }}
          VERSION: ${{ needs.build.outputs.version }}
        run: |
          set -euo pipefail
          deadline=$((SECONDS + 300))
          until $RUN uv pip install --no-cache --no-deps --reinstall-package "$DIST_NAME" \
            --index-url https://test.pypi.org/simple/ "$DIST_NAME==$VERSION"; do
            [ "$SECONDS" -lt "$deadline" ] || { echo "::error::$DIST_NAME==$VERSION not installable from TestPyPI after 5 minutes"; exit 1; }
            sleep 20
          done
      - env:
          SMOKE_COMMAND: ${{ inputs.smoke-command }}
          IMPORT_NAME: ${{ needs.build.outputs.import-name }}
        run: |
          set -euo pipefail
          cd "$RUNNER_TEMP"
          $RUN bash -euo pipefail -c "${SMOKE_COMMAND:-python -c \"import $IMPORT_NAME\"}"

  ready:
    needs: [prepare, test, build, testpypi, smoke]
    if: always()
    runs-on: ubuntu-latest
    permissions: {}
    outputs:
      ready: ${{ steps.ready.outputs.ready }}
    steps:
      - uses: step-security/harden-runner@46b06cea07f9e64621fdf066ba77ac6915163d43 # v2.22.3
        with:
          egress-policy: audit
      - id: ready
        env:
          READY: >-
            ${{
              !inputs.dry-run
              && (needs.prepare.result == 'skipped' || needs.prepare.outputs.prepared == 'true')
              && (needs.test.result == 'success' || (!inputs.test && needs.test.result == 'skipped'))
              && (needs.build.result == 'success' || (!inputs.build && needs.build.result == 'skipped'))
              && (needs.smoke.result == 'success' || (!inputs.testpypi && needs.smoke.result == 'skipped'))
            }}
        run: echo "ready=$READY" >> "$GITHUB_OUTPUT"

  github-release:
    needs: ready
    if: always() && needs.ready.outputs.ready == 'true' && inputs.github-release
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: step-security/harden-runner@46b06cea07f9e64621fdf066ba77ac6915163d43 # v2.22.3
        with:
          egress-policy: audit
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        if: inputs.release-notes-file != ''
        with:
          ref: ${{ env.TAG }}
          persist-credentials: false
      - env:
          GH_TOKEN: ${{ github.token }}
          NOTES_FILE: ${{ inputs.release-notes-file }}
          NOTES_URL: ${{ inputs.release-notes-url }}
        run: |
          set -euo pipefail
          body="$RUNNER_TEMP/release-notes.md"
          : > "$body"
          if [ -n "$NOTES_URL" ]; then printf 'Release notes: %s\n\n' "$NOTES_URL" >> "$body"; fi
          args=(--repo "$GITHUB_REPOSITORY" --verify-tag --notes-file "$body")
          if [ -n "$NOTES_FILE" ]; then cat "$NOTES_FILE" >> "$body"; else args+=(--generate-notes); fi
          if [[ "${TAG#v}" =~ [0-9](a|b|rc)[0-9]*$ ]]; then args+=(--prerelease); fi
          gh release create "$TAG" "${args[@]}"

  publish:
    needs: [build, ready, github-release]
    if: >-
      always() && needs.ready.outputs.ready == 'true' && inputs.pypi
      && (needs.github-release.result == 'success' || needs.github-release.result == 'skipped')
    runs-on: ubuntu-latest
    environment:
      name: pypi
      url: https://pypi.org/project/${{ needs.build.outputs.dist-name }}/${{ needs.build.outputs.version }}
    permissions:
      id-token: write
    steps:
      - uses: step-security/harden-runner@46b06cea07f9e64621fdf066ba77ac6915163d43 # v2.22.3
        with:
          egress-policy: audit
      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
        with:
          name: Packages-release
          path: dist
      - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3