From b55b6d953d6c58a52fb5b391b111db32c187b25e Mon Sep 17 00:00:00 2001
From: Tsvika Shapira <tsvikas@gmail.com>
Date: Mon, 26 Oct 2026 22:23:42 +0200
Subject: [PATCH] ci: link the opened PR, and explain the PR-permission failure

When create-pull-request fails, add an error annotation that links to the
repo's Actions settings and says which checkbox to enable, since GitHub's
error only links to the REST docs. When it creates or updates a PR, add a
notice with the PR link.

Applies to the generated deps-update workflow and to update-template-pins.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/update-template-pins.yml     | 15 +++++++++++++++
 project_name/.github/workflows/deps-update.yml | 13 +++++++++++++
 2 files changed, 28 insertions(+)

diff --git a/.github/workflows/update-template-pins.yml b/.github/workflows/update-template-pins.yml
index 0992404..7f70aca 100644
--- a/.github/workflows/update-template-pins.yml
+++ b/.github/workflows/update-template-pins.yml
@@ -80,6 +80,21 @@ jobs:
           delete-branch: true
           labels: dependencies
 
+      - name: Link the pull request
+        if: steps.cpr.outputs.pull-request-operation == 'created' || steps.cpr.outputs.pull-request-operation == 'updated'
+        env:
+          OPERATION: ${{ steps.cpr.outputs.pull-request-operation }}
+          URL: ${{ steps.cpr.outputs.pull-request-url }}
+        run: echo "::notice title=Pull request ${OPERATION}::$URL"
+
+      - name: Explain a failure to create the pull request
+        if: failure() && steps.cpr.outcome == 'failure'
+        run: |
+          url="$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/settings/actions"
+          msg="If the error is 'GitHub Actions is not permitted to create or approve pull requests': open $url, check 'Allow GitHub Actions to create and approve pull requests' under 'Workflow permissions', save, and re-run this workflow."
+          echo "::error title=Could not create the pull request::$msg"
+          echo "$msg" >> "$GITHUB_STEP_SUMMARY"
+
       - name: Run tests on the pull request
         # A pull request opened with GITHUB_TOKEN gets `pull_request` runs held for
         # approval, but `workflow_dispatch` runs right away, on the PR head.
diff --git a/project_name/.github/workflows/deps-update.yml b/project_name/.github/workflows/deps-update.yml
index 3688765..bebb53f 100644
--- a/project_name/.github/workflows/deps-update.yml
+++ b/project_name/.github/workflows/deps-update.yml
@@ -127,6 +127,19 @@ jobs:
           branch: deps/update
           delete-branch: true
           labels: dependencies
+      - name: Link the pull request
+        if: steps.cpr.outputs.pull-request-operation == 'created' || steps.cpr.outputs.pull-request-operation == 'updated'
+        env:
+          OPERATION: ${{ steps.cpr.outputs.pull-request-operation }}
+          URL: ${{ steps.cpr.outputs.pull-request-url }}
+        run: echo "::notice title=Pull request ${OPERATION}::$URL"
+      - name: Explain a failure to create the pull request
+        if: failure() && steps.cpr.outcome == 'failure'
+        run: |
+          url="$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/settings/actions"
+          msg="If the error is 'GitHub Actions is not permitted to create or approve pull requests': open $url, check 'Allow GitHub Actions to create and approve pull requests' under 'Workflow permissions', save, and re-run this workflow."
+          echo "::error title=Could not create the pull request::$msg"
+          echo "$msg" >> "$GITHUB_STEP_SUMMARY"
       - name: Run tests on the pull request
         # A pull request opened with GITHUB_TOKEN gets `pull_request` runs held for
         # approval, but `workflow_dispatch` runs right away, on the PR head.