Using gh-aw in forks of repositories

[dsyme]

We had a report that gh-aw doesn't work well in forks.

This is likely a lot of work and the first step will be to assess what works and what doesn't and give good errors or warnings if you add workflows to forks that use features that are known not to work well.

[dsyme]

/scout Please do the analysis mentioned

[github-actions]

🔍 Scout Research Report

Triggered by @dsyme

Executive Summary

This report analyzes what works and what doesn't when gh-aw is used in forked repositories. There are two distinct fork scenarios that need to be addressed separately, with different failure modes and mitigation strategies. Several areas already have good handling; others need new errors/warnings.

Click to expand detailed findings

Research Findings

Two Distinct Fork Scenarios

Scenario A — Fork PRs into a gh-aw repo (inbound)

This scenario is already well-handled by the compiler:

• pull_request triggers block all fork PRs by default (github.event.pull_request.head.repo.id == github.repository_id check injected)
• forks: frontmatter field allows explicit allow-listing of trusted forks
• push-to-pull-request-branch safe-output already has a fork check with a clear error: "Cannot push to fork PR: ... The workflow token does not have permission to push to fork repositories."
• workflow_run triggers have !(github.event.workflow_run.repository.fork) injected by the compiler

Scenario B — Running gh-aw workflows inside a forked repository (fork-internal)

This is the unhandled case mentioned in the issue. When a user forks a repo that has gh-aw installed and tries to use those workflows in their own fork, multiple things break without clear errors:

---

Specific Features That Break in Forks

1. Secrets / API Keys — Silent Failures

Forked repos do not inherit secrets from the parent. All of these will be missing:

• ANTHROPIC_API_KEY, OPENAI_API_KEY — the AI model cannot run at all
• GH_AW_GITHUB_TOKEN, GH_AW_COPILOT_TOKEN, GH_AW_GITHUB_MCP_SERVER_TOKEN — GitHub API/MCP access degraded
• Any workflow-specific secrets

The current validate_secrets.cjs step in agentics-maintenance will report all these as missing, but without any indication that the fork context is the likely cause.

2. Agentic Maintenance Workflow (agentics-maintenance.yml) — Noisy and Confusing

This schedule-based workflow is automatically copied to all forks. In forks it will:

• Run every 2 hours on schedule
• Attempt to validate secrets (all fail)
• Attempt to compile workflows (may fail without AI key)
• Attempt to close expired issues/discussions/PRs (may silently no-op or fail)

There is currently no fork detection or graceful skip path in this workflow.

3. Slash Command Triggers — Broken Without Explanation

Issue comment-based /command triggers will fire on the fork's own issues/PRs, but the workflow will fail silently or with generic errors when the AI model can't start due to missing API keys. There is no user-facing message explaining the fork context.

4. gh aw init — No Fork Guidance

The init command doesn't detect fork context and gives no guidance about the different secret setup requirements for forks. A fork user running gh aw init gets the same instructions as a fresh install, with no indication they also need to configure their own copies of all the secrets.

5. Error Messages — Missing Fork Context

When workflows fail due to missing secrets in a fork, current errors say things like "API key not found" or "token not configured" — with no mention of fork context as a likely cause. This makes debugging very difficult for users who don't know what a fork implies for secrets.

6. workflow_run-based Triggers — Fork Safety Check Present, But Error Not User-Friendly

The workflow_run compiler already injects !(github.event.workflow_run.repository.fork) which prevents cross-fork triggering. The safety check itself is good, but if a fork user wonders why their workflow_run workflow never fires, there's no clear explanation.

---

What Currently Works in Forks

Feature	Status	Notes
pull_request fork filtering	✅ Already handled	Compiler injects repo ID check; forks: field for allow-listing
push-to-pull-request-branch fork check	✅ Already handled	Clear error message
workflow_run cross-fork safety	✅ Already handled	Fork check injected at compile time
Fork repo running its own workflows	⚠️ Partially works	Only if fork owner configures their own secrets
Agentic maintenance in fork	❌ Broken	No fork detection, runs without proper config
Slash commands in fork	❌ Broken	Fails silently without fork context in error
gh aw init in fork	❌ No guidance	No fork detection, no guidance on secret setup
Error messages in fork context	❌ No fork context	Generic errors, no fork cause explanation

---

Platform Constraints (GitHub Actions)

From GitHub's documentation:

• Fork PRs use a read-only GITHUB_TOKEN with no access to parent secrets (unless repo explicitly enables "Send secrets to workflows from pull requests")
• Forked repos don't inherit Actions secrets — the fork owner must configure their own secrets
• pull_request_target event runs in the base repo context with full secret access — this is an alternative pattern for safe fork PR handling that could be relevant for some gh-aw workflows
• Cache access from forks to the base repo is a known security consideration

Recommendations

1. Compile-time fork detection: gh aw compile (and gh aw init) should detect when running inside a forked repository (check gh repo view --json isFork) and emit warnings listing which secrets need to be configured and which features are restricted.

2. Fork-aware error messages: When a workflow fails because secrets are missing, add a check for github.event.repository.fork == true context. Include a fork-specific hint in the failure issue/comment generated by the conclusion job.

3. Agentic maintenance workflow — fork skip: Add a step at the start of agentics-maintenance.yml that checks if the current repository is a fork and skips with an info message rather than running and failing.

4. Fork documentation page: A dedicated page explaining: what works in forks, what doesn't, how to set up your own secrets, and when to use forks: vs pull_request_target.

5. validate_secrets fork context: In validate_secrets.cjs, detect the fork context (check context.payload.repository.fork) and prefix the report with a warning that all secrets must be reconfigured in the fork.

6. Consider pull_request_target guidance: For workflows that need to react to fork PRs with write access (e.g., auto-labeling, auto-commenting), document and provide an example using pull_request_target which runs in the base repo context.

Key Sources

• GitHub Docs: Managing GitHub Actions settings for a repository — fork PR workflow settings
• [GitHub Blog: GitHub Actions improvements for fork and pull request workflows]((github.blog/redacted) — pull_request_target event and fork settings
• GitHub Docs: About permissions and visibility of forks — fork permission model
• Codebase: pkg/workflow/filters.go — existing fork filter implementation
• Codebase: actions/setup/js/push_to_pull_request_branch.cjs — existing fork check pattern
• Codebase: pkg/workflow/workflow_run_repo_safety_test.go — workflow_run fork safety checks

Suggested Next Steps

1. Add fork detection to gh aw init/gh aw compile CLI commands with a warning message listing required secrets
2. Add a fork check step to agentics-maintenance.yml that gracefully skips with an info message
3. Update validate_secrets.cjs and the conclusion job failure reporter to include fork context if context.payload.repository.fork === true
4. Add a documentation page on fork support with a compatibility table
5. Consider whether pull_request_target should be added as a supported trigger type in the compiler with appropriate security warnings

References:

• §22442517078

🔭 Intelligence gathered by Scout

[pelikhan]

we need to maintain a fork and run agentic workflows in there

[pelikhan]

it's the only way to ensure this feature works.

[pelikhan]

/plan