githubnext / githubnext/gh-aw-workshop

[workflow-editor] Fix broken numbered heading cross-references to shared validation section

Closed
#3,433 0 comments 0 reactions 0 assignees View on GitHub
agentic-workflows documentation workflow-editor
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.