Skip to content

[task] Add "Verify Your Setup" section to Quick Start #4261

@github-actions

Description

@github-actions

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:

  1. Commands to verify installation
  2. How to run a test workflow
  3. Where to view results
  4. 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 enabled

Acceptance 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

Metadata

Metadata

Assignees

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions