-
Notifications
You must be signed in to change notification settings - Fork 36
Closed as not planned
Labels
Description
Objective
Add a verification section at the end of Quick Start that helps users confirm their installation works and shows them what to do next.
Context
After completing Quick Start, beginners don't know:
- How to verify installation worked
- Where to see results
- What to try first
Related to #4257 (Documentation Noob Test Report)
Approach
Add a new section after the installation steps in Quick Start with:
- Commands to verify installation
- How to run a test workflow
- Where to view results
- Next steps suggestions
Files to Modify
docs/src/content/docs/setup/quick-start.mdx
Implementation Details
Add this section before "Next Steps":
## Verify Your Setup
### 1. Check Installation
Verify gh-aw is installed correctly:
\`\`\`bash
gh aw --version
\`\`\`
Expected output: Version number (e.g., `0.0.350`)
### 2. Run a Test Workflow
Try compiling the example workflow:
\`\`\`bash
# Create a test workflow
mkdir -p .github/workflows
cat > .github/workflows/hello.md << 'EOF'
---
on: workflow_dispatch
permissions:
contents: read
engine: copilot
---
# Hello World
Create a simple greeting message.
EOF
# Compile it
gh aw compile hello
\`\`\`
### 3. Check Results
Look for the compiled workflow:
\`\`\`bash
ls -la .github/workflows/hello.lock.yml
\`\`\`
You should see the generated GitHub Actions YAML file.
### 4. View in GitHub
1. Commit and push the files
2. Go to your repository's Actions tab
3. Find "Hello World" in the workflows list
4. Click "Run workflow" to test it
### What To Expect
- Compilation should complete in 1-2 seconds
- The `.lock.yml` file contains GitHub Actions YAML
- First workflow run may take 2-5 minutes
- Results appear in the Actions tab
### Troubleshooting
**If `gh aw --version` fails:**
- Reinstall: `gh extension install githubnext/gh-aw --force`
**If compilation fails:**
- Check YAML syntax in the frontmatter
- Run with verbose flag: `gh aw compile hello --verbose`
**If workflow doesn't appear:**
- Ensure files are committed and pushed
- Check repository has Actions enabledAcceptance Criteria
- Verification section is added after installation steps
- Commands to check installation are provided
- Test workflow example is included
- Expected output is described
- Troubleshooting common issues is included
- Links to Actions tab are clear
- Documentation builds without errors
Priority
HIGH - Identified as Quick Win #3 with high impact for new users
AI generated by Plan Command for discussion #4257
Copilot