From d9c53fba24c23a15375c724e12577e4fc479121e Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 13 Feb 2026 21:02:11 +0000
Subject: [PATCH 1/2] Initial plan


From c9d4d134c865b7e62289eaced3f764405527109e Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 13 Feb 2026 21:08:02 +0000
Subject: [PATCH 2/2] Add documentation for create-discussion announcement
 requirement and FAQ entry

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
---
 docs/src/content/docs/reference/faq.md          | 11 +++++++++++
 docs/src/content/docs/reference/safe-outputs.md |  3 +++
 2 files changed, 14 insertions(+)

diff --git a/docs/src/content/docs/reference/faq.md b/docs/src/content/docs/reference/faq.md
index 146abe3140f..9c602447e72 100644
--- a/docs/src/content/docs/reference/faq.md
+++ b/docs/src/content/docs/reference/faq.md
@@ -229,6 +229,17 @@ Yes! Use [TrialOps](/gh-aw/patterns/trialops/) to test workflows in isolated tri
 
 See [Common Issues](/gh-aw/troubleshooting/common-issues/) for detailed troubleshooting guidance including workflow failures, debugging strategies, permission issues, and network problems.
 
+### Why is my create-discussion workflow failing with integration-forbidden?
+
+Discussion creation requires announcement-capable categories. If your workflow fails with an `integration-forbidden` error, ensure the `category` field in your configuration specifies a category that has announcement capabilities enabled in your repository's discussion settings.
+
+Common issues:
+- **Non-announcement categories**: Only categories configured to support announcements can be used for automated discussion creation. Check your repository's discussion settings to verify which categories have announcement capabilities.
+- **Category name typos**: Verify the category name spelling in your workflow configuration matches exactly with your repository's discussion categories. Category names are case-sensitive.
+- **Category slugs**: Use lowercase category slugs (e.g., `general`, `announcements`) rather than display names for better reliability.
+
+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.
+
 ## Workflow Design
 
 ### Should I focus on one workflow, or write many different ones?
diff --git a/docs/src/content/docs/reference/safe-outputs.md b/docs/src/content/docs/reference/safe-outputs.md
index 8f77c7eb1f3..67a595881a1 100644
--- a/docs/src/content/docs/reference/safe-outputs.md
+++ b/docs/src/content/docs/reference/safe-outputs.md
@@ -847,6 +847,9 @@ Creates discussions with optional `category` (slug, name, or ID; defaults to fir
 
 **Category Naming Standard**: Use lowercase, plural category names (e.g., `audits`, `general`, `reports`) for consistency and better searchability. GitHub Discussion category IDs (starting with `DIC_`) are also supported.
 
+> [!WARNING]
+> Only announcement-capable category succeeds; all non-announcement categories fail with integration-forbidden.
+
 ```yaml wrap
 safe-outputs:
   create-discussion: