From bb61383c6dfd8971d06930bf3ba7ea878580be3b Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 17 Apr 2026 18:32:10 +0000 Subject: [PATCH 1/8] Initial plan From 0f0b1c18e7faac055150d064d1e54ee12c0c334f Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 17 Apr 2026 19:02:25 +0000 Subject: [PATCH 2/8] docs: clarify quick start workflow source and copilot token setup Agent-Logs-Url: https://github.com/github/gh-aw/sessions/6f98a85f-d3d5-4d3e-b23b-fcc01490470e Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- docs/astro.config.mjs | 8 +++++++ docs/src/content/docs/setup/quick-start.mdx | 24 ++++++++++++++++++++- 2 files changed, 31 insertions(+), 1 deletion(-) 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..3de811ee071 100644 --- a/docs/src/content/docs/setup/quick-start.mdx +++ b/docs/src/content/docs/setup/quick-start.mdx @@ -55,6 +55,8 @@ gh extension install github/gh-aw ### Step 2 - Add the sample workflow and trigger a run +The `gh aw add-wizard` argument uses the format `//`. In this guide, `githubnext/agentics/daily-repo-status` points to the public workflow catalog in the [`githubnext/agentics` repository](https://github.com/githubnext/agentics/tree/main/workflows), and selects `workflows/daily-repo-status.md`. + From your repository root run: ```text wrap @@ -65,10 +67,30 @@ 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 Copilot CLI inference. + +`GITHUB_TOKEN` does not include Copilot permissions, so Copilot engine runs need `COPILOT_GITHUB_TOKEN`. + +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&user_copilot_requests=read). +2. Set **Resource owner** to your personal account. +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/). From 5e82a9bd69a3aedf7e426d5991b2c8ec1dc61a28 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 17 Apr 2026 19:10:03 +0000 Subject: [PATCH 3/8] docs: refine quick start token and catalog wording Agent-Logs-Url: https://github.com/github/gh-aw/sessions/6f98a85f-d3d5-4d3e-b23b-fcc01490470e Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- docs/src/content/docs/setup/quick-start.mdx | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/src/content/docs/setup/quick-start.mdx b/docs/src/content/docs/setup/quick-start.mdx index 3de811ee071..00a1fbd7f48 100644 --- a/docs/src/content/docs/setup/quick-start.mdx +++ b/docs/src/content/docs/setup/quick-start.mdx @@ -55,7 +55,7 @@ gh extension install github/gh-aw ### Step 2 - Add the sample workflow and trigger a run -The `gh aw add-wizard` argument uses the format `//`. In this guide, `githubnext/agentics/daily-repo-status` points to the public workflow catalog in the [`githubnext/agentics` repository](https://github.com/githubnext/agentics/tree/main/workflows), and selects `workflows/daily-repo-status.md`. +The workflow reference argument to `gh aw add-wizard` uses the format `//`. In this guide, `githubnext/agentics/daily-repo-status` points to the public workflow catalog in the [`githubnext/agentics` repository](https://github.com/githubnext/agentics/tree/main/workflows), and the `daily-repo-status` workflow ID maps to `workflows/daily-repo-status.md`. From your repository root run: @@ -76,14 +76,12 @@ This will take you through an interactive process to: `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 Copilot CLI inference. - -`GITHUB_TOKEN` does not include Copilot permissions, so Copilot engine runs need `COPILOT_GITHUB_TOKEN`. +- `COPILOT_GITHUB_TOKEN` is a separate fine-grained PAT used by the Copilot CLI for inference, because `GITHUB_TOKEN` 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&user_copilot_requests=read). -2. Set **Resource owner** to your personal account. +2. Set **Resource owner** to your personal account (not an organization). `COPILOT_GITHUB_TOKEN` requires **Copilot Requests** user-level permission, which is only available for user accounts. 3. Under **Permissions → Account permissions**, set **Copilot Requests: Read**. 4. Generate the token, then save it as a repository secret named `COPILOT_GITHUB_TOKEN`. From 121035d5ff50cd2b429a695d439a8a08a4953cec Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 17 Apr 2026 19:11:43 +0000 Subject: [PATCH 4/8] docs: clarify copilot token platform requirement Agent-Logs-Url: https://github.com/github/gh-aw/sessions/6f98a85f-d3d5-4d3e-b23b-fcc01490470e Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- docs/src/content/docs/setup/quick-start.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/content/docs/setup/quick-start.mdx b/docs/src/content/docs/setup/quick-start.mdx index 00a1fbd7f48..adc296b93a4 100644 --- a/docs/src/content/docs/setup/quick-start.mdx +++ b/docs/src/content/docs/setup/quick-start.mdx @@ -81,7 +81,7 @@ This will take you through an interactive process to: 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&user_copilot_requests=read). -2. Set **Resource owner** to your personal account (not an organization). `COPILOT_GITHUB_TOKEN` requires **Copilot Requests** user-level permission, which is only available for user accounts. +2. Set **Resource owner** to your personal account (not an organization). This is a GitHub platform requirement: `COPILOT_GITHUB_TOKEN` needs **Copilot Requests** user-level permission, which is only available for user accounts. 3. Under **Permissions → Account permissions**, set **Copilot Requests: Read**. 4. Generate the token, then save it as a repository secret named `COPILOT_GITHUB_TOKEN`. From f351f747617fd60f5b01c440103cd3d692c004b9 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 17 Apr 2026 19:13:23 +0000 Subject: [PATCH 5/8] docs: improve quick start readability for new users Agent-Logs-Url: https://github.com/github/gh-aw/sessions/6f98a85f-d3d5-4d3e-b23b-fcc01490470e Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- docs/src/content/docs/setup/quick-start.mdx | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/src/content/docs/setup/quick-start.mdx b/docs/src/content/docs/setup/quick-start.mdx index adc296b93a4..505acce63e3 100644 --- a/docs/src/content/docs/setup/quick-start.mdx +++ b/docs/src/content/docs/setup/quick-start.mdx @@ -55,7 +55,8 @@ 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 `//`. In this guide, `githubnext/agentics/daily-repo-status` points to the public workflow catalog in the [`githubnext/agentics` repository](https://github.com/githubnext/agentics/tree/main/workflows), and the `daily-repo-status` workflow ID maps to `workflows/daily-repo-status.md`. +The workflow reference argument to `gh aw add-wizard` uses the format `//`. +In this guide, `githubnext/agentics/daily-repo-status` points to the public workflow catalog in the [`githubnext/agentics` repository](https://github.com/githubnext/agentics/tree/main/workflows). The `daily-repo-status` workflow ID maps to `workflows/daily-repo-status.md`. From your repository root run: @@ -81,7 +82,8 @@ This will take you through an interactive process to: 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&user_copilot_requests=read). -2. Set **Resource owner** to your personal account (not an organization). This is a GitHub platform requirement: `COPILOT_GITHUB_TOKEN` needs **Copilot Requests** user-level permission, which is only available for user accounts. +2. Set **Resource owner** to your personal account (not an organization). + This is required by the GitHub platform: `COPILOT_GITHUB_TOKEN` needs **Copilot Requests** user-level permission, which is only available for user accounts. 3. Under **Permissions → Account permissions**, set **Copilot Requests: Read**. 4. Generate the token, then save it as a repository secret named `COPILOT_GITHUB_TOKEN`. From 54ec68dd5d5d18942ac4fdc1e8e5cb74fa0f6d0e Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 17 Apr 2026 19:15:14 +0000 Subject: [PATCH 6/8] docs: clarify workflow id format in quick start Agent-Logs-Url: https://github.com/github/gh-aw/sessions/6f98a85f-d3d5-4d3e-b23b-fcc01490470e Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- docs/src/content/docs/setup/quick-start.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/src/content/docs/setup/quick-start.mdx b/docs/src/content/docs/setup/quick-start.mdx index 505acce63e3..a4a7ee8d7fc 100644 --- a/docs/src/content/docs/setup/quick-start.mdx +++ b/docs/src/content/docs/setup/quick-start.mdx @@ -56,7 +56,8 @@ 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 `//`. -In this guide, `githubnext/agentics/daily-repo-status` points to the public workflow catalog in the [`githubnext/agentics` repository](https://github.com/githubnext/agentics/tree/main/workflows). The `daily-repo-status` workflow ID maps to `workflows/daily-repo-status.md`. +`` is the workflow filename without `.md`. +In this guide, `githubnext/agentics/daily-repo-status` points to the public workflow catalog in the [`githubnext/agentics` repository](https://github.com/githubnext/agentics/tree/main/workflows), where `daily-repo-status` maps to `workflows/daily-repo-status.md`. From your repository root run: From 153de96cdb510d763e7653578d7e0ee482ce54f9 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 17 Apr 2026 19:17:01 +0000 Subject: [PATCH 7/8] docs: polish quick start onboarding wording Agent-Logs-Url: https://github.com/github/gh-aw/sessions/6f98a85f-d3d5-4d3e-b23b-fcc01490470e Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- docs/src/content/docs/setup/quick-start.mdx | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/src/content/docs/setup/quick-start.mdx b/docs/src/content/docs/setup/quick-start.mdx index a4a7ee8d7fc..6ce5632dacf 100644 --- a/docs/src/content/docs/setup/quick-start.mdx +++ b/docs/src/content/docs/setup/quick-start.mdx @@ -57,7 +57,7 @@ gh extension install github/gh-aw 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 workflow catalog in the [`githubnext/agentics` repository](https://github.com/githubnext/agentics/tree/main/workflows), where `daily-repo-status` maps to `workflows/daily-repo-status.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: @@ -78,13 +78,12 @@ This will take you through an interactive process to: `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` does not include Copilot-specific permissions. +- `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&user_copilot_requests=read). -2. Set **Resource owner** to your personal account (not an organization). - This is required by the GitHub platform: `COPILOT_GITHUB_TOKEN` needs **Copilot Requests** user-level permission, which is only available for user accounts. +2. Set **Resource owner** to your personal account (not an organization). This is required by the GitHub platform: `COPILOT_GITHUB_TOKEN` needs **Copilot Requests** user-level permission, which is only available for user accounts. 3. Under **Permissions → Account permissions**, set **Copilot Requests: Read**. 4. Generate the token, then save it as a repository secret named `COPILOT_GITHUB_TOKEN`. From bc87bea0946eb1064e3d51018a388ffa0a28ac22 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 17 Apr 2026 19:18:47 +0000 Subject: [PATCH 8/8] docs: fix copilot token setup link and owner guidance Agent-Logs-Url: https://github.com/github/gh-aw/sessions/6f98a85f-d3d5-4d3e-b23b-fcc01490470e Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- docs/src/content/docs/setup/quick-start.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/src/content/docs/setup/quick-start.mdx b/docs/src/content/docs/setup/quick-start.mdx index 6ce5632dacf..915f42475ba 100644 --- a/docs/src/content/docs/setup/quick-start.mdx +++ b/docs/src/content/docs/setup/quick-start.mdx @@ -82,8 +82,8 @@ This will take you through an interactive process to: 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&user_copilot_requests=read). -2. Set **Resource owner** to your personal account (not an organization). This is required by the GitHub platform: `COPILOT_GITHUB_TOKEN` needs **Copilot Requests** user-level permission, which is only available for user accounts. +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`.