diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index e4acbc20730..c209f42a7e1 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -245,6 +245,14 @@ export default defineConfig({ }) ], sidebar: [ + { + label: 'New here? Start with these 3 pages', + items: [ + { label: '1. Quick Start', link: '/setup/quick-start/' }, + { label: '2. How Agentic Workflows Work', link: '/introduction/how-they-work/' }, + { label: '3. FAQ', link: '/reference/faq/' }, + ], + }, { label: 'Introduction', autogenerate: { directory: 'introduction' }, diff --git a/docs/src/content/docs/setup/quick-start.mdx b/docs/src/content/docs/setup/quick-start.mdx index 08824e86f6c..915f42475ba 100644 --- a/docs/src/content/docs/setup/quick-start.mdx +++ b/docs/src/content/docs/setup/quick-start.mdx @@ -55,6 +55,10 @@ gh extension install github/gh-aw ### Step 2 - Add the sample workflow and trigger a run +The workflow reference argument to `gh aw add-wizard` uses the format `//`. +`` is the workflow filename without `.md`. +In this guide, `githubnext/agentics/daily-repo-status` points to the public [`githubnext/agentics` workflow catalog](https://github.com/githubnext/agentics/tree/main/workflows), where `daily-repo-status` maps to `workflows/daily-repo-status.md`. + From your repository root run: ```text wrap @@ -65,10 +69,28 @@ This will take you through an interactive process to: 1. **Check prerequisites** - Verify repository permissions. 2. **Select an AI Engine** - Choose between Copilot, Claude, or Codex. -3. **Set up the required secret** - [`COPILOT_GITHUB_TOKEN`](/gh-aw/reference/auth/#copilot_github_token) (a separate GitHub token with Copilot access — distinct from the default `GITHUB_TOKEN`), [`ANTHROPIC_API_KEY`](/gh-aw/reference/auth/#anthropic_api_key), or [`OPENAI_API_KEY`](/gh-aw/reference/auth/#openai_api_key). See [Authentication](/gh-aw/reference/auth/) for setup instructions. +3. **Set up the required secret** - [`COPILOT_GITHUB_TOKEN`](/gh-aw/reference/auth/#copilot_github_token), [`ANTHROPIC_API_KEY`](/gh-aw/reference/auth/#anthropic_api_key), or [`OPENAI_API_KEY`](/gh-aw/reference/auth/#openai_api_key). See [Authentication](/gh-aw/reference/auth/) and [Token Reference](/gh-aw/reference/tokens/) for details. 4. **Add the workflow** - Adds the workflow and lock file to `.github/workflows/`. 5. **Optionally trigger an initial run** - Starts the workflow immediately. +#### If you choose Copilot, create `COPILOT_GITHUB_TOKEN` first + +`GITHUB_TOKEN` and `COPILOT_GITHUB_TOKEN` are different tokens with different jobs: + +- `GITHUB_TOKEN` is created automatically by GitHub Actions for repository operations. +- `COPILOT_GITHUB_TOKEN` is a separate fine-grained PAT used by the Copilot CLI for inference, because `GITHUB_TOKEN` is scoped to repository operations and does not include Copilot-specific permissions. + +To create it: + +1. Open [Create fine-grained PAT for `COPILOT_GITHUB_TOKEN`](https://github.com/settings/personal-access-tokens/new?name=COPILOT_GITHUB_TOKEN&description=GitHub+Agentic+Workflows+-+Copilot+engine+authentication). +2. Set **Resource owner** to your personal account. The **Copilot Requests** permission is user-level and cannot be granted to organization-scoped tokens. +3. Under **Permissions → Account permissions**, set **Copilot Requests: Read**. +4. Generate the token, then save it as a repository secret named `COPILOT_GITHUB_TOKEN`. + + ```text wrap + gh aw secrets set COPILOT_GITHUB_TOKEN --value "" + ``` + > [!TIP] > **Having trouble?** Check your [repository secrets](/gh-aw/reference/auth/), see the [FAQ](/gh-aw/reference/faq/) and [Common Issues](/gh-aw/troubleshooting/common-issues/).