githubnext / githubnext/gh-aw-workshop
[workflow-editor] Fix broken numbered heading cross-references to shared validation section
- Dominant language
- JavaScript
- Stars
- 47
- Forks
- 19
- Avg merge
- 8h 54m
- Merged PRs (30d)
- 50
Description
> [!CAUTION]
> Protected files were modified in this change.
> This pull request is in `request_review` mode and requires explicit human scrutiny before merge.
>
> Protected files: `.github/workflows/security-side-quest.lock.yml`, `.github/workflows/security-side-quest.md`, `.github/workflows/side-quest.lock.yml`, `.github/workflows/side-quest.md`, `.github/workflows/workshop-skill-activity-author.lock.yml`, `.github/workflows/workshop-skill-activity-author.md`
## What changed
Three workflow files pointed to a numbered heading — `### 5. Validate agentic
workflow snippets` — in `workshop-author.md` as their shared validation
procedure. The real heading in `workshop-author.md` is
`### Validate agentic workflow snippets` (no number, matching this repo's own
"no numbered headers" guideline). The stale numeric reference meant an agent
following the cross-reference would not reliably locate the intended section.
## Files changed
- `.github/workflows/side-quest.md`
- `.github/workflows/security-side-quest.md`
- `.github/workflows/workshop-skill-activity-author.md`
- Regenerated matching `*.lock.yml` files via `gh aw compile --validate`
## Why this is more Skills-like
The fix is purely subtractive/corrective: it removes an incorrect, hard-coded
number from prose and replaces it with the exact heading text, so the
cross-reference is accurate and self-documenting — short, direct, and free of
duplication, consistent with GitHub Skills lesson conventions.
## Validation
Ran `gh aw compile .github/workflows/side-quest.md
.github/workflows/security-side-quest.md
.github/workflows/workshop-skill-activity-author.md --validate` — all three
compiled successfully (pre-existing, unrelated `concurrency.job-discriminator`
warnings only).
> [!WARNING]
>
> Firewall blocked 1 domain
>
> The following domain was blocked by the firewall during workflow execution:
>
> - `api.github.com`
>
> [!TIP]
> `api.github.com` is blocked because GitHub API access uses the built-in GitHub tools by default. Instead of adding `api.github.com` to `network.allowed`, use `tools.github.mode: gh-proxy` for direct pre-authenticated GitHub CLI access without requiring network access to `api.github.com`:
>
> ```yaml
> tools:
> github:
> mode: gh-proxy
> ```
>
> See [GitHub Tools](https://github.github.com/gh-aw/reference/github-tools/) for more information on `gh-proxy` mode.
>
> To allow these domains, add them to the `network.allowed` list in your workflow frontmatter:
>
> ```yaml
> network:
> allowed:
> - defaults
> - "api.github.com"
> ```
>
> See [Network Configuration](https://github.github.com/gh-aw/reference/network/) for more information.
>
>
> Generated by [✂️ Workflow Skills Editor](https://github.com/githubnext/gh-aw-workshop/actions/runs/35068983695) · copilot · auto · 69.5 AIC · ⌖ 9.07 AIC · ⊞ 7.9K · [◷](https://github.com/search?q=repo%3Agithubnext%2Fgh-aw-workshop+%22gh-aw-workflow-id%3A+workflow-skills-editor%22&type=pullrequests)
> - [x] expires on Sep 17, 2026, 7:40 AM UTC
---
> [!NOTE]
> This was originally intended as a pull request, but the git push operation failed.
>
> **Original error:** The process '/usr/bin/git' failed with exit code 1
>
> **Workflow Run:** [View run details and download bundle artifact](https://github.com/githubnext/gh-aw-workshop/actions/runs/35068983695)
>
> The bundle file is available in the `agent` artifact in the workflow run linked above.
Create the pull request manually
```sh
# Download the artifact from the workflow run
gh run download '35068983695' -n agent -D '/tmp/agent-35068983695'
# Resolve the bundle source ref, fetch it into a temporary ref, then create the local branch
bundle_path='/tmp/agent-35068983695/aw-workflow-editor-fix-broken-snippet-validation-xref.bundle'
temp_ref='refs/bundles/create-pr-workflow-editor-fix-broken-snippet-validation-xref-8e3ca564e80af6d5-d1629689'
target_ref='refs/heads/workflow-editor/fix-broken-snippet-validation-xref-8e3ca564e80af6d5'
bundle_source_ref=$(git bundle list-heads "$bundle_path" | awk '$2 ~ /^refs\/heads\// { print $2 }')
if [ -z "$bundle_source_ref" ]; then
bundle_source_ref=$(git bundle list-heads "$bundle_path" | awk '$2 == "HEAD" { print $2 }')
fi
if [ "$(printf '%s\n' "$bundle_source_ref" | sed '/^$/d' | wc -l | tr -d ' ')" != "1" ]; then
echo "Expected exactly one bundle source ref, found: $bundle_source_ref" >&2
exit 1
fi
git fetch "$bundle_path" "${bundle_source_ref}:${temp_ref}"
git update-ref "$target_ref" "$temp_ref"
git checkout 'workflow-editor/fix-broken-snippet-validation-xref-8e3ca564e80af6d5'
# Ensure the working tree matches the updated branch
git reset --hard
# Remove the temporary bundle ref
git update-ref -d "$temp_ref"
# Push the branch to the target remote
git push 'origin' 'workflow-editor/fix-broken-snippet-validation-xref-8e3ca564e80af6d5'
# Create the pull request
gh pr create --title '[workflow-editor] Fix broken numbered heading cross-references to shared validation section' --base 'main' --head 'workflow-editor/fix-broken-snippet-validation-xref-8e3ca564e80af6d5' --repo 'githubnext/gh-aw-workshop'
```
Contributor guide
No contributing guide indexed for this repository
Research direction
Read the cross-references in `.github/workflows/side-quest.md`, `.github/workflows/security-side-quest.md`, and `.github/workflows/workshop-skill-activity-author.md`, then compare them with the heading in `workshop-author.md`. Run `gh aw compile` with `--validate` on the three workflow files; done means the references use the unnumbered heading and the matching lock files are regenerated successfully.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- github-actions
- Domain
- ci-cd
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 35/100