Add FAQ link to "GitHub Actions not permitted to create or approve pull requests" diagnostics

actions/setup/js/create_pull_request.cjs

@@ -37,6 +37,9 @@ const HANDLER_TYPE = "create_pull_request";
 /** @type {string} Label always added to fallback issues so the triage system can find them */
 const MANAGED_FALLBACK_ISSUE_LABEL = "agentic-workflows";
 
+/** @type {string} FAQ link for the "GitHub Actions is not permitted to create or approve pull requests" error */
+const FAQ_CREATE_PR_PERMISSIONS_URL = "https://github.github.com/gh-aw/reference/faq/#why-is-my-create-pull-request-workflow-failing-with-github-actions-is-not-permitted-to-create-or-approve-pull-requests";
+
 // GitHub Copilot reviewer bot username
 const COPILOT_REVIEWER_BOT = "copilot-pull-request-reviewer[bot]";
 
@@ -1158,7 +1161,7 @@ ${patchPreview}`;
 
       // Check if the error is the specific "GitHub actions is not permitted to create or approve pull requests" error
       if (errorMessage.includes("GitHub Actions is not permitted to create or approve pull requests")) {
-        core.error("Permission error: GitHub Actions is not permitted to create or approve pull requests");
+        core.error(`Permission error: GitHub Actions is not permitted to create or approve pull requests. See FAQ: ${FAQ_CREATE_PR_PERMISSIONS_URL}`);
 
         // Branch has already been pushed - create a fallback issue with a link to create the PR via GitHub UI
         const githubServer = process.env.GITHUB_SERVER_URL || "https://github.com";
@@ -1174,15 +1177,15 @@ ${patchPreview}`;
           patchPreview = generatePatchPreview(patchContent);
         }
 
-        const fallbackBody =
-          `${body}\n\n---\n\n` +
-          `> [!NOTE]\n` +
-          `> This was originally intended as a pull request, but GitHub Actions is not permitted to create or approve pull requests in this repository.\n` +
-          `> The changes have been pushed to branch \`${branchName}\`.\n` +
-          `>\n` +
-          `> **[Click here to create the pull request](${createPrUrl})**\n\n` +
-          `To fix the permissions issue, go to **Settings** → **Actions** → **General** and enable **Allow GitHub Actions to create and approve pull requests**.` +
-          patchPreview;
+        const fallbackTemplatePath = `${process.env.RUNNER_TEMP}/gh-aw/prompts/pr_permission_denied_fallback.md`;
+        const fallbackTemplate = fs.readFileSync(fallbackTemplatePath, "utf8");
+        const fallbackBody = renderTemplate(fallbackTemplate, {
+          body,
+          branch_name: branchName,
+          create_pr_url: createPrUrl,
+          faq_url: FAQ_CREATE_PR_PERMISSIONS_URL,
+          patch_preview: patchPreview,
+        });
 
         try {
           const { data: issue } = await githubClient.rest.issues.create({

actions/setup/js/handle_create_pr_error.cjs

@@ -4,6 +4,9 @@
 const { sanitizeContent } = require("./sanitize_content.cjs");
 const { getErrorMessage } = require("./error_helpers.cjs");
 
+/** @type {string} FAQ link for the "GitHub Actions is not permitted to create or approve pull requests" error */
+const FAQ_CREATE_PR_PERMISSIONS_URL = "https://github.github.com/gh-aw/reference/faq/#why-is-my-create-pull-request-workflow-failing-with-github-actions-is-not-permitted-to-create-or-approve-pull-requests";
+
 /**
  * Handle create_pull_request permission errors
  * This script is called from the conclusion job when create_pull_request fails
@@ -44,7 +47,11 @@ async function main() {
     "3. Check the box: **Allow GitHub Actions to create and approve pull requests**\n" +
     "4. Click **Save**\n\n" +
     "### Documentation\n\n" +
-    "For more information, see: [Managing GitHub Actions settings for a repository](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#preventing-github-actions-from-creating-or-approving-pull-requests)\n\n" +
+    "For more information, see:\n" +
+    "- [gh-aw FAQ: Why is my create-pull-request workflow failing?](" +
+    FAQ_CREATE_PR_PERMISSIONS_URL +
+    ")\n" +
+    "- [Managing GitHub Actions settings for a repository](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#preventing-github-actions-from-creating-or-approving-pull-requests)\n\n" +
     "### Workflow Details\n\n" +
     "- **Workflow**: " +
     workflowName +

actions/setup/md/pr_permission_denied_fallback.md

@@ -0,0 +1,11 @@
+{body}
+
+---
+
+> [!NOTE]
+> This was originally intended as a pull request, but GitHub Actions is not permitted to create or approve pull requests in this repository.
+> The changes have been pushed to branch `{branch_name}`.
+>
+> **[Click here to create the pull request]({create_pr_url})**
+
+To fix the permissions issue, go to **Settings** → **Actions** → **General** and enable **Allow GitHub Actions to create and approve pull requests**. See also: [gh-aw FAQ]({faq_url}){patch_preview}