From b2dbd302c124844f98387c2ecf8d4ba9cb31d09b Mon Sep 17 00:00:00 2001 From: Don Syme Date: Mon, 23 Feb 2026 22:43:46 +0000 Subject: [PATCH 01/10] auth doc update and magic secret for GH_AW_CI_TRIGGER_TOKEN --- .github/aw/create-agentic-workflow.md | 2 +- actions/setup/js/extra_empty_commit.cjs | 5 +- docs/src/content/docs/examples/multi-repo.md | 2 +- .../docs/examples/multi-repo/feature-sync.md | 2 +- .../examples/multi-repo/issue-tracking.md | 2 +- .../content/docs/examples/project-tracking.md | 8 +- .../docs/guides/getting-started-mcp.md | 13 +- docs/src/content/docs/index.mdx | 2 +- .../content/docs/patterns/multi-repo-ops.md | 2 +- .../src/content/docs/patterns/project-ops.mdx | 15 +- .../content/docs/patterns/side-repo-ops.mdx | 2 +- .../docs/reference/assign-to-copilot.mdx | 131 +++++++++ .../content/docs/reference/auth-projects.mdx | 106 +++++++ docs/src/content/docs/reference/auth.mdx | 274 ++---------------- docs/src/content/docs/reference/faq.md | 6 +- .../src/content/docs/reference/frontmatter.md | 7 - .../content/docs/reference/github-tools.md | 131 +++++++++ .../content/docs/reference/lockdown-mode.md | 31 +- .../content/docs/reference/safe-outputs.md | 40 +-- docs/src/content/docs/reference/tools.md | 71 +---- .../content/docs/reference/triggering-ci.mdx | 8 +- .../docs/troubleshooting/common-issues.md | 4 +- .../content/docs/troubleshooting/errors.md | 2 +- pkg/cli/project_command.go | 10 +- pkg/parser/schemas/main_workflow_schema.json | 4 +- pkg/workflow/compiler.go | 2 +- pkg/workflow/compiler_safe_outputs_job.go | 4 + pkg/workflow/create_pull_request.go | 4 + pkg/workflow/github_token.go | 16 + pkg/workflow/github_token_test.go | 28 ++ 30 files changed, 502 insertions(+), 432 deletions(-) create mode 100644 docs/src/content/docs/reference/assign-to-copilot.mdx create mode 100644 docs/src/content/docs/reference/auth-projects.mdx create mode 100644 docs/src/content/docs/reference/github-tools.md diff --git a/.github/aw/create-agentic-workflow.md b/.github/aw/create-agentic-workflow.md index ea5cb79c5f..53c790e77b 100644 --- a/.github/aw/create-agentic-workflow.md +++ b/.github/aw/create-agentic-workflow.md @@ -315,7 +315,7 @@ These resources contain workflow patterns, best practices, safe outputs, and per **Documentation Reference:** - Full guide: https://github.github.com/gh-aw/patterns/multi-repo-ops/ - Safe Outputs Reference: https://github.github.com/gh-aw/reference/safe-outputs/ - - GitHub Tools: https://github.github.com/gh-aw/reference/tools/#github-tools-github + - GitHub Tools: https://github.github.com/gh-aw/reference/github-tools/ **Custom Safe Output Jobs (for new safe outputs):** diff --git a/actions/setup/js/extra_empty_commit.cjs b/actions/setup/js/extra_empty_commit.cjs index 98dffcf30b..185af5fad4 100644 --- a/actions/setup/js/extra_empty_commit.cjs +++ b/actions/setup/js/extra_empty_commit.cjs @@ -9,7 +9,10 @@ * GITHUB_TOKEN do not trigger other workflow runs. * * The token comes from `github-token-for-extra-empty-commit` in safe-outputs config - * (passed as GH_AW_EXTRA_EMPTY_COMMIT_TOKEN env var), or `app` for GitHub App authentication. + * (passed as GH_AW_EXTRA_EMPTY_COMMIT_TOKEN env var). Supported values: + * - `app` - Use GitHub App token from safe-outputs-app-token step + * - `default` - Use the magic secret GH_AW_CI_TRIGGER_TOKEN + * - `${{ secrets.CUSTOM_TOKEN }}` - Use a custom PAT or secret */ /** diff --git a/docs/src/content/docs/examples/multi-repo.md b/docs/src/content/docs/examples/multi-repo.md index f4ee6891e9..79c71a8883 100644 --- a/docs/src/content/docs/examples/multi-repo.md +++ b/docs/src/content/docs/examples/multi-repo.md @@ -158,6 +158,6 @@ For comprehensive documentation on the MultiRepoOps design pattern, see: ## Related Documentation - [Safe Outputs Reference](/gh-aw/reference/safe-outputs/) - Configuration options -- [GitHub Tools](/gh-aw/reference/tools/#github-tools-github) - API access configuration +- [GitHub Tools](/gh-aw/reference/github-tools/) - API access configuration - [Security Best Practices](/gh-aw/introduction/architecture/) - Authentication and security - [Reusing Workflows](/gh-aw/guides/packaging-imports/) - Sharing workflows diff --git a/docs/src/content/docs/examples/multi-repo/feature-sync.md b/docs/src/content/docs/examples/multi-repo/feature-sync.md index f3ba38902f..7a0b808be6 100644 --- a/docs/src/content/docs/examples/multi-repo/feature-sync.md +++ b/docs/src/content/docs/examples/multi-repo/feature-sync.md @@ -272,4 +272,4 @@ For enhanced security, use GitHub App installation tokens. See [Using a GitHub A - [MultiRepoOps Design Pattern](/gh-aw/patterns/multi-repo-ops/) - Complete multi-repo overview - [Cross-Repo Issue Tracking](/gh-aw/examples/multi-repo/issue-tracking/) - Issue management patterns - [Safe Outputs Reference](/gh-aw/reference/safe-outputs/) - Pull request configuration -- [GitHub Tools](/gh-aw/reference/tools/#github-tools-github) - Repository access tools +- [GitHub Tools](/gh-aw/reference/github-tools/) - Repository access tools diff --git a/docs/src/content/docs/examples/multi-repo/issue-tracking.md b/docs/src/content/docs/examples/multi-repo/issue-tracking.md index ac2534cb88..fc03c22391 100644 --- a/docs/src/content/docs/examples/multi-repo/issue-tracking.md +++ b/docs/src/content/docs/examples/multi-repo/issue-tracking.md @@ -301,4 +301,4 @@ For enhanced security, use GitHub App installation tokens. See [Using a GitHub A - [MultiRepoOps Design Pattern](/gh-aw/patterns/multi-repo-ops/) - Complete multi-repo overview - [Feature Synchronization](/gh-aw/examples/multi-repo/feature-sync/) - Code sync patterns - [Safe Outputs Reference](/gh-aw/reference/safe-outputs/) - Issue creation configuration -- [GitHub Tools](/gh-aw/reference/tools/#github-tools-github) - API access configuration +- [GitHub Tools](/gh-aw/reference/github-tools/) - API access configuration diff --git a/docs/src/content/docs/examples/project-tracking.md b/docs/src/content/docs/examples/project-tracking.md index 8d0dff80be..067d998f72 100644 --- a/docs/src/content/docs/examples/project-tracking.md +++ b/docs/src/content/docs/examples/project-tracking.md @@ -75,7 +75,9 @@ safe-outputs: See [Safe Outputs: Project Board Updates](/gh-aw/reference/safe-outputs/#project-board-updates-update-project) for complete configuration details. -## Prerequisites +## Authentication + +See ### 1. Create a GitHub Project @@ -106,7 +108,7 @@ Use a **fine-grained PAT** with: gh aw secrets set GH_AW_PROJECT_GITHUB_TOKEN --value "YOUR_PROJECT_TOKEN" ``` -See the [GitHub Projects V2 authentication](/gh-aw/reference/auth/#gh_aw_project_github_token) for complete details. +See [GitHub Projects authentication](/gh-aw/reference/auth-projects/) for complete details. ## Example: Issue Triage @@ -314,6 +316,6 @@ Update the project item with the team field. - [Safe Outputs Reference](/gh-aw/reference/safe-outputs/) - Complete safe-outputs documentation - [update-project](/gh-aw/reference/safe-outputs/#project-board-updates-update-project) - Detailed update-project configuration - [create-project-status-update](/gh-aw/reference/safe-outputs/#project-status-updates-create-project-status-update) - Status update configuration -- [GitHub Projects V2 Authentication](/gh-aw/reference/auth/#gh_aw_project_github_token) - Token setup guide +- [GitHub Projects Authentication](/gh-aw/reference/auth-projects/) - Token setup guide - [Projects & Monitoring](/gh-aw/patterns/monitoring/) - Design pattern guide - [Orchestration](/gh-aw/patterns/orchestration/) - Design pattern guide diff --git a/docs/src/content/docs/guides/getting-started-mcp.md b/docs/src/content/docs/guides/getting-started-mcp.md index ac92c1d244..8457a52a26 100644 --- a/docs/src/content/docs/guides/getting-started-mcp.md +++ b/docs/src/content/docs/guides/getting-started-mcp.md @@ -132,17 +132,6 @@ tools: ``` Local mode runs the MCP server in a Docker container, useful for pinning specific versions or offline environments. -### Authentication - -Tokens are used in order: `github-token` configuration field, [`GH_AW_GITHUB_TOKEN`](/gh-aw/reference/auth/#gh_aw_github_token) secret, then `GITHUB_TOKEN` (default). - -```yaml wrap -tools: - github: - github-token: "${{ secrets.CUSTOM_PAT }}" # Optional custom token - toolsets: [default] -``` - ### Read-Only Mode Restrict operations to read-only for security-sensitive workflows: @@ -314,7 +303,7 @@ gh aw compile my-workflow --validate --strict **Tool not found:** Run `gh aw mcp inspect my-workflow` to verify available tools. Ensure the correct toolset is enabled or that tool names in `allowed:` match exactly. -**Authentication errors:** Verify the secret exists in repository settings and has required scopes. For remote mode, set [`GH_AW_GITHUB_TOKEN`](/gh-aw/reference/auth/#gh_aw_github_token) with a PAT. +**Authentication errors:** Verify the secret exists in repository settings and has required scopes. **Connection failures:** Check URL syntax for HTTP servers, network configuration for containers, and verify Docker images exist. diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx index 9f37b6c07b..88f6301f29 100644 --- a/docs/src/content/docs/index.mdx +++ b/docs/src/content/docs/index.mdx @@ -41,7 +41,7 @@ Developed by GitHub Next and Microsoft Research, workflows run with added guardr Workflows that understand context and adapt to situations - + Deep integration with Actions, Issues, PRs, Discussions, and repository management diff --git a/docs/src/content/docs/patterns/multi-repo-ops.md b/docs/src/content/docs/patterns/multi-repo-ops.md index bf3d468c5c..2de35b8311 100644 --- a/docs/src/content/docs/patterns/multi-repo-ops.md +++ b/docs/src/content/docs/patterns/multi-repo-ops.md @@ -257,6 +257,6 @@ For organization-wide workflows: ## Related Documentation - [Safe Outputs Reference](/gh-aw/reference/safe-outputs/) - Complete safe output configuration -- [GitHub Tools](/gh-aw/reference/tools/#github-tools-github) - GitHub API toolsets +- [GitHub Tools](/gh-aw/reference/github-tools/) - GitHub API toolsets - [Security Best Practices](/gh-aw/introduction/architecture/) - Authentication and token security - [Reusing Workflows](/gh-aw/guides/packaging-imports/) - Sharing workflows across repos diff --git a/docs/src/content/docs/patterns/project-ops.mdx b/docs/src/content/docs/patterns/project-ops.mdx index d90b263114..0660a79319 100644 --- a/docs/src/content/docs/patterns/project-ops.mdx +++ b/docs/src/content/docs/patterns/project-ops.mdx @@ -15,7 +15,7 @@ Safe outputs handle all project operations in separate, scoped jobs with minimal 1. **Create a Project**: Before you wire up a workflow, you must first create the Project in the GitHub UI (user or organization level). Keep the Project URL handy (you'll need to reference it in your workflow instructions). -2. **Arrange access**: See [Projects authentication](/gh-aw/reference/auth/#gh_aw_project_github_token) for complete details. +2. Add **Additional Authentication** to your workflow: See [Authentication (Projects)](/gh-aw/reference/auth-projects/) for setup instructions. ## Example: Smart Issue Triage @@ -32,11 +32,11 @@ permissions: tools: github: toolsets: [default, projects] - github-token: ${{ secrets.GH_AW_PROJECT_GITHUB_TOKEN }} + github-token: ${{ secrets.MY_PROJECT_TOKEN }} safe-outputs: update-project: max: 1 - github-token: ${{ secrets.GH_AW_PROJECT_GITHUB_TOKEN }} + github-token: ${{ secrets.MY_PROJECT_TOKEN }} add-comment: max: 1 --- @@ -97,6 +97,10 @@ Each safe output operates in a separate job with minimal, scoped permissions. Se See the [Safe Outputs reference](/gh-aw/reference/safe-outputs/#project-board-updates-update-project) for project field and view configuration. +## Authentication for Project Operations + +Project operations require additional authentication since the default `GITHUB_TOKEN` lacks necessary permissions for the Projects API. See [Authentication (Projects)](/gh-aw/reference/auth-projects/). + ## When to Use ProjectOps ProjectOps complements [GitHub's built-in Projects automation](https://docs.github.com/en/issues/planning-and-tracking-with-projects/automating-your-project/using-the-built-in-automations) with AI-powered intelligence: @@ -113,7 +117,7 @@ ProjectOps complements [GitHub's built-in Projects automation](https://docs.gith **Field Name Mismatches**: Custom field names are case-sensitive. Use exact field names as defined in project settings. Field names are automatically normalized (e.g., `story_points` matches `Story Points`). -**Token Scope**: Default `GITHUB_TOKEN` cannot access Projects. Store a PAT with Projects permissions in [`GH_AW_PROJECT_GITHUB_TOKEN`](/gh-aw/reference/auth/#gh_aw_project_github_token) secret. +**Token Scope**: Default `GITHUB_TOKEN` cannot access Projects. See [Authentication (Projects)](/gh-aw/reference/auth-projects/) for setup. **Project URL Format**: Use full project URLs (e.g., `https://github.com/orgs/myorg/projects/42`), not project numbers alone. @@ -121,9 +125,10 @@ ProjectOps complements [GitHub's built-in Projects automation](https://docs.gith ## Additional Resources +- [Authentication (Projects)](/gh-aw/reference/auth-projects/) - Project-specific authentication setup - [Safe Outputs Reference](/gh-aw/reference/safe-outputs/) - Complete safe output configuration and API details - [Projects & Monitoring](/gh-aw/patterns/monitoring/) - Design pattern guide - [Orchestration](/gh-aw/patterns/orchestration/) - Design pattern guide - [Trigger Events](/gh-aw/reference/triggers/) - Event trigger configuration options - [IssueOps](/gh-aw/patterns/issue-ops/) - Related issue automation patterns -- [Token Reference](/gh-aw/reference/auth/#gh_aw_project_github_token) - GitHub Projects token setup +- [Authentication Reference](/gh-aw/reference/auth/) - All tokens and secrets diff --git a/docs/src/content/docs/patterns/side-repo-ops.mdx b/docs/src/content/docs/patterns/side-repo-ops.mdx index 57b58fcfe5..90ba4f35ca 100644 --- a/docs/src/content/docs/patterns/side-repo-ops.mdx +++ b/docs/src/content/docs/patterns/side-repo-ops.mdx @@ -401,7 +401,7 @@ This creates a feedback loop where the side repository tracks automation effecti ## Related Documentation - [Safe Outputs Reference](/gh-aw/reference/safe-outputs/) - Complete safe output configuration -- [GitHub Tools](/gh-aw/reference/tools/#github-tools-github) - GitHub API toolsets +- [GitHub Tools](/gh-aw/reference/github-tools/) - GitHub API toolsets - [Authentication](/gh-aw/reference/auth/) - Token types and precedence - [Security Best Practices](/gh-aw/introduction/architecture/) - Authentication and security - [Reusing Workflows](/gh-aw/guides/packaging-imports/) - Sharing workflows diff --git a/docs/src/content/docs/reference/assign-to-copilot.mdx b/docs/src/content/docs/reference/assign-to-copilot.mdx new file mode 100644 index 0000000000..0e2dbefb29 --- /dev/null +++ b/docs/src/content/docs/reference/assign-to-copilot.mdx @@ -0,0 +1,131 @@ +--- +title: Assign to Copilot +description: Programmatically assign GitHub Copilot coding agent to issues and pull requests +sidebar: + order: 810 +--- + +import Video from '../../../components/Video.astro'; + +This page describes how to programmatically assign the [GitHub Copilot coding agent](https://docs.github.com/en/copilot/concepts/agents/coding-agent/about-coding-agent) to issues or pull requests using the `assign-to-agent` safe output. This automates the [standard GitHub workflow for assigning issues to Copilot](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-a-pr#assigning-an-issue-to-copilot). + +## When to Use + +Use `assign-to-agent` when you need to programmatically assign agents to **existing** issues or PRs through workflow automation. + +If you're creating new issues and want to assign an agent immediately, use `assignees: copilot` in your [`create-issue`](/gh-aw/reference/safe-outputs/#issue-creation-create-issue) configuration instead. + +## Configuration + +```yaml wrap +safe-outputs: + assign-to-agent: + name: "copilot" # default agent (default: "copilot") + model: "claude-opus-4.6" # default AI model (default: "auto") + custom-agent: "agent-id" # default custom agent ID (optional) + custom-instructions: "..." # default custom instructions (optional) + allowed: [copilot] # restrict to specific agents (optional) + max: 1 # max assignments (default: 1) + target: "triggering" # "triggering" (default), "*", or number + target-repo: "owner/repo" # where the issue lives (cross-repository) + pull-request-repo: "owner/repo" # where the PR should be created (may differ from issue repo) + allowed-pull-request-repos: [owner/repo1, owner/repo2] # additional allowed PR repositories + base-branch: "develop" # target branch for PR (default: target repo's default branch) + github-token: ${{ secrets.GH_AW_AGENT_TOKEN }} # token for permissions +``` + +**Supported agents:** `copilot` (`copilot-swe-agent`) + +## Target Issue or Pull Request + +The `target` parameter determines which issue or PR to assign the agent to: + +- `target: "triggering"` (default) - Auto-resolves from `github.event.issue.number` or `github.event.pull_request.number` +- `target: "*"` - Requires explicit `issue_number` or `pull_number` in agent output +- `target: "123"` - Always uses issue/PR #123 + +## Cross-Repository PR Creation + +The `pull-request-repo` parameter allows you to create pull requests in a different repository than where the issue lives. This is useful when: + +- Issues are tracked in a central repository but code lives in separate repositories +- You want to separate issue tracking from code repositories + +When `pull-request-repo` is configured, Copilot will create the pull request in the specified repository instead of the issue's repository. The issue repository is determined by `target-repo` or defaults to the workflow's repository. + +The repository specified by `pull-request-repo` is automatically allowed - you don't need to list it in `allowed-pull-request-repos`. Use `allowed-pull-request-repos` to specify additional repositories where PRs can be created. + +Use `base-branch` to specify which branch in the target repository the pull request should target. When omitted, the target repository's actual default branch is used automatically. Only relevant when `pull-request-repo` is configured. + +## Assignee Filtering + +When an `allowed` list is configured, existing agent assignees not in the list are removed while regular user assignees are preserved. + +## Authentication + +This safe output requires a fine-grained PAT to authenticate the agent assignment operation. The default `GITHUB_TOKEN` lacks the necessary permissions. + +### Token Precedence + +The safe output uses tokens in this order: + +1. `GH_AW_AGENT_TOKEN` (recommended) +2. `GH_AW_GITHUB_TOKEN` (fallback) +3. `GITHUB_TOKEN` (will fail - lacks required permissions) + +### `GH_AW_AGENT_TOKEN` Setup + +The required token type and permissions depend on whether you own the repository or an organization owns it. + +**For User-owned Repositories:** + +1. Create a [fine-grained PAT](https://github.com/settings/personal-access-tokens/new) with: + - **Resource owner**: Your user account + - **Repository access**: "Public repositories" or select specific repos + - **Repository permissions**: + - Actions: Write + - Contents: Write + - Issues: Write + - Pull requests: Write + +**For Organization-owned Repositories:** + +When an organization owns the repository, you need a fine-grained PAT with the resource owner set to the organization: + +1. Create a [fine-grained PAT](https://github.com/settings/personal-access-tokens/new) with: + - **Resource owner**: The organization that owns the repository + - **Repository access**: Select the specific repositories that will use the workflow + - **Repository permissions**: + - Actions: Write + - Contents: Write + - Issues: Write + - Pull requests: Write + - **Important**: You must set the resource owner to the organization during token creation + +