Document Actions permission restrictions detected by init command

[Copilot]

The gh aw init command validates repository Actions configuration via checks in pkg/cli/preconditions.go. Users encountering these validation errors need guidance on resolution.

Changes

• Added FAQ entry explaining three Actions restriction scenarios that block workflow execution:

  • Actions completely disabled in repository settings
  • local_only restriction blocking GitHub-owned actions (actions/checkout, actions/setup-node)
  • Selective allowlists missing GitHub-created actions checkbox

• Linked to GitHub documentation for managing Actions settings, permissions, and action allowlists

• Added CAUTION callout for org-level policy inheritance that overrides repository settings

The FAQ entry maps directly to the validation logic in checkActionsEnabledShared() and checkSelectedActionsPermissions().

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
  • Triggering command: /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:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

Add an FAQ answer about disable actions and actions restrictions in repositories that maybe create issues for aw. See recent commit with check in tbe init command to detect those. Links to github docs.

Custom agent used: technical-doc-writer
AI technical documentation writer for GitHub Actions library using GitHub Docs voice

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[Copilot]

Pull request overview

Adds troubleshooting guidance to the FAQ for gh aw init when repository GitHub Actions settings prevent agentic workflows from running, aligning the docs with the CLI’s precondition checks.

Changes:

• Added a new FAQ entry describing three GitHub Actions restriction scenarios that can block workflow execution
• Linked to relevant GitHub Docs pages for Actions settings and permissions
• Added a CAUTION callout noting that org-level policies can override repo settings

Comments suppressed due to low confidence (2)

docs/src/content/docs/reference/faq.md:191

• "Workflows upload successfully" is potentially misleading here (init isn't uploading anything). This scenario is better described the same way the CLI does: you can add workflows to the repo, but they won't run until Actions is enabled.

**Actions completely turned off:** Your repo has Actions disabled entirely. Workflows upload successfully but never trigger. Fix: Repository Settings → Actions → General → toggle Actions on. Reference: [Managing Actions settings](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository).

docs/src/content/docs/reference/faq.md:193

• The UI wording in the local-only scenario looks incorrect. The CLI/API case is allowed_actions == local_only, which corresponds to allowing only local actions (actions defined in this repository), not "Allow [owner] actions only". Suggest aligning the FAQ wording with the actual setting name to reduce confusion.

**Local-only restriction:** You've configured "Allow [owner] actions only", which blocks external actions including GitHub's own. Agentic workflows need `actions/checkout`, `actions/setup-node`, etc. Fix: Settings → Actions → General → switch to "Allow all actions" or "Allow select actions" with GitHub-created ones enabled. Reference: [Managing Actions permissions](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#managing-github-actions-permissions-for-your-repository).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The text says users may encounter "errors" when running gh aw init, but the Actions completely turned off case in checkActionsEnabledShared() only prints a warning and continues (no error returned). Consider rephrasing to "warnings or errors" and clarifying which scenarios are blocking vs informational.

This issue also appears in the following locations of the same file:

• line 191
• line 193