Skip to content

[plan] Add verification steps and troubleshooting context #6510

@github-actions

Description

@github-actions

Objective

Add verification commands after setup steps so users can confirm their configuration is working correctly, and provide troubleshooting context for common issues.

Problem

After adding the COPILOT_GITHUB_TOKEN secret, the guide says "Your repository is now configured!" but doesn't tell users:

  • How to verify the setup worked
  • What to do if something went wrong
  • How to know if the token is valid

Additionally, the CLI commands page lacks context about when to use each command.

Approach

  1. Add verification step after token setup in Quick Start:
# Verify your setup
gh aw status

# Expected output:
# ✓ gh-aw extension: v0.x.x
# ✓ GitHub CLI: authenticated
# ✓ Repository: githubnext/gh-aw
# ✓ Copilot token: configured
  1. Add "Common Workflows" section to CLI Commands page:
### Common Workflows for Beginners

**After creating a new workflow:**
```bash
gh aw compile my-workflow.md  # Check for syntax errors
gh aw run my-workflow         # Test it manually (if workflow_dispatch enabled)
gh aw logs my-workflow        # See what happened

When something goes wrong:

gh aw status                  # Check configuration
gh aw logs my-workflow -f     # Watch live logs
gh aw audit (run-id)          # Analyze specific run (get run-id from Actions tab)
  1. Improve Safe Outputs explanation with security context:
**Safe Outputs are a security feature.** Your AI agent runs with minimal permissions (read-only). When it wants to make changes (like creating an issue), it "requests" that action. A separate, permission-controlled job reviews and executes these requests. This prevents the AI from accidentally or maliciously making unauthorized changes.

Files to Modify

  • docs/src/content/docs/setup/quick-start.mdx - Add verification commands after token setup
  • docs/src/content/docs/setup/cli.mdx - Add "Common Workflows" section with context
  • docs/src/content/docs/index.mdx or relevant concept page - Improve Safe Outputs explanation

Acceptance Criteria

  • Verification command added after token configuration step
  • Expected output shown so users know what success looks like
  • CLI Commands page includes usage context for beginners
  • Run-id explained (where to find it)
  • Safe Outputs explanation clarifies security model
  • Users can self-diagnose basic setup issues

Reference

From noob test report: Critical Issue #3 (Token Creation), Confusing Areas #4 (Safe Outputs), #5 (CLI Commands)
Related to #6505

AI generated by Plan Command for discussion #6502

Metadata

Metadata

Assignees

Labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions