Document create-discussion announcement-capable category requirement#15512
Document create-discussion announcement-capable category requirement#15512
Conversation
…FAQ entry Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
This PR documents a critical requirement for the create-discussion safe output: only announcement-capable categories can be used, and non-announcement categories fail with an integration-forbidden error. The documentation adds a prominent warning in the safe-outputs reference and a comprehensive FAQ entry to help users troubleshoot this common failure scenario.
Changes:
- Added a WARNING callout in the Discussion Creation section highlighting the announcement-capable category requirement
- Added a new FAQ entry explaining the integration-forbidden error, common causes (non-announcement categories, typos, slug vs display name issues), and the fallback-to-issue workaround
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| docs/src/content/docs/reference/safe-outputs.md | Added WARNING callout about announcement-capable category requirement immediately after the Category Naming Standard section |
| docs/src/content/docs/reference/faq.md | Added comprehensive FAQ entry explaining integration-forbidden errors with troubleshooting steps and fallback strategy |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| 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. |
There was a problem hiding this comment.
The example includes "general" as a category slug option, but the FAQ entry and warning state that only announcement-capable categories work. Including "general" as an example may mislead users since it's not typically an announcement-capable category. Consider using only "announcements" as the example, or clarifying that "general" should only be used if it has announcement capabilities enabled in the specific repository.
| - **Category slugs**: Use lowercase category slugs (e.g., `general`, `announcements`) rather than display names for better reliability. | |
| - **Category slugs**: Use lowercase category slugs (e.g., `announcements`) rather than display names for better reliability. |
| **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. |
There was a problem hiding this comment.
The warning message uses singular "category" but should use plural "categories" for grammatical correctness. Suggest changing to: "Only announcement-capable categories succeed; all non-announcement categories fail with integration-forbidden."
| > Only announcement-capable category succeeds; all non-announcement categories fail with integration-forbidden. | |
| > Only announcement-capable categories succeed; all non-announcement categories fail with integration-forbidden. |
Discussion creation via
create-discussionsafe output requires announcement-capable categories. Non-announcement categories fail withintegration-forbiddenerror.Changes
fallback-to-issue: trueThe warning appears immediately after the category naming standard section where users configure category values, maximizing visibility when most relevant.
Warning
Firewall rules blocked me from connecting to one or more addresses (expand for details)
I tried to connect to the following addresses, but was blocked by firewall rules:
telemetry.astro.build/opt/hostedtoolcache/node/24.13.0/x64/bin/node node /home/REDACTED/work/gh-aw/gh-aw/docs/node_modules/.bin/astro build(dns block)If you need me to access, download, or install something from one of these locations, you can either:
💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.