From e85c5cf6bfc92110a008b5f3c474e2a9c576d049 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 20 Dec 2025 18:54:26 +0000 Subject: [PATCH 1/7] Initial plan From cf1f5a51750b5d06a76aaf9d0658982e769de85b Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 20 Dec 2025 18:58:19 +0000 Subject: [PATCH 2/7] Add comprehensive token configuration instructions to README Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- README.md | 197 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 197 insertions(+) diff --git a/README.md b/README.md index ac1a692..3d270f0 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,199 @@ # agentics-template A template to get started with GitHub Agentic Workflows + +## Getting Started + +This repository is a template for creating GitHub Agentic Workflows. Agentic workflows allow you to use AI agents (like GitHub Copilot) to automate tasks in your repository. + +## Configuring Tokens for Agentic Workflows + +GitHub Agentic Workflows require specific tokens to authenticate with various services. GitHub Actions always provides `GITHUB_TOKEN` automatically, but for advanced features like Copilot workflows, you'll need to configure additional tokens. + +### Quick Start: Tokens You Need to Configure + +Create these repository secrets based on what features you need: + +| When you need this... | Secret to create | Notes | +|----------------------|------------------|-------| +| Cross-repo Project Ops / remote GitHub tools | `GH_AW_GITHUB_TOKEN` | PAT or app token with cross-repo access | +| Copilot workflows (CLI, engine, agent tasks, etc.) | `COPILOT_GITHUB_TOKEN` | Needs Copilot Requests permission and repo access | +| Assigning agents/bots to issues or pull requests | `GH_AW_AGENT_TOKEN` | Used by `assign-to-agent` and Copilot assignee/reviewer flows | +| Any GitHub Projects v2 operations | `GH_AW_PROJECT_GITHUB_TOKEN` | **Required** for `update-project`. Default `GITHUB_TOKEN` cannot access Projects v2 API | +| Isolating MCP server permissions (advanced optional) | `GH_AW_GITHUB_MCP_SERVER_TOKEN` | Only if you want MCP to use a different token than other jobs | + +### Step-by-Step: Configuring Tokens for Copilot + +Follow these steps to set up GitHub Copilot in your agentic workflows: + +#### 1. Install the GitHub Agentic Workflows CLI + +```bash +gh extension install githubnext/gh-aw +``` + +If you encounter authentication issues, use the standalone installer: + +```bash +curl -O https://raw.githubusercontent.com/githubnext/gh-aw/main/install-gh-aw.sh +chmod +x install-gh-aw.sh +./install-gh-aw.sh +``` + +#### 2. Create a Personal Access Token for Copilot + +1. Go to [GitHub Personal Access Tokens settings](https://github.com/settings/personal-access-tokens/new) +2. Configure the token: + - **Resource owner**: Your user account (not organization) + - **Repository access**: "Public repositories" or select specific repos + - **Permissions**: Select "Copilot Requests" (required) +3. Generate the token and copy it + +#### 3. Set the Copilot Token as a Repository Secret + +Use the CLI to create the secret in your repository: + +```bash +# Set COPILOT_GITHUB_TOKEN for the current repository +gh aw secrets set COPILOT_GITHUB_TOKEN --value "YOUR_COPILOT_PAT" + +# Alternative: Use environment variable +export MY_COPILOT_TOKEN="YOUR_COPILOT_PAT" +gh aw secrets set COPILOT_GITHUB_TOKEN --value-from-env MY_COPILOT_TOKEN + +# Alternative: Pipe from stdin +echo "YOUR_COPILOT_PAT" | gh aw secrets set COPILOT_GITHUB_TOKEN +``` + +#### 4. (Optional) Configure Additional Tokens + +If you need additional capabilities, configure these tokens: + +```bash +# For cross-repository operations +gh aw secrets set GH_AW_GITHUB_TOKEN --value "YOUR_PAT" + +# For agent assignment operations +gh aw secrets set GH_AW_AGENT_TOKEN --value "YOUR_AGENT_PAT" + +# For GitHub Projects v2 operations +gh aw secrets set GH_AW_PROJECT_GITHUB_TOKEN --value "YOUR_PROJECT_PAT" +``` + +#### 5. Use the Bootstrap Helper + +Check which tokens are configured and get recommendations: + +```bash +# Check which recommended token secrets exist +gh aw secrets bootstrap + +# Initialize repository with token checks for specific engine +gh aw init --tokens --engine copilot +``` + +### Token Types and Permissions + +#### `COPILOT_GITHUB_TOKEN` (Copilot Authentication) + +**Required for:** +- `engine: copilot` workflows +- `create-agent-task:` safe outputs +- Assigning `copilot` as issue assignee +- Adding `copilot` as PR reviewer + +**Required permissions:** +- Copilot Requests (required) +- Repository access (read or write depending on use case) + +#### `GH_AW_GITHUB_TOKEN` (Enhanced PAT) + +**Required for:** +- Cross-repository operations +- Remote GitHub tools mode +- Codex engine operations with GitHub MCP + +**Required permissions:** +- Contents: Read (minimum) or Read+Write (for PRs) +- Issues: Read+Write (for issue operations) +- Pull requests: Read+Write (for PR operations) + +#### `GH_AW_AGENT_TOKEN` (Agent Assignment) + +**Required for:** +- `assign-to-agent:` safe outputs +- Programmatic agent assignment operations + +**Required permissions:** +- Actions: Write +- Contents: Write +- Issues: Write +- Pull requests: Write + +#### `GH_AW_PROJECT_GITHUB_TOKEN` (GitHub Projects v2) + +**Required for:** +- Any GitHub Projects v2 operations +- `update-project` safe outputs + +**Required permissions:** +- For User-owned Projects: Classic PAT with `project` scope +- For Organization-owned Projects: Classic PAT with `project` + `read:org` scopes, OR fine-grained PAT with explicit Organization access + Projects: Read+Write + +### Security Best Practices + +1. **Use least privilege**: Grant tokens only the permissions they need +2. **Scope permissions at the job level**: Use `permissions:` in your workflow to limit token scope + ```yaml + permissions: + contents: read + pull-requests: write + ``` +3. **Use fine-grained PATs**: Prefer fine-grained Personal Access Tokens over classic PATs when possible +4. **Limit repository access**: Only grant access to repositories that need it +5. **Use GitHub Environments**: For sensitive tokens, use GitHub Environments with required reviewers +6. **Rotate tokens regularly**: Update your tokens periodically for better security + +### Example Workflow Using Copilot + +Here's a simple workflow that uses Copilot to respond to issue comments: + +```yaml +--- +on: + issue_comment: + types: [created] +permissions: + contents: read + issues: write +engine: copilot +--- + +# Copilot Issue Helper + +Respond to the user's comment on issue #${{ github.event.issue.number }}: + +"${{ needs.activation.outputs.text }}" + +Provide a helpful response based on the repository context. +``` + +After creating this workflow file (e.g., `.github/workflows/copilot-helper.md`), compile it: + +```bash +gh aw compile copilot-helper +``` + +This will generate `.github/workflows/copilot-helper.lock.yml` which GitHub Actions will run. + +## Next Steps + +1. **Explore the documentation**: Check `.github/aw/github-agentic-workflows.md` for comprehensive workflow documentation +2. **Create your first workflow**: Start with a simple workflow and iterate +3. **Test in a safe environment**: Use a test repository to experiment +4. **Monitor usage**: Use `gh aw logs` to track workflow runs and costs + +## Additional Resources + +- [GitHub Agentic Workflows Documentation](https://githubnext.github.io/gh-aw/) +- [Token Reference](https://github.com/githubnext/gh-aw/blob/main/docs/src/content/docs/reference/tokens.md) +- [CLI Documentation](https://githubnext.github.io/gh-aw/setup/cli/) From 82c5204b2e757ef99d7ca5e88b1b8f8787fb5fff Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 20 Dec 2025 18:59:34 +0000 Subject: [PATCH 3/7] Clarify workflow file format and add note about activation context Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 3d270f0..faebf7c 100644 --- a/README.md +++ b/README.md @@ -177,13 +177,15 @@ Respond to the user's comment on issue #${{ github.event.issue.number }}: Provide a helpful response based on the repository context. ``` -After creating this workflow file (e.g., `.github/workflows/copilot-helper.md`), compile it: +> **Note**: The `needs.activation.outputs.text` variable is automatically provided by the agentic workflows system. It contains sanitized content from the triggering event (in this case, the comment body) with security protections against @mentions and code injection. + +After creating this workflow file as `.github/workflows/copilot-helper.md` (note: agentic workflows use `.md` files, not `.yml`), compile it: ```bash gh aw compile copilot-helper ``` -This will generate `.github/workflows/copilot-helper.lock.yml` which GitHub Actions will run. +This will generate `.github/workflows/copilot-helper.lock.yml`, which is the actual GitHub Actions workflow file that will run. ## Next Steps From 3a2f2461f31301bf32f041d761d08b7bd7e1063c Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 20 Dec 2025 19:01:05 +0000 Subject: [PATCH 4/7] Address code review nitpicks for improved clarity Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- README.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index faebf7c..d119491 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ Create these repository secrets based on what features you need: | When you need this... | Secret to create | Notes | |----------------------|------------------|-------| -| Cross-repo Project Ops / remote GitHub tools | `GH_AW_GITHUB_TOKEN` | PAT or app token with cross-repo access | +| Cross-repo operations / remote GitHub tools | `GH_AW_GITHUB_TOKEN` | PAT or app token with cross-repo access | | Copilot workflows (CLI, engine, agent tasks, etc.) | `COPILOT_GITHUB_TOKEN` | Needs Copilot Requests permission and repo access | | Assigning agents/bots to issues or pull requests | `GH_AW_AGENT_TOKEN` | Used by `assign-to-agent` and Copilot assignee/reviewer flows | | Any GitHub Projects v2 operations | `GH_AW_PROJECT_GITHUB_TOKEN` | **Required** for `update-project`. Default `GITHUB_TOKEN` cannot access Projects v2 API | @@ -137,7 +137,8 @@ gh aw init --tokens --engine copilot **Required permissions:** - For User-owned Projects: Classic PAT with `project` scope -- For Organization-owned Projects: Classic PAT with `project` + `read:org` scopes, OR fine-grained PAT with explicit Organization access + Projects: Read+Write +- For Organization-owned Projects (option 1): Classic PAT with `project` + `read:org` scopes +- For Organization-owned Projects (option 2): Fine-grained PAT with explicit Organization access + Projects: Read+Write ### Security Best Practices @@ -177,7 +178,7 @@ Respond to the user's comment on issue #${{ github.event.issue.number }}: Provide a helpful response based on the repository context. ``` -> **Note**: The `needs.activation.outputs.text` variable is automatically provided by the agentic workflows system. It contains sanitized content from the triggering event (in this case, the comment body) with security protections against @mentions and code injection. +> **Note**: The `needs.activation.outputs.text` variable is automatically provided by the agentic workflows system. It contains sanitized content from the triggering event (in this case, the comment body) with security protections including @mention neutralization (converts `@user` to `` `@user` ``), bot trigger protection, XML tag safety, and URI filtering. After creating this workflow file as `.github/workflows/copilot-helper.md` (note: agentic workflows use `.md` files, not `.yml`), compile it: From 5a3291cd2674877292f7a59e9f0c16995e67f855 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 20 Dec 2025 19:09:20 +0000 Subject: [PATCH 5/7] Address feedback: use GitHub web UI for secrets, reorder steps, remove CLI installation and security section Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- README.md | 80 ++++++++++--------------------------------------------- 1 file changed, 14 insertions(+), 66 deletions(-) diff --git a/README.md b/README.md index d119491..e1e3ff0 100644 --- a/README.md +++ b/README.md @@ -25,21 +25,7 @@ Create these repository secrets based on what features you need: Follow these steps to set up GitHub Copilot in your agentic workflows: -#### 1. Install the GitHub Agentic Workflows CLI - -```bash -gh extension install githubnext/gh-aw -``` - -If you encounter authentication issues, use the standalone installer: - -```bash -curl -O https://raw.githubusercontent.com/githubnext/gh-aw/main/install-gh-aw.sh -chmod +x install-gh-aw.sh -./install-gh-aw.sh -``` - -#### 2. Create a Personal Access Token for Copilot +#### 1. Create a Personal Access Token for Copilot 1. Go to [GitHub Personal Access Tokens settings](https://github.com/settings/personal-access-tokens/new) 2. Configure the token: @@ -48,48 +34,24 @@ chmod +x install-gh-aw.sh - **Permissions**: Select "Copilot Requests" (required) 3. Generate the token and copy it -#### 3. Set the Copilot Token as a Repository Secret - -Use the CLI to create the secret in your repository: +#### 2. Set the Copilot Token as a Repository Secret -```bash -# Set COPILOT_GITHUB_TOKEN for the current repository -gh aw secrets set COPILOT_GITHUB_TOKEN --value "YOUR_COPILOT_PAT" +Add the token as a repository secret using the GitHub website: -# Alternative: Use environment variable -export MY_COPILOT_TOKEN="YOUR_COPILOT_PAT" -gh aw secrets set COPILOT_GITHUB_TOKEN --value-from-env MY_COPILOT_TOKEN +1. Go to your repository on GitHub +2. Click **Settings** > **Secrets and variables** > **Actions** +3. Click **New repository secret** +4. Set the name to `COPILOT_GITHUB_TOKEN` +5. Paste your Personal Access Token in the **Secret** field +6. Click **Add secret** -# Alternative: Pipe from stdin -echo "YOUR_COPILOT_PAT" | gh aw secrets set COPILOT_GITHUB_TOKEN -``` +#### 3. (Optional) Configure Additional Tokens -#### 4. (Optional) Configure Additional Tokens +If you need additional capabilities, add these tokens as repository secrets following the same steps above: -If you need additional capabilities, configure these tokens: - -```bash -# For cross-repository operations -gh aw secrets set GH_AW_GITHUB_TOKEN --value "YOUR_PAT" - -# For agent assignment operations -gh aw secrets set GH_AW_AGENT_TOKEN --value "YOUR_AGENT_PAT" - -# For GitHub Projects v2 operations -gh aw secrets set GH_AW_PROJECT_GITHUB_TOKEN --value "YOUR_PROJECT_PAT" -``` - -#### 5. Use the Bootstrap Helper - -Check which tokens are configured and get recommendations: - -```bash -# Check which recommended token secrets exist -gh aw secrets bootstrap - -# Initialize repository with token checks for specific engine -gh aw init --tokens --engine copilot -``` +- **For cross-repository operations**: Create a secret named `GH_AW_GITHUB_TOKEN` +- **For agent assignment operations**: Create a secret named `GH_AW_AGENT_TOKEN` +- **For GitHub Projects v2 operations**: Create a secret named `GH_AW_PROJECT_GITHUB_TOKEN` ### Token Types and Permissions @@ -140,20 +102,6 @@ gh aw init --tokens --engine copilot - For Organization-owned Projects (option 1): Classic PAT with `project` + `read:org` scopes - For Organization-owned Projects (option 2): Fine-grained PAT with explicit Organization access + Projects: Read+Write -### Security Best Practices - -1. **Use least privilege**: Grant tokens only the permissions they need -2. **Scope permissions at the job level**: Use `permissions:` in your workflow to limit token scope - ```yaml - permissions: - contents: read - pull-requests: write - ``` -3. **Use fine-grained PATs**: Prefer fine-grained Personal Access Tokens over classic PATs when possible -4. **Limit repository access**: Only grant access to repositories that need it -5. **Use GitHub Environments**: For sensitive tokens, use GitHub Environments with required reviewers -6. **Rotate tokens regularly**: Update your tokens periodically for better security - ### Example Workflow Using Copilot Here's a simple workflow that uses Copilot to respond to issue comments: From 1f45b882671ccfbd7130c40e8016692b999fd92c Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 20 Dec 2025 19:22:50 +0000 Subject: [PATCH 6/7] Remove example workflow and next steps sections, add workflow creation and debugging sections Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- README.md | 51 +++++++++++++++++---------------------------------- 1 file changed, 17 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index e1e3ff0..4d8e13c 100644 --- a/README.md +++ b/README.md @@ -102,46 +102,29 @@ If you need additional capabilities, add these tokens as repository secrets foll - For Organization-owned Projects (option 1): Classic PAT with `project` + `read:org` scopes - For Organization-owned Projects (option 2): Fine-grained PAT with explicit Organization access + Projects: Read+Write -### Example Workflow Using Copilot +## Creating Workflows -Here's a simple workflow that uses Copilot to respond to issue comments: +### Using the Create Agentic Workflow Agent -```yaml ---- -on: - issue_comment: - types: [created] -permissions: - contents: read - issues: write -engine: copilot ---- +The easiest way to create a new agentic workflow is to use the built-in custom agent: -# Copilot Issue Helper - -Respond to the user's comment on issue #${{ github.event.issue.number }}: - -"${{ needs.activation.outputs.text }}" - -Provide a helpful response based on the repository context. -``` - -> **Note**: The `needs.activation.outputs.text` variable is automatically provided by the agentic workflows system. It contains sanitized content from the triggering event (in this case, the comment body) with security protections including @mention neutralization (converts `@user` to `` `@user` ``), bot trigger protection, XML tag safety, and URI filtering. - -After creating this workflow file as `.github/workflows/copilot-helper.md` (note: agentic workflows use `.md` files, not `.yml`), compile it: - -```bash -gh aw compile copilot-helper -``` +1. Go to your repository on GitHub +2. Click on the **Actions** tab +3. Click **Create new agentic task** +4. In the agent selection, choose **create-agentic-workflow** +5. Describe what you want your workflow to do (e.g., "Create a workflow that triages new issues and adds labels") +6. The agent will generate the workflow file for you -This will generate `.github/workflows/copilot-helper.lock.yml`, which is the actual GitHub Actions workflow file that will run. +### Debugging and Improving Workflows -## Next Steps +If you encounter issues with a workflow or want to improve it: -1. **Explore the documentation**: Check `.github/aw/github-agentic-workflows.md` for comprehensive workflow documentation -2. **Create your first workflow**: Start with a simple workflow and iterate -3. **Test in a safe environment**: Use a test repository to experiment -4. **Monitor usage**: Use `gh aw logs` to track workflow runs and costs +1. Go to your repository on GitHub +2. Click on the **Actions** tab +3. Click **Create new agentic task** +4. In the agent selection, choose **debug-agentic-workflow** +5. Provide the GitHub URL to your failed workflow run (e.g., `https://github.com/owner/repo/actions/runs/12345`) +6. The agent will analyze the logs and suggest fixes or improvements ## Additional Resources From 344a11411b3bc19c4d15e23994094858c3efd11c Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 20 Dec 2025 19:29:21 +0000 Subject: [PATCH 7/7] Remove Token Types and Permissions section Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- README.md | 49 ------------------------------------------------- 1 file changed, 49 deletions(-) diff --git a/README.md b/README.md index 4d8e13c..37f820c 100644 --- a/README.md +++ b/README.md @@ -53,55 +53,6 @@ If you need additional capabilities, add these tokens as repository secrets foll - **For agent assignment operations**: Create a secret named `GH_AW_AGENT_TOKEN` - **For GitHub Projects v2 operations**: Create a secret named `GH_AW_PROJECT_GITHUB_TOKEN` -### Token Types and Permissions - -#### `COPILOT_GITHUB_TOKEN` (Copilot Authentication) - -**Required for:** -- `engine: copilot` workflows -- `create-agent-task:` safe outputs -- Assigning `copilot` as issue assignee -- Adding `copilot` as PR reviewer - -**Required permissions:** -- Copilot Requests (required) -- Repository access (read or write depending on use case) - -#### `GH_AW_GITHUB_TOKEN` (Enhanced PAT) - -**Required for:** -- Cross-repository operations -- Remote GitHub tools mode -- Codex engine operations with GitHub MCP - -**Required permissions:** -- Contents: Read (minimum) or Read+Write (for PRs) -- Issues: Read+Write (for issue operations) -- Pull requests: Read+Write (for PR operations) - -#### `GH_AW_AGENT_TOKEN` (Agent Assignment) - -**Required for:** -- `assign-to-agent:` safe outputs -- Programmatic agent assignment operations - -**Required permissions:** -- Actions: Write -- Contents: Write -- Issues: Write -- Pull requests: Write - -#### `GH_AW_PROJECT_GITHUB_TOKEN` (GitHub Projects v2) - -**Required for:** -- Any GitHub Projects v2 operations -- `update-project` safe outputs - -**Required permissions:** -- For User-owned Projects: Classic PAT with `project` scope -- For Organization-owned Projects (option 1): Classic PAT with `project` + `read:org` scopes -- For Organization-owned Projects (option 2): Fine-grained PAT with explicit Organization access + Projects: Read+Write - ## Creating Workflows ### Using the Create Agentic Workflow Agent