Skip to content

Commit a5893d4

Browse files
bradygasterbradygaster
authored
Merge pull request #2072 from bradygaster/bradygaster-investigate-agentic-workflow-failures
docs: require Issues before gh-aw installation
2 parents fcb7747 + a6a8c95 commit a5893d4

9 files changed

Lines changed: 375 additions & 25 deletions

File tree

‎.changeset/gh-aw-issues-prerequisite.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
"@bradygaster/squad-cli": patch
3+
"@bradygaster/squad-sdk": patch
4+
---
5+
6+
Require GitHub Issues to be enabled before installing Squad Agentic Workflows, and fail closed when the authenticated user cannot update the repository setting.

‎.github/agents.md‎

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -23,10 +23,15 @@ GitHub Agentic Workflows (`gh-aw`) are composable AI workflows triggered by slas
2323
> Agentic Workflows, execute the complete
2424
> [seven-step quick start](../docs/src/content/docs/guide/gh-aw.md#quick-start)
2525
> in their repository. Do not only quote or run the `gh aw add` command below.
26-
> The supported path configures workflow-created pull requests, installs and
27-
> validates the complete generated artifact set, commits it on an isolated
28-
> branch, and opens a human-reviewed bootstrap PR. Stop at that PR; the human
29-
> merges it. `/squad` slash commands become active only after that merge reaches
26+
> The supported path verifies that GitHub Issues are enabled (and enables them
27+
> when the authenticated user has repository administration permission),
28+
> configures workflow-created pull requests, installs and validates the complete
29+
> generated artifact set, commits it on an isolated branch, and opens a
30+
> human-reviewed bootstrap PR. If disabled Issues cannot be enabled, stop before
31+
> installation and ask a repository administrator to enable them. `/squad`
32+
> commands use issue comments, and bootstrap creates a research/proposals issue.
33+
> Stop at the bootstrap PR; the human merges it.
34+
> `/squad` slash commands become active only after that merge reaches
3035
> the repository's default branch.
3136
3237
The quick start installs this workflow set:

‎.squad-templates/skills/gh-aw-enlistment/SKILL.md‎

Lines changed: 56 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,8 @@ source: "Operationalized from the authoritative Squad gh-aw guide (docs/src/cont
77
triggers: [set up Squad agentic workflows, enlist this repo in Squad, enlist my repository in Squad, install Squad gh-aw workflows, install Squad agentic workflows, add Squad gh aw workflows, bootstrap Squad in this repo, onboard this repo to Squad, set up /squad slash commands, gh aw add squad]
88
tools:
99
- name: "gh"
10-
description: "GitHub CLI — repo identity, Actions permissions, PR creation, review request, and check watching."
11-
when: "Every step: preflight identity/auth, enabling Actions-created PRs, opening and watching the bootstrap PR."
10+
description: "GitHub CLI — repo identity, Issues and Actions settings, PR creation, review request, and check watching."
11+
when: "Every step: preflight identity/auth, requiring Issues, enabling Actions-created PRs, opening and watching the bootstrap PR."
1212
- name: "gh aw"
1313
description: "GitHub Agentic Workflows extension (github/gh-aw) — installs and strictly compiles the Squad workflow set."
1414
when: "Installing the seven @dev workflows and compiling them into deterministic .lock.yml files."
@@ -28,6 +28,12 @@ The authoritative source is `docs/src/content/docs/guide/gh-aw.md` (mirrored at
2828
`https://bradygaster.github.io/squad/docs/guide/gh-aw/`). If that guide and this
2929
skill ever disagree, the guide wins — re-read it before proceeding.
3030

31+
GitHub Issues are a hard prerequisite: `/squad` commands arrive as issue
32+
comments, and the merged bootstrap creates a research/proposals issue. Detect
33+
and enable Issues before creating the bootstrap branch or installing workflows,
34+
so the install cannot produce a PR whose post-merge bootstrap is unable to
35+
complete.
36+
3137
**Portability contract:** resolve every repository identifier (owner, repo, default
3238
branch) **at runtime**. Never hardcode a placeholder like `{owner}/{repo}`. The only
3339
fixed identifier is the Squad source itself — `bradygaster/squad/workflows/...@dev` —
@@ -73,10 +79,37 @@ git status --short
7379
- Confirm Copilot is enabled for the repository where checkable; the activation
7480
run and the requested `@copilot` review both depend on it.
7581

76-
### 1. Allow Actions-created PRs while keeping the default token read-only
82+
### 1. Require GitHub Issues, then allow Actions-created PRs with a read-only token
7783

78-
Squad opens PRs through GitHub Actions. Enable that **without** widening the
79-
default workflow token:
84+
Check the REST API's `has_issues` field first. If Issues are disabled, enable
85+
them before touching the install:
86+
87+
```bash
88+
issues_enabled="$(gh api "repos/${owner_repo}" --jq '.has_issues')"
89+
if [ "${issues_enabled}" != "true" ]; then
90+
echo "GitHub Issues are disabled; enabling them before workflow installation."
91+
if ! gh api --method PATCH "repos/${owner_repo}" \
92+
-F has_issues=true --silent; then
93+
echo "STOP: GitHub Issues are disabled and could not be enabled." >&2
94+
echo "A repository administrator must enable Settings > General > Features > Issues, then rerun enlistment." >&2
95+
exit 1
96+
fi
97+
fi
98+
99+
test "$(gh api "repos/${owner_repo}" --jq '.has_issues')" = "true" || {
100+
echo "STOP: GitHub Issues must be enabled before installing Squad workflows." >&2
101+
exit 1
102+
}
103+
```
104+
105+
Reading `.has_issues` is non-mutating. Updating it through
106+
`PATCH /repos/{owner}/{repo}` requires repository administration permission.
107+
If the PATCH fails, **STOP before branch creation or `gh aw add`** and ask an
108+
administrator to enable **Settings → General → Features → Issues**. Do not
109+
continue with a bootstrap PR that cannot complete after merge.
110+
111+
Squad also opens PRs through GitHub Actions. Enable that **without** widening
112+
the default workflow token:
80113

81114
```bash
82115
gh api --method PUT "repos/${owner_repo}/actions/permissions/workflow" \
@@ -295,6 +328,21 @@ gh pr checks --watch
295328
owner_repo="$(gh repo view --json nameWithOwner --jq '.nameWithOwner')"
296329
default_branch="$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name')"
297330

331+
issues_enabled="$(gh api "repos/${owner_repo}" --jq '.has_issues')"
332+
if [ "${issues_enabled}" != "true" ]; then
333+
if ! gh api --method PATCH "repos/${owner_repo}" \
334+
-F has_issues=true --silent; then
335+
echo "STOP: GitHub Issues are disabled and could not be enabled." >&2
336+
echo "A repository administrator must enable Settings > General > Features > Issues, then rerun enlistment." >&2
337+
exit 1
338+
fi
339+
fi
340+
341+
test "$(gh api "repos/${owner_repo}" --jq '.has_issues')" = "true" || {
342+
echo "STOP: GitHub Issues must be enabled before installing Squad workflows." >&2
343+
exit 1
344+
}
345+
298346
gh api --method PUT "repos/${owner_repo}/actions/permissions/workflow" \
299347
-f default_workflow_permissions=read -F can_approve_pull_request_reviews=true
300348

@@ -353,6 +401,9 @@ gh pr merge --squash # auto-merge before human review. NEVER.
353401

354402
- ❌ **Hardcoding repository identifiers.** Always resolve `owner/repo` and the
355403
default branch at runtime with `gh repo view`.
404+
- ❌ **Installing while GitHub Issues are disabled.** `/squad` commands and the
405+
bootstrap research/proposals issue require Issues. Enable them first, or stop
406+
before installation if repository administration permission is unavailable.
356407
- ❌ **Blanket staging** (`git add .` / `-A` / `git commit -a`). Stage only
357408
`.gitattributes`, `.github/aw/`, `.github/workflows/`, `.github/skills/`, by path.
358409
- ❌ **Approving unknown safe updates.** Approve ONLY `SQUAD_GITHUB_APP_PRIVATE_KEY`,

‎README.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -561,7 +561,31 @@ If you use [GitHub Agentic Workflows](https://github.blog/changelog/2025-05-19-g
561561

562562
<!-- cspell:ignore agentics -->
563563

564+
Squad requires GitHub Issues: slash commands are issue comments, and the merged
565+
bootstrap creates a research/proposals issue. Follow the
566+
[supported seven-step quick start](docs/src/content/docs/guide/gh-aw.md#quick-start),
567+
which checks and enables Issues before installation when the authenticated user
568+
has repository administration permission, and stops before creating a bootstrap
569+
PR when an administrator must enable them.
570+
564571
```bash
572+
set -euo pipefail
573+
574+
owner_repo="$(gh repo view --json nameWithOwner --jq '.nameWithOwner')"
575+
issues_enabled="$(gh api "repos/${owner_repo}" --jq '.has_issues')"
576+
if [ "${issues_enabled}" != "true" ]; then
577+
if ! gh api --method PATCH "repos/${owner_repo}" \
578+
-F has_issues=true --silent; then
579+
echo "STOP: A repository administrator must enable Settings > General > Features > Issues." >&2
580+
exit 1
581+
fi
582+
fi
583+
584+
test "$(gh api "repos/${owner_repo}" --jq '.has_issues')" = "true" || {
585+
echo "STOP: GitHub Issues must be enabled before installing Squad workflows." >&2
586+
exit 1
587+
}
588+
565589
gh aw add \
566590
bradygaster/squad/workflows/squad.md@dev \
567591
bradygaster/squad/workflows/squad-implement-worker.md@dev \

‎docs/src/content/docs/guide/gh-aw.md‎

Lines changed: 57 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,23 @@ owner_repo="$(gh repo view --json nameWithOwner --jq '.nameWithOwner')"
3333
default_branch="$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name')"
3434
gh extension list | grep -q 'github/gh-aw' || gh extension install github/gh-aw
3535

36-
# 2. Allow GitHub Actions to create pull requests
36+
# 2. Require GitHub Issues, then allow GitHub Actions to create pull requests
37+
issues_enabled="$(gh api "repos/${owner_repo}" --jq '.has_issues')"
38+
if [ "${issues_enabled}" != "true" ]; then
39+
echo "GitHub Issues are disabled; enabling them before workflow installation."
40+
if ! gh api --method PATCH "repos/${owner_repo}" \
41+
-F has_issues=true --silent; then
42+
echo "STOP: GitHub Issues are disabled and could not be enabled." >&2
43+
echo "A repository administrator must enable Settings > General > Features > Issues, then rerun this quick start." >&2
44+
exit 1
45+
fi
46+
fi
47+
48+
test "$(gh api "repos/${owner_repo}" --jq '.has_issues')" = "true" || {
49+
echo "STOP: GitHub Issues must be enabled before installing Squad workflows." >&2
50+
exit 1
51+
}
52+
3753
gh api --method PUT "repos/${owner_repo}/actions/permissions/workflow" \
3854
-f default_workflow_permissions=read \
3955
-F can_approve_pull_request_reviews=true
@@ -104,6 +120,15 @@ contains the complete seven-workflow set. For a repeatable upgrade, pin all
104120
seven entries to one reviewed commit as described in
105121
[Upgrading the workflows](#upgrading-the-workflows).
106122

123+
Step 2 deliberately checks Issues before creating the bootstrap branch or
124+
installing any workflow. Squad commands are issue comments, and the merged
125+
bootstrap creates a research/proposals issue; without Issues, the installation
126+
PR could merge but the bootstrap journey could not complete. Reading
127+
`.has_issues` is safe for normal repository access. Enabling it through
128+
`PATCH /repos/{owner}/{repo}` requires repository administration permission. If
129+
that update fails, stop before installation and ask an administrator to enable
130+
**Settings → General → Features → Issues**, then rerun the quick start.
131+
107132
> Step 7 stages `.github/skills/` because `gh aw add` installs the Squad skills
108133
> alongside the workflows, and it deliberately does not stage `.github/aw/logs/`.
109134
> Downloaded workflow logs are local diagnostic output — see [ignoring downloaded
@@ -136,13 +161,43 @@ issues exist.
136161
| Requirement | Details |
137162
|-------------|---------|
138163
| GitHub repo with Copilot | Copilot must be enabled for the repository |
164+
| GitHub Issues | Required for `/squad` issue comments and the bootstrap research/proposals issue; a repository administrator must be available to enable Issues if they are disabled |
139165
| `gh` CLI | [Install the GitHub CLI](https://cli.github.com/) and authenticate with `gh auth login` |
140166
| `gh aw` extension | `gh extension install github/gh-aw` |
141167

142168
---
143169

144170
## Setup
145171

172+
### Enable GitHub Issues
173+
174+
Squad receives commands through issue comments, and `squad-bootstrap` creates a
175+
research/proposals issue after the workflow-installation PR merges. Check the
176+
repository setting and enable it before installing any workflows:
177+
178+
```bash
179+
owner_repo="$(gh repo view --json nameWithOwner --jq '.nameWithOwner')"
180+
issues_enabled="$(gh api "repos/${owner_repo}" --jq '.has_issues')"
181+
182+
if [ "${issues_enabled}" != "true" ]; then
183+
if ! gh api --method PATCH "repos/${owner_repo}" \
184+
-F has_issues=true --silent; then
185+
echo "STOP: A repository administrator must enable Settings > General > Features > Issues." >&2
186+
exit 1
187+
fi
188+
fi
189+
190+
test "$(gh api "repos/${owner_repo}" --jq '.has_issues')" = "true" || {
191+
echo "STOP: GitHub Issues must be enabled before installing Squad workflows." >&2
192+
exit 1
193+
}
194+
```
195+
196+
The GET is non-mutating, and the conditional PATCH makes this safe to rerun.
197+
Changing `has_issues` requires repository administration permission. If the
198+
PATCH fails, do not continue to `gh aw add`: have an administrator enable Issues
199+
in repository settings, then rerun the supported quick start.
200+
146201
### Allow workflow-created pull requests
147202

148203
Squad opens pull requests through GitHub Actions. Enable this repository setting
@@ -384,6 +439,7 @@ Use this checklist for the initial bootstrap and after any workflow update:
384439
385440
| Stage | Action | Expected evidence |
386441
|-------|--------|-------------------|
442+
| Repository readiness | Confirm `.has_issues` is `true`; if it is `false`, enable it before installing workflows | GitHub Issues are available for `/squad` comments and the bootstrap research/proposals issue; insufficient administration permission stops the install before a bootstrap PR is created |
387443
| Install | Run the seven-workflow `gh aw add` command on a bootstrap branch | All seven `.md`/`.lock.yml` pairs exist, with shared imports, `.github/aw/`, installed skills, and `.gitattributes` included in the diff |
388444
| Compile | Review any first-install safe-update report, approve only the documented entries, then run `gh aw compile --strict` without approval | All seven workflows succeed, only documented warnings remain, and all fourteen source/lock files exist |
389445
| Bootstrap review | Open the PR, request `@copilot`, wait for checks, and merge only after human approval | The default branch receives the complete generated install as one human-reviewable change |

‎packages/squad-cli/templates/skills/gh-aw-enlistment/SKILL.md‎

Lines changed: 56 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,8 @@ source: "Operationalized from the authoritative Squad gh-aw guide (docs/src/cont
77
triggers: [set up Squad agentic workflows, enlist this repo in Squad, enlist my repository in Squad, install Squad gh-aw workflows, install Squad agentic workflows, add Squad gh aw workflows, bootstrap Squad in this repo, onboard this repo to Squad, set up /squad slash commands, gh aw add squad]
88
tools:
99
- name: "gh"
10-
description: "GitHub CLI — repo identity, Actions permissions, PR creation, review request, and check watching."
11-
when: "Every step: preflight identity/auth, enabling Actions-created PRs, opening and watching the bootstrap PR."
10+
description: "GitHub CLI — repo identity, Issues and Actions settings, PR creation, review request, and check watching."
11+
when: "Every step: preflight identity/auth, requiring Issues, enabling Actions-created PRs, opening and watching the bootstrap PR."
1212
- name: "gh aw"
1313
description: "GitHub Agentic Workflows extension (github/gh-aw) — installs and strictly compiles the Squad workflow set."
1414
when: "Installing the seven @dev workflows and compiling them into deterministic .lock.yml files."
@@ -28,6 +28,12 @@ The authoritative source is `docs/src/content/docs/guide/gh-aw.md` (mirrored at
2828
`https://bradygaster.github.io/squad/docs/guide/gh-aw/`). If that guide and this
2929
skill ever disagree, the guide wins — re-read it before proceeding.
3030

31+
GitHub Issues are a hard prerequisite: `/squad` commands arrive as issue
32+
comments, and the merged bootstrap creates a research/proposals issue. Detect
33+
and enable Issues before creating the bootstrap branch or installing workflows,
34+
so the install cannot produce a PR whose post-merge bootstrap is unable to
35+
complete.
36+
3137
**Portability contract:** resolve every repository identifier (owner, repo, default
3238
branch) **at runtime**. Never hardcode a placeholder like `{owner}/{repo}`. The only
3339
fixed identifier is the Squad source itself — `bradygaster/squad/workflows/...@dev` —
@@ -73,10 +79,37 @@ git status --short
7379
- Confirm Copilot is enabled for the repository where checkable; the activation
7480
run and the requested `@copilot` review both depend on it.
7581

76-
### 1. Allow Actions-created PRs while keeping the default token read-only
82+
### 1. Require GitHub Issues, then allow Actions-created PRs with a read-only token
7783

78-
Squad opens PRs through GitHub Actions. Enable that **without** widening the
79-
default workflow token:
84+
Check the REST API's `has_issues` field first. If Issues are disabled, enable
85+
them before touching the install:
86+
87+
```bash
88+
issues_enabled="$(gh api "repos/${owner_repo}" --jq '.has_issues')"
89+
if [ "${issues_enabled}" != "true" ]; then
90+
echo "GitHub Issues are disabled; enabling them before workflow installation."
91+
if ! gh api --method PATCH "repos/${owner_repo}" \
92+
-F has_issues=true --silent; then
93+
echo "STOP: GitHub Issues are disabled and could not be enabled." >&2
94+
echo "A repository administrator must enable Settings > General > Features > Issues, then rerun enlistment." >&2
95+
exit 1
96+
fi
97+
fi
98+
99+
test "$(gh api "repos/${owner_repo}" --jq '.has_issues')" = "true" || {
100+
echo "STOP: GitHub Issues must be enabled before installing Squad workflows." >&2
101+
exit 1
102+
}
103+
```
104+
105+
Reading `.has_issues` is non-mutating. Updating it through
106+
`PATCH /repos/{owner}/{repo}` requires repository administration permission.
107+
If the PATCH fails, **STOP before branch creation or `gh aw add`** and ask an
108+
administrator to enable **Settings → General → Features → Issues**. Do not
109+
continue with a bootstrap PR that cannot complete after merge.
110+
111+
Squad also opens PRs through GitHub Actions. Enable that **without** widening
112+
the default workflow token:
80113

81114
```bash
82115
gh api --method PUT "repos/${owner_repo}/actions/permissions/workflow" \
@@ -295,6 +328,21 @@ gh pr checks --watch
295328
owner_repo="$(gh repo view --json nameWithOwner --jq '.nameWithOwner')"
296329
default_branch="$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name')"
297330

331+
issues_enabled="$(gh api "repos/${owner_repo}" --jq '.has_issues')"
332+
if [ "${issues_enabled}" != "true" ]; then
333+
if ! gh api --method PATCH "repos/${owner_repo}" \
334+
-F has_issues=true --silent; then
335+
echo "STOP: GitHub Issues are disabled and could not be enabled." >&2
336+
echo "A repository administrator must enable Settings > General > Features > Issues, then rerun enlistment." >&2
337+
exit 1
338+
fi
339+
fi
340+
341+
test "$(gh api "repos/${owner_repo}" --jq '.has_issues')" = "true" || {
342+
echo "STOP: GitHub Issues must be enabled before installing Squad workflows." >&2
343+
exit 1
344+
}
345+
298346
gh api --method PUT "repos/${owner_repo}/actions/permissions/workflow" \
299347
-f default_workflow_permissions=read -F can_approve_pull_request_reviews=true
300348

@@ -353,6 +401,9 @@ gh pr merge --squash # auto-merge before human review. NEVER.
353401

354402
- ❌ **Hardcoding repository identifiers.** Always resolve `owner/repo` and the
355403
default branch at runtime with `gh repo view`.
404+
- ❌ **Installing while GitHub Issues are disabled.** `/squad` commands and the
405+
bootstrap research/proposals issue require Issues. Enable them first, or stop
406+
before installation if repository administration permission is unavailable.
356407
- ❌ **Blanket staging** (`git add .` / `-A` / `git commit -a`). Stage only
357408
`.gitattributes`, `.github/aw/`, `.github/workflows/`, `.github/skills/`, by path.
358409
- ❌ **Approving unknown safe updates.** Approve ONLY `SQUAD_GITHUB_APP_PRIVATE_KEY`,

0 commit comments

Comments
 (0)