Skip to content

Add FAQ entry for PR creation disabled by organization settings #15676

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pelikhan merged 2 commits into from
Feb 14, 2026
Merged

Add FAQ entry for PR creation disabled by organization settings #15676

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b45a13d
Initial plan
Copilot Feb 14, 2026
9684830
Add FAQ entry for PR creation restrictions with workarounds
Copilot Feb 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 56 additions & 0 deletions docs/src/content/docs/reference/faq.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Comment on lines +242 to +245
Copy link

Copilot AI Feb 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This section mentions the setting can be disabled via repository or organization settings, but the navigation that follows only references organization settings. Consider including the repository-level path (repo Settings → Actions → General) or rewording the heading to reflect both scopes so readers look in the right place.

Suggested change
**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
**Where to change this setting (organization or repository):**
- At the organization level: Navigate to your organization's **Settings** → **Actions** → **General**
- Look for the **"Workflow permissions"** section
- Check if **"Allow GitHub Actions to create and approve pull requests"** is disabled
- At the repository level: Navigate to the repository's **Settings** → **Actions** → **General**, then check the **"Workflow permissions"** section for **"Allow GitHub Actions to create and approve pull requests"**

Copilot uses AI. Check for mistakes.

**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)**
Comment on lines +249 to +251
Copy link

Copilot AI Feb 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The intro sentence says "you have two alternatives", but three options are listed below. Also, Option 1 is labeled "Use create-issue with automatic fallback" while the example/config shown is create-pull-request with fallback-as-issue behavior—this heading should match the safe output being configured.

Suggested change
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)**
If you cannot enable PR creation or prefer to keep it disabled for security reasons, you have the following alternatives:
**Option 1: Use create-pull-request with automatic fallback (default)**

Copilot uses AI. Check for mistakes.

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?
Expand Down