github-release.yml

# **what?**
# Create a new release on GitHub and include any artifacts in the `/dist` directory of the GitHub artifacts store.
#
# Inputs:
#  sha:            The commit to attach to this release
#  version_number: The release version number (i.e. 1.0.0b1, 1.2.3rc2, 1.0.0)
#  changelog_path: Path to the changelog file for release notes
#  test_run:       Test run (Publish release as draft)
#
# **why?**
# Reusable and consistent GitHub release process.
#
# **when?**
# Call after a successful build.  Build artifacts should be ready to release and live in a dist/ directory.
#
# This workflow expects the artifacts to already be built and living in the artifact store of the workflow.
#
# Validation Checks
#
# 1. If no release already exists for this commit and version, create the tag and release it to GitHub.
# 2. If a release already exists for this commit, skip creating the release but finish with a success.
# 3. If a release exists for this commit under a different tag, fail.
# 4. If the commit is already associated with a different release, fail.

name: GitHub Release

on:
  workflow_call:
    inputs:
      sha:
        description: The commit to attach to this release
        required: true
        type: string
      version_number:
        description: The release version number (i.e. 1.0.0b1)
        required: true
        type: string
      changelog_path:
        description: Path to the changelog file for release notes
        required: true
        type: string
      test_run:
        description: Test run (Publish release as draft)
        required: true
        type: boolean
      archive_name:
        description: artifact name to download
        required: true
        type: string
    outputs:
      tag:
        description: The path to the changelog for this version
        value: ${{ jobs.check-release-exists.outputs.tag }}

permissions:
  contents: write

env:
  REPO_LINK: ${{ github.server_url }}/${{ github.repository }}
  NOTIFICATION_PREFIX: "[GitHub Release]"

jobs:
  log-inputs:
    runs-on: ubuntu-latest
    steps:
      - name: "[DEBUG] Print Variables"
        run: |
          echo The last commit sha in the release: ${{ inputs.sha }}
          echo The release version number:         ${{ inputs.version_number }}
          echo Expected Changelog path:            ${{ inputs.changelog_path }}
          echo Test run:                           ${{ inputs.test_run }}
          echo Repo link:                          ${{ env.REPO_LINK }}
          echo Notification prefix:                ${{ env.NOTIFICATION_PREFIX }}

  check-release-exists:
    runs-on: ubuntu-latest
    outputs:
      exists: ${{ steps.release_check.outputs.exists }}
      draft_exists: ${{ steps.release_check.outputs.draft_exists }}
      tag: ${{ steps.set_tag.outputs.tag }}

    steps:
      - name: "Generate Release Tag"
        id: set_tag
        run: echo "tag=v${{ inputs.version_number }}" >> $GITHUB_OUTPUT

      # When the GitHub CLI doesn't find a release for the given tag, it will exit 1 with a
      # message of "release not found".  In our case, it's not an actual error, just a
      # confirmation that the release does not already exists so we can go ahead and create it.
      # The `|| true` makes it so the step does not exit with a non-zero exit code
      # Also check if the release already exists is draft state.  If it does, and we are not
      # testing then we can publish that draft as is.  If it's in draft and we are testing, skip the
      # release.
      - name: "Check If Release Exists For Tag ${{ steps.set_tag.outputs.tag }}"
        id: release_check
        run: |
          output=$((gh release view ${{ steps.set_tag.outputs.tag }} --json isDraft,targetCommitish --repo ${{ env.REPO_LINK }}) 2>&1) || true
          if [[ "$output" == "release not found" ]]
          then
            title="Release for tag ${{ steps.set_tag.outputs.tag }} does not exist."
            message="Check passed."
            echo "exists=false" >> $GITHUB_OUTPUT
            echo "draft_exists=false" >> $GITHUB_OUTPUT
            echo "::notice title=${{ env.NOTIFICATION_PREFIX }}: $title::$message"
            exit 0
          fi
          commit=$(jq -r '.targetCommitish' <<< "$output")
          if [[ $commit != ${{ inputs.sha }} ]]
          then
            title="Release for tag ${{ steps.set_tag.outputs.tag }} already exists for commit $commit!"
            message="Cannot create a new release for commit ${{ inputs.sha }}. Exiting."
            echo "::error title=${{ env.NOTIFICATION_PREFIX }}: $title::$message"
            exit 1
          fi
          isDraft=$(jq -r '.isDraft' <<< "$output")
          if [[ $isDraft == true ]] && [[ ${{ inputs.test_run }} == false ]]
          then
            title="Release tag ${{ steps.set_tag.outputs.tag }} already associated with the draft release."
            message="Release workflow will publish the associated release."
            echo "exists=false" >> $GITHUB_OUTPUT
            echo "draft_exists=true" >> $GITHUB_OUTPUT
            echo "::notice title=${{ env.NOTIFICATION_PREFIX }}: $title::$message"
            exit 0
          fi
          title="Release for tag ${{ steps.set_tag.outputs.tag }} already exists."
          message="Skip GitHub Release Publishing."
          echo "exists=true" >> $GITHUB_OUTPUT
          echo "draft_exists=false" >> $GITHUB_OUTPUT
          echo "::notice title=${{ env.NOTIFICATION_PREFIX }}: $title::$message"
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          REPO: ${{ env.REPO_LINK }}

      - name: "[DEBUG] Log Job Outputs"
        run: |
          echo exists:       ${{ steps.release_check.outputs.exists }}
          echo draft_exists: ${{ steps.release_check.outputs.draft_exists }}
          echo tag:          ${{ steps.set_tag.outputs.tag }}

  skip-github-release:
    runs-on: ubuntu-latest
    needs: [check-release-exists]
    if: needs.check-release-exists.outputs.exists == 'true'

    steps:
      - name: "Tag Exists, Skip GitHub Release Job"
        run: |
          echo title="A tag already exists for ${{ needs.check-release-exists.outputs.tag }} and commit."
          echo message="Skipping GitHub release."
          echo "::notice title=${{ env.NOTIFICATION_PREFIX }}: $title::$message"

  audit-release-different-commit:
    runs-on: ubuntu-latest
    needs: [check-release-exists]
    if: needs.check-release-exists.outputs.exists == 'false'

    steps:
      - name: "Check If Release Already Exists For Commit"
        uses: cardinalby/git-get-release-action@1.2.4
        id: check_release_commit
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          commitSha: ${{ inputs.sha }}
          doNotFailIfNotFound: true # returns blank outputs when not found instead of error
          searchLimit: 15 # Since we only care about recent releases, speed up the process

      - name: "[DEBUG] Print Release Details"
        run: |
          echo steps.check_release_commit.outputs.id:               ${{ steps.check_release_commit.outputs.id }}
          echo steps.check_release_commit.outputs.tag_name:         ${{ steps.check_release_commit.outputs.tag_name }}
          echo steps.check_release_commit.outputs.target_commitish: ${{ steps.check_release_commit.outputs.target_commitish }}
          echo steps.check_release_commit.outputs.prerelease:       ${{ steps.check_release_commit.outputs.prerelease }}

      # Since we already know a release for this tag does not exist, if we find anything it's for the wrong tag, exit
      - name: "Check If The Tag Matches The Version Number"
        if: steps.check_release_commit.outputs.id != ''
        run: |
          title="Tag ${{ steps.check_release_commit.outputs.tag_name }} already exists for this commit!"
          message="Cannot create a new tag for ${{ needs.check-release-exists.outputs.tag }} for the same commit"
          echo "::error title=${{ env.NOTIFICATION_PREFIX }}: $title::$message"
          exit 1

  publish-draft-release:
    runs-on: ubuntu-latest
    needs: [check-release-exists, audit-release-different-commit]
    if: >-
      needs.check-release-exists.outputs.draft_exists == 'true' &&
      inputs.test_run  == false

    steps:
      - name: "Publish Draft Release - ${{ needs.check-release-exists.outputs.tag }}"
        run: |
          gh release edit $TAG --draft=false --repo ${{ env.REPO_LINK }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          TAG: ${{ needs.check-release-exists.outputs.tag }}

  create-github-release:
    runs-on: ubuntu-latest
    needs: [check-release-exists, audit-release-different-commit]
    if: needs.check-release-exists.outputs.draft_exists == 'false'

    steps:
      - name: "Check out repository"
        uses: actions/checkout@v4
        with:
          ref: ${{ inputs.sha }}

      - name: "Download Artifact ${{ inputs.archive_name }}"
        uses: actions/download-artifact@v4
        with:
          name: ${{ inputs.archive_name }}
          path: dist/

      - name: "[DEBUG] Display Structure Of Expected Files"
        run: |
          ls -R .changes
          ls -l dist

      - name: "Set Release Type"
        id: release_type
        run: |
          if ${{ contains(inputs.version_number, 'rc') ||  contains(inputs.version_number, 'b') }}
          then
            echo Release will be set as pre-release
            echo "prerelease=--prerelease" >> $GITHUB_OUTPUT
          else
            echo This is not a prerelease
          fi

      - name: "Set As Draft Release"
        id: draft
        run: |
          if [[ ${{ inputs.test_run }} == true ]]
          then
            echo Release will be published as draft
            echo "draft=--draft" >> $GITHUB_OUTPUT
          else
            echo This is not a draft release
          fi

      - name: "GitHub Release Workflow Annotation"
        run: |
          title="Release ${{ needs.check-release-exists.outputs.tag }}"
          message="Configuration: ${{ steps.release_type.outputs.prerelease }} ${{ steps.draft.outputs.draft }}"
          echo "::notice title=${{ env.NOTIFICATION_PREFIX }}: $title::$message"

      - name: "Create New GitHub Release - ${{ needs.check-release-exists.outputs.tag }}"
        run: |
          gh release create $TAG ./dist/* --title "$TITLE" --notes-file $RELEASE_NOTES --target $COMMIT $PRERELEASE $DRAFT --repo ${{ env.REPO_LINK }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          TAG: ${{ needs.check-release-exists.outputs.tag }}
          TITLE: ${{ github.event.repository.name }} ${{ needs.check-release-exists.outputs.tag }}
          RELEASE_NOTES: ${{ inputs.changelog_path }}
          COMMIT: ${{ inputs.sha }}
          PRERELEASE: ${{ steps.release_type.outputs.prerelease }}
          DRAFT: ${{ steps.draft.outputs.draft }}