Skip to content

[plan] Add fork support documentation page #18521

@github-actions

Description

@github-actions

Context

Closes part of #18481 — gh-aw in forks.

There is currently no documentation explaining how gh-aw behaves in forked repositories, what works, what doesn't, and how to set things up correctly.

Objective

Add a documentation page on fork support under docs/ covering the compatibility matrix, required setup steps for fork users, and explanation of design decisions.

Approach

  1. Create a new documentation page, e.g., docs/src/content/docs/guides/fork-support.md (follow the existing Diátaxis/Starlight conventions used in docs/).

  2. The page should include:

    • Overview: two fork scenarios (inbound fork PRs vs. running gh-aw in a fork)

    • Compatibility table (based on the scout report):

      Feature Status in Fork Notes
      pull_request fork filtering ✅ Works Compiler injects repo ID check
      workflow_run cross-fork safety ✅ Works Fork check injected at compile time
      Running your own workflows ⚠️ Partial Must configure own secrets
      Agentic maintenance ⚠️ Skipped Fork detection added; skips gracefully
      Slash commands ⚠️ Partial Works if secrets configured
      Secrets ❌ Not inherited Must reconfigure in fork settings
    • Setup guide: step-by-step for configuring required secrets in a fork

    • forks: frontmatter field: explanation of allow-listing trusted forks

    • Known limitations: features that won't work regardless of secret setup

  3. Reference the documentation skill (skills/documentation.md) for style/format guidelines.

  4. Verify the page renders correctly in the docs site structure.

Files to Create/Modify

  • docs/src/content/docs/guides/fork-support.md (new)
  • Possibly update docs/src/content/docs/guides/ index or sidebar config

Acceptance Criteria

  • New documentation page exists covering the two fork scenarios
  • Compatibility table present with accurate status
  • Setup guide covers all required secrets
  • forks: frontmatter field documented
  • Page follows existing docs style and Diátaxis conventions
    Related to Using gh-aw in forks of repositories #18481

Generated by Plan Command for issue #18481

  • expires on Feb 28, 2026, 4:18 PM UTC

Metadata

Metadata

Labels

Type

No type
No fields configured for issues without a type.

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions