update_software_layer_scripts_commit.yml

# documentation: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions
#
# Keeps bot/software_layer_scripts_commit in software-layer/main in sync with the latest
# commit on main of EESSI/software-layer-scripts.
#
# Triggers:
#   - schedule (hourly): safety net; needs no credentials beyond the ephemeral GITHUB_TOKEN.
#   - workflow_dispatch: manual runs, and remote triggering from EESSI/software-layer-scripts
#     (see EESSI/.github/workflows/dispatch_software_layer_update.yml) via the workflow_dispatch API,
#     using a fine-grained PAT with only "Actions: read & write" on this repo.
#
# Behavior:
#   - Only acts when the stored SHA differs from the latest commit on software-layer-scripts main.
#   - If it differs, but the bot branch 'gh_action_update_software_layer_commit_sha' already pins that
#     same latest SHA (i.e. an open PR is already proposing it), does nothing: no pointless force-push,
#     no PR re-creation/comment, until that PR is merged (or the upstream SHA moves again).
#   - Recreates branch 'gh_action_update_software_layer_commit_sha' from software-layer's latest main and force-pushes it,
#     so the PR never accumulates merge conflicts and the existing PR (if any) is updated in place.
#     The force push is safe: the branch is bot-owned and fully regenerated on every run.
#   - A PR is created only if none exists for the branch; on later updates a comment posts the new SHA.
#
# Permissions:
#   - contents: write       -> push to gh_action_update_software_layer_commit_sha
#   - pull-requests: write  -> create PR / comment on it
#   main is branch-protected, so this token cannot touch main.
#
# Caveat: the pinned SHA is the raw tip of software-layer-scripts main. The check in
# test_software_layer_scripts.yml additionally requires the commit to be web-flow signed;
# if someone ever pushes directly to software-layer-scripts main (not via PR), the bot PR
# may fail that check until the next PR merge arrives. That should never happen because that branch
# is protected though.
name: Update bot/software_layer_scripts_commit
on:
  schedule:
    - cron: '0 * * * *'   # hourly safety net
  workflow_dispatch: {}   # manual, or via API from software-layer-scripts
permissions:
  contents: write  # Needs to create a feature branch and push to it
  pull-requests: write  # Needs to create a PR, add comments on updates, etc
concurrency:  # Prevent simultaneous runs from cron and workflow_dispatch
  group: update-software-layer-scripts-commit
  cancel-in-progress: true  # Older run is cancelled, makes sure we get the most up-to-date SHA
jobs:
  update:
    runs-on: ubuntu-24.04
    steps:
      - name: Check out software-layer (shallow)
        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1

      - name: Get latest commit on main of EESSI/software-layer-scripts
        id: latest
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          SHA=$(gh api repos/EESSI/software-layer-scripts/commits/main --jq .sha)
          echo "sha=$SHA" >> "$GITHUB_OUTPUT"

      - name: Compare with stored SHA and pending bot branch
        id: cmp
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          STORED=$(tr -d '[:space:]' < bot/software_layer_scripts_commit)
          LATEST="${{ steps.latest.outputs.sha }}"

          if [[ "$STORED" == "$LATEST" ]]; then
            echo "changed=false" >> "$GITHUB_OUTPUT"
            echo "Already up to date on main: $STORED"
            exit 0
          fi

          # main is behind latest, but an open PR from a previous run may already pin it.
          BRANCH_SHA=""
          if CONTENT=$(gh api "repos/${{ github.repository }}/contents/bot/software_layer_scripts_commit?ref=gh_action_update_software_layer_commit_sha" \
                          --jq .content 2>/dev/null); then
            BRANCH_SHA=$(printf '%s' "$CONTENT" | base64 -d | tr -d '[:space:]')
          fi

          if [[ "$BRANCH_SHA" == "$LATEST" ]]; then
            echo "changed=false" >> "$GITHUB_OUTPUT"
            echo "Bot branch gh_action_update_software_layer_commit_sha already pins $LATEST; PR pending merge, nothing to do."
          else
            echo "changed=true" >> "$GITHUB_OUTPUT"
            echo "Stored on main:  $STORED"
            echo "Bot branch has:  ${BRANCH_SHA:-<none>}"
            echo "Latest:          $LATEST"
          fi

      - name: Update file and force-push gh_action_update_software_layer_commit_sha
        if: steps.cmp.outputs.changed == 'true'
        run: |
          git checkout -B gh_action_update_software_layer_commit_sha origin/main
          printf '%s\n' "${{ steps.latest.outputs.sha }}" > bot/software_layer_scripts_commit
          git -c user.name='github-actions[bot]' \
              -c user.email='41898282+github-actions[bot]@users.noreply.github.com' \
              commit -am "Update bot/software_layer_scripts_commit to ${{ steps.latest.outputs.sha }}"
          git push --force origin gh_action_update_software_layer_commit_sha

      - name: Create PR, or comment with the new SHA
        if: steps.cmp.outputs.changed == 'true'
        env:
          GH_TOKEN: ${{ github.token }}
          PR_BODY: |
            This PR is auto-generated by the
            [`update_software_layer_scripts_commit` workflow](https://github.com/EESSI/software-layer/actions/workflows/update_software_layer_scripts_commit.yml)
            ([workflow source](https://github.com/EESSI/software-layer/blob/main/.github/workflows/update_software_layer_scripts_commit.yml)).

            It pins `bot/software_layer_scripts_commit` to `${{ steps.latest.outputs.sha }}`,
            the current tip of [`EESSI/software-layer-scripts`](https://github.com/EESSI/software-layer-scripts) `main`.

            If `bot/software_layer_scripts_commit` in this PR looks outdated, **DO NOT push updates to this branch manually**.
            The bot keeps it up to date automatically; you can also rerun the workflow manually from
            [the workflow page](https://github.com/EESSI/software-layer/actions/workflows/update_software_layer_scripts_commit.yml).
        run: |
          NEW_SHA="${{ steps.latest.outputs.sha }}"
          PR_URL=$(gh pr list --head gh_action_update_software_layer_commit_sha --state open --json url --jq '.[0].url')
          if [[ -n "$PR_URL" ]]; then
            echo "PR already exists: $PR_URL"
            gh pr comment "$PR_URL" --body \
              "Updated \`bot/software_layer_scripts_commit\` to \`$NEW_SHA\` (commit \`$(git rev-parse HEAD)\`)."
          else
            gh pr create --base main --head gh_action_update_software_layer_commit_sha \
              --title "Update bot/software_layer_scripts_commit" \
              --body "$PR_BODY"
          fi