From b45a13d000658da492329991bf3cef757c54e120 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 14 Feb 2026 13:35:59 +0000
Subject: [PATCH 1/2] Initial plan


From 96848309b6793185bf234d8980f8ccbba59ba1d0 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 14 Feb 2026 13:41:31 +0000
Subject: [PATCH 2/2] Add FAQ entry for PR creation restrictions with
 workarounds

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
---
 docs/src/content/docs/reference/faq.md | 56 ++++++++++++++++++++++++++
 1 file changed, 56 insertions(+)

diff --git a/docs/src/content/docs/reference/faq.md b/docs/src/content/docs/reference/faq.md
index adadcbb0fd5..ac54e97a827 100644
--- a/docs/src/content/docs/reference/faq.md
+++ b/docs/src/content/docs/reference/faq.md
@@ -235,6 +235,62 @@ Common issues:
 
 If discussions are not enabled or the category lacks announcement capabilities, consider using `fallback-to-issue: true` (the default) to automatically create an issue instead. See [Discussion Creation](/gh-aw/reference/safe-outputs/#discussion-creation-create-discussion) for configuration details.
 
+### Why is my create-pull-request workflow failing with "GitHub Actions is not permitted to create or approve pull requests"?
+
+Some organizations disable pull request creation by GitHub Actions workflows through repository or organization settings. This security policy prevents automation from creating PRs, resulting in the error: **"GitHub Actions is not permitted to create or approve pull requests."**
+
+**Organization Setting Location:**
+- Navigate to your organization's **Settings** → **Actions** → **General**
+- Look for **"Workflow permissions"** section
+- Check if **"Allow GitHub Actions to create and approve pull requests"** is disabled
+
+**Workaround Options:**
+
+If you cannot enable PR creation or prefer to keep it disabled for security reasons, you have two alternatives:
+
+**Option 1: Use create-issue with automatic fallback (default)**
+
+The `create-pull-request` safe output automatically falls back to creating an issue when PR creation is blocked:
+
+```yaml wrap
+safe-outputs:
+  create-pull-request:
+    # fallback-as-issue: true is the default behavior
+    # When PR creation fails, an issue is created with branch link
+```
+
+This requires both `contents: write` + `pull-requests: write` (for PR attempt) and `issues: write` (for fallback).
+
+**Option 2: Use create-issue directly with Copilot assignment**
+
+Create an issue describing the desired changes and assign it to Copilot for automated implementation:
+
+```yaml wrap
+safe-outputs:
+  create-issue:
+    assignees: [copilot]              # Assign to Copilot for PR creation
+    labels: [automation, enhancement] # Add tracking labels
+```
+
+When assigned to Copilot, the issue can be automatically picked up for processing in a separate workflow or manually reviewed by the Copilot agent to create the PR.
+
+**Option 3: Disable issue fallback to save permissions**
+
+If you only want PR creation (no fallback), disable the issue fallback to avoid requiring `issues: write`:
+
+```yaml wrap
+safe-outputs:
+  create-pull-request:
+    fallback-as-issue: false          # Only attempt PR creation
+```
+
+This requires only `contents: write` + `pull-requests: write`, but workflows will fail if PR creation is blocked at the organization level.
+
+> [!TIP]
+> For workflows that need to work across different organizations with varying PR policies, use the default `fallback-as-issue: true` behavior. This ensures workflows gracefully adapt to organization settings.
+
+See [Pull Request Creation](/gh-aw/reference/safe-outputs/#pull-request-creation-create-pull-request) for complete configuration details and the fallback mechanism explanation.
+
 ## Workflow Design
 
 ### Should I focus on one workflow, or write many different ones?