Skip to content

Conversation

Copy link
Contributor

Copilot AI commented Nov 18, 2025

Thanks for assigning this issue to me. I'm starting to work on it and will keep this PR's description up to date as I form a plan and make progress.

Original prompt

This section details on the original issue you should resolve

<issue_title>[task] Add "Verify Your Setup" section to Quick Start</issue_title>
<issue_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:

  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</issue_description>

Comments on the Issue (you are @copilot in this section)


💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

@pelikhan pelikhan closed this Nov 18, 2025
Copilot AI requested a review from pelikhan November 18, 2025 08:03
@pelikhan pelikhan deleted the copilot/add-verify-your-setup-section branch December 15, 2025 04:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

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

2 participants