register.yml

# Register: once a release merges into the main branch, comment `@JuliaRegistrator register` on its commit, with its section of the changelog as the release notes, so that the registry registers it; TagBot then tags it.
# Called from the repository's own workflow, under gitflow and trunk on pushes to the main branch, and under OneFlow by hand on the release branch, which OneFlow registers before merging it back:
#
#   on:
#     push:
#       branches: [main]
#   jobs:
#     register:
#       uses: BioJulia/Workflows/.github/workflows/register.yml@v1
#       permissions:
#         contents: write
#
# A commit whose version the registry already records, or that changes no version, has nothing to register, so the workflow does nothing.
# Registrator acts on comments from collaborators and members of the repository's organization, which an app's bot isn't, and from github-actions[bot], so the comment takes the workflow's GITHUB_TOKEN, with the permission contents: write that the caller grants.
# REGISTRATOR_TOKEN, a token of an account with write access, takes its place where it's given.
# A package's first release is registered by hand, which the workflow's warning says how to do.
# TagBot tags the release once the registry merges it.
# The register job, which comments, runs in the deployment environment `environment`, `releaseflow` unless given, which keeps REGISTRATOR_TOKEN where it's given.
name: "Reusable: Register"

on:
  workflow_call:
    inputs:
      project:
        description: The package's directory, relative to the repository's root, for a package in a subdirectory, which the comment names as `subdir`.
        type: string
        default: ''
      registry:
        description: The registry of the package's releases.
        type: string
        default: General
      local-action:
        description: Whether to run the action from the checked-out commit instead of its release, for BioJulia/Workflows' own releases, which may be the first to have a check that they call.
        type: boolean
        default: false
      environment:
        description: The deployment environment of the register job, which holds REGISTRATOR_TOKEN where it's given.
        type: string
        default: releaseflow
    secrets:
      REGISTRATOR_TOKEN:
        description: A personal access token of an account with write access, which comments in place of the workflow's GITHUB_TOKEN.
        required: false

# Each job states its permissions but the register job, which takes the caller's: a called job that asks for more than its caller grants doesn't start.

jobs:
  # GitHub resolves every action of a job before it runs, even one whose step is skipped, and a release's own tag only exists once it's registered.
  # So the action runs in one of two jobs: at the release that this workflow belongs to, or, with `local-action`, at the checked-out commit.
  # The register job, which runs none of this repository's actions, comments with the caller's permissions.
  registration:
    name: Registration
    if: ${{ !inputs.local-action }}
    runs-on: ubuntu-latest
    permissions:
      contents: read
    outputs:
      register: ${{ steps.registration.outputs.register }}
      version: ${{ steps.registration.outputs.version }}
      notes: ${{ steps.registration.outputs.notes }}
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0
      - id: registration
        uses: BioJulia/Workflows@v1.3.1
        with:
          check: registration
          project: ${{ inputs.project }}
          registry: ${{ inputs.registry }}

  registration-local:
    name: Registration
    if: ${{ inputs.local-action }}
    runs-on: ubuntu-latest
    permissions:
      contents: read
    outputs:
      register: ${{ steps.registration-local.outputs.register }}
      version: ${{ steps.registration-local.outputs.version }}
      notes: ${{ steps.registration-local.outputs.notes }}
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0
      - id: registration-local
        uses: ./
        with:
          check: registration
          project: ${{ inputs.project }}
          registry: ${{ inputs.registry }}

  register:
    name: Register
    needs: [registration, registration-local]
    if: ${{ !cancelled() && (needs.registration.outputs.register == 'true' || needs.registration-local.outputs.register == 'true') }}
    runs-on: ubuntu-latest
    environment: ${{ inputs.environment }}
    steps:
      - name: Comment for Registrator
        env:
          GH_TOKEN: ${{ secrets.REGISTRATOR_TOKEN }}
          WORKFLOW_TOKEN: ${{ github.token }}
          REPOSITORY: ${{ github.repository }}
          SHA: ${{ github.sha }}
          RELEASEFLOW_PROJECT: ${{ inputs.project }}
          VERSION: ${{ needs.registration.outputs.version || needs.registration-local.outputs.version }}
          NOTES: ${{ needs.registration.outputs.notes || needs.registration-local.outputs.notes }}
        run: |
          set -euo pipefail
          # REGISTRATOR_TOKEN comments where it's given, and the workflow's GITHUB_TOKEN otherwise.
          if [ -n "$GH_TOKEN" ]; then
            token=REGISTRATOR_TOKEN
          elif [ -n "${WORKFLOW_TOKEN:-}" ]; then
            token=GITHUB_TOKEN
            export GH_TOKEN="$WORKFLOW_TOKEN"
          else
            echo "::error title=Register::Registering $VERSION needs REGISTRATOR_TOKEN or the workflow's GITHUB_TOKEN, and the step was given neither."
            exit 1
          fi
          command="@JuliaRegistrator register${RELEASEFLOW_PROJECT:+ subdir=${RELEASEFLOW_PROJECT%/}}"
          body="$command"
          if [ -n "$NOTES" ]; then
            body="$body

          Release notes:

          $NOTES"
          fi
          # Where the comment can't be made, what the token needs, and the comment to make by hand meanwhile.
          fail() {
            if [ "$token" = GITHUB_TOKEN ]; then
              needs="Commenting on a commit needs the permission contents: write, which the caller's job that uses register.yml grants."
            else
              needs="REGISTRATOR_TOKEN must be a token of an account with write access to $REPOSITORY, with the repository permission Contents: Read and write; without it, the workflow comments with GITHUB_TOKEN, as github-actions[bot], whose comments Registrator acts on."
            fi
            echo "::error title=Register::$1 $needs Meanwhile, comment \`$command\` on $SHA by hand; see the job summary."
            {
              echo "## Register $VERSION"
              echo
              echo "$1 $needs"
              echo
              echo "Comment on $SHA by hand, with the release notes:"
              echo
              echo "\`\`\`"
              echo "$body"
              echo "\`\`\`"
            } >> "$GITHUB_STEP_SUMMARY"
            exit 1
          }
          errors=$(mktemp)
          gh api "repos/$REPOSITORY/commits/$SHA/comments" -f body="$body" --jq .html_url 2> "$errors" || fail "$token couldn't comment on $SHA, for $VERSION: $(tr '\n' ' ' < "$errors")"
          echo "Commented \`$command\` on $SHA, for $VERSION."