Skip to content

docs: consolidate prerequisites section with verification commands - #6559

Merged
pelikhan merged 3 commits into
mainfrom
copilot/add-prerequisites-to-quick-start
Dec 15, 2025
Merged

docs: consolidate prerequisites section with verification commands#6559
pelikhan merged 3 commits into
mainfrom
copilot/add-prerequisites-to-quick-start

Conversation

Copilot AI commented Dec 15, 2025 •
edited
Loading

Copy link
Copy Markdown
Contributor

The Quick Start guide prerequisites were fragmented across three separate callout boxes, making it difficult for users to see upfront requirements.

Changes

  • Consolidated prerequisites into single checklist - All essential requirements now visible at once with ✅ checkboxes and "Why" explanations
  • Added unified verification block - Single code section with all verification commands: 
    gh --version      # Should show version 2.0.0 or higher
gh auth status    # Should show "Logged in to github.com"
git --version     # Should show git version 2.x or higher
  • Separated optional/future requirements - Discussions moved to tip callout; PAT requirement to "You'll need later" (configured in Step 3)
  • Added direct installation links - GitHub CLI and Copilot subscription links in-line

Screenshot

Prerequisites section

Before: Three boxes (Must Have, Must Configure, Will Need Later) with scattered verification commands
After: One prominent checklist with consolidated verification section

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

  • telemetry.astro.build
    • Triggering command: /opt/hostedtoolcache/node/24.11.1/x64/bin/node node /home/REDACTED/work/gh-aw/gh-aw/docs/node_modules/.bin/astro build (dns block)
    • Triggering command: /opt/hostedtoolcache/node/24.11.1/x64/bin/node node /home/REDACTED/work/gh-aw/gh-aw/docs/node_modules/.bin/astro preview (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

Original prompt

This section details on the original issue you should resolve

<issue_title>[plan] Add comprehensive prerequisites section to Quick Start guide</issue_title>
<issue_description>## Objective

Add a clear prerequisites section at the beginning of the Quick Start guide so users know what they need BEFORE attempting installation.

Problem

The Quick Start currently says "Install the extension" without explaining what needs to be in place first. Users don't know if they need GitHub CLI, a Copilot subscription, admin rights, etc.

Approach

Add a prominent prerequisites section before Step 1 in /docs/src/content/docs/setup/quick-start.mdx:

### Prerequisites

Before installing, ensure you have:

- ✅ [GitHub CLI](https://cli.github.com/) installed and authenticated (`gh auth login`)
- ✅ A GitHub repository (personal or org) with admin access
- ✅ Active [GitHub Copilot subscription](https://github.com/features/copilot) (for AI-powered workflows)
- ✅ Git installed on your machine

**Verify your setup:**
```bash
gh --version  # Should show version 2.x or higher
gh auth status  # Should show "Logged in to github.com"

Then proceed with installation:


## Files to Modify

- `docs/src/content/docs/setup/quick-start.mdx` - Add prerequisites section before installation steps

## Acceptance Criteria

- [ ] Prerequisites listed with checkboxes
- [ ] Each prerequisite has a link to installation docs
- [ ] Includes verification commands to check if prerequisites are met
- [ ] Positioned before Step 1 (installation)
- [ ] Explains WHY each prerequisite is needed (briefly)

## Reference

From noob test report: "Unclear Installation Prerequisites" - Critical Issue githubnext/gh-aw#2
Related to githubnext/gh-aw#6505




> AI generated by [Plan Command](https://github.com/githubnext/gh-aw/actions/runs/20229579821) for discussion githubnext/gh-aw#6502

<!-- agentic-workflow: Plan Command, engine: copilot, run: https://github.com/githubnext/gh-aw/actions/runs/20229579821 --></issue_description>

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

<comments>
</comments>

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

Copilot AI and others added 2 commits December 15, 2025 20:17
@mnkiefer
Initial plan: Enhance prerequisites section in Quick Start guide
68de622 
Co-authored-by: mnkiefer <8320933+mnkiefer@users.noreply.github.com>
@mnkiefer
docs: enhance prerequisites section in Quick Start guide
d23bb35 
- Consolidate prerequisites into single prominent list with checkboxes
- Add clear "Verify your setup" code block with verification commands
- Separate PAT requirement into "You'll need later" callout
- Maintain all "Why" explanations for each prerequisite
- Move Discussions to optional tip callout

Addresses #6505 acceptance criteria

Co-authored-by: mnkiefer <8320933+mnkiefer@users.noreply.github.com>
Copilot AI changed the title [WIP] Add comprehensive prerequisites section to Quick Start guide docs: consolidate prerequisites section with verification commands Dec 15, 2025
Copilot AI requested a review from mnkiefer December 15, 2025 20:24
@pelikhan
pelikhan marked this pull request as ready for review December 15, 2025 22:02
@pelikhan
pelikhan merged commit 888212b into main Dec 15, 2025
4 checks passed
@pelikhan
pelikhan deleted the copilot/add-prerequisites-to-quick-start branch December 15, 2025 22:03
This was referenced Dec 15, 2025
Merged
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@pelikhan pelikhan pelikhan approved these changes
@mnkiefer mnkiefer Awaiting requested review from mnkiefer

Assignees

@mnkiefer mnkiefer

Copilot code review Copilot

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[plan] Add comprehensive prerequisites section to Quick Start guide

3 participants

@pelikhan @mnkiefer