diff --git a/.github/aw/create-agentic-workflow.md b/.github/aw/create-agentic-workflow.md index ea5cb79c5f..906f092e89 100644 --- a/.github/aw/create-agentic-workflow.md +++ b/.github/aw/create-agentic-workflow.md @@ -266,7 +266,7 @@ These resources contain workflow patterns, best practices, safe outputs, and per **Authentication Setup:** ```yaml safe-outputs: - github-token: ${{ secrets.CROSS_REPO_PAT }} # PAT with access to target repos + github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }} # PAT with access to target repos create-issue: max: 5 add-comment: @@ -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):** @@ -618,7 +618,7 @@ Based on the parsed requirements, determine: If the workflow involves cross-repository operations, follow these additional guidelines: **Authentication Configuration:** -- Add `safe-outputs.github-token: ${{ secrets.CROSS_REPO_PAT }}` for PAT authentication +- Add `safe-outputs.github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }}` for PAT authentication - Or use `safe-outputs.app` for GitHub App authentication - Document required PAT scopes in the workflow description @@ -648,7 +648,7 @@ tools: github: toolsets: [repos, issues, pull_requests] safe-outputs: - github-token: ${{ secrets.CROSS_REPO_PAT }} + github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }} create-issue: max: 5 add-comment: diff --git a/.github/aw/github-agentic-workflows.md b/.github/aw/github-agentic-workflows.md index f7b84e916e..3f7b23bc25 100644 --- a/.github/aw/github-agentic-workflows.md +++ b/.github/aw/github-agentic-workflows.md @@ -745,7 +745,7 @@ The YAML frontmatter supports these fields: update-release: max: 1 # Optional: max releases (default: 1, max: 10) target-repo: "owner/repo" # Optional: cross-repository - github-token: ${{ secrets.CUSTOM_TOKEN }} # Optional: custom token + github-token: ${{ secrets.GH_AW_UPDATE_RELEASE_TOKEN }} # Optional: custom token ``` Operation types: `replace`, `append`, `prepend`. - `upload-asset:` - Publish files to orphaned git branch @@ -895,7 +895,7 @@ The YAML frontmatter supports these fields: safe-outputs: create-issue: add-comment: - github-token: ${{ secrets.CUSTOM_PAT }} # Use custom PAT instead of GITHUB_TOKEN + github-token: ${{ secrets.GH_AW_SAFE_OUTPUTS_TOKEN }} # Use custom PAT instead of GITHUB_TOKEN ``` Useful when you need additional permissions or want to perform actions across repositories. - `allowed-domains:` - Allowed domains for URLs in safe output content (array) 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/astro.config.mjs b/docs/astro.config.mjs index 8e3f1a261f..00244c490c 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -209,6 +209,7 @@ export default defineConfig({ items: [ { label: 'AI Engines', link: '/reference/engines/' }, { label: 'Authentication', link: '/reference/auth/' }, + { label: 'Authentication (Projects)', link: '/reference/auth-projects/' }, { label: 'Cache Memory', link: '/reference/cache-memory/' }, { label: 'Command Triggers', link: '/reference/command-triggers/' }, { label: 'Compilation Process', link: '/reference/compilation-process/' }, diff --git a/docs/src/content/docs/examples/multi-repo.md b/docs/src/content/docs/examples/multi-repo.md index f4ee6891e9..6f873fbced 100644 --- a/docs/src/content/docs/examples/multi-repo.md +++ b/docs/src/content/docs/examples/multi-repo.md @@ -26,7 +26,7 @@ All multi-repo workflows require proper authentication: gh auth token # Store as repository or organization secret -gh aw secrets set CROSS_REPO_PAT --value "ghp_your_token_here" +gh aw secrets set GH_AW_CROSS_REPO_PAT --value "ghp_your_token_here" ``` The PAT needs permissions **only on target repositories** (not the source repository where the workflow runs): `repo` for private repos, `contents: write` for commits, `issues: write` for issues, and `pull-requests: write` for PRs. @@ -92,7 +92,7 @@ Most safe output types support the `target-repo` parameter for cross-repository ```yaml wrap safe-outputs: - github-token: ${{ secrets.CROSS_REPO_PAT }} + github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }} create-issue: target-repo: "org/tracking-repo" # Cross-repo: creates in tracking-repo title-prefix: "[component] " @@ -141,7 +141,7 @@ engine: uses: actions/checkout@v5 with: repository: org/secondary-repo - token: ${{ secrets.CROSS_REPO_PAT }} + token: ${{ secrets.GH_AW_CROSS_REPO_PAT }} path: secondary-repo ``` @@ -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..376725cf63 100644 --- a/docs/src/content/docs/examples/multi-repo/feature-sync.md +++ b/docs/src/content/docs/examples/multi-repo/feature-sync.md @@ -36,7 +36,7 @@ tools: bash: - "git:*" safe-outputs: - github-token: ${{ secrets.CROSS_REPO_PAT }} + github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }} create-pull-request: target-repo: "myorg/downstream-service" title-prefix: "[sync] " @@ -71,7 +71,7 @@ tools: bash: - "git:*" safe-outputs: - github-token: ${{ secrets.CROSS_REPO_PAT }} + github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }} create-pull-request: max: 3 title-prefix: "[core-sync] " @@ -103,7 +103,7 @@ tools: bash: - "git:*" safe-outputs: - github-token: ${{ secrets.CROSS_REPO_PAT }} + github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }} create-pull-request: target-repo: "myorg/production-service" title-prefix: "[upgrade] " @@ -139,7 +139,7 @@ tools: bash: - "git:*" safe-outputs: - github-token: ${{ secrets.CROSS_REPO_PAT }} + github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }} create-pull-request: target-repo: "myorg/client-sdk" title-prefix: "[types] " @@ -173,7 +173,7 @@ tools: bash: - "git:*" safe-outputs: - github-token: ${{ secrets.CROSS_REPO_PAT }} + github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }} create-pull-request: target-repo: "myorg/sister-project" title-prefix: "[config-sync] " @@ -208,7 +208,7 @@ tools: bash: - "git:*" safe-outputs: - github-token: ${{ secrets.CROSS_REPO_PAT }} + github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }} create-pull-request: target-repo: "myorg/integration-tests" title-prefix: "[feature-test] " @@ -238,7 +238,7 @@ tools: bash: - "git:*" safe-outputs: - github-token: ${{ secrets.CROSS_REPO_PAT }} + github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }} create-pull-request: target-repo: "myorg/downstream-fork" title-prefix: "[weekly-sync] " @@ -260,7 +260,7 @@ Cross-repo sync workflows require authentication via PAT or GitHub App. Create a PAT with `repo`, `contents: write`, and `pull-requests: write` permissions, then store it as a repository secret: ```bash -gh aw secrets set CROSS_REPO_PAT --value "ghp_your_token_here" +gh aw secrets set GH_AW_CROSS_REPO_PAT --value "ghp_your_token_here" ``` ### GitHub App Configuration @@ -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..5fc7726354 100644 --- a/docs/src/content/docs/examples/multi-repo/issue-tracking.md +++ b/docs/src/content/docs/examples/multi-repo/issue-tracking.md @@ -31,7 +31,7 @@ tools: github: toolsets: [issues] safe-outputs: - github-token: ${{ secrets.CROSS_REPO_PAT }} + github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }} create-issue: target-repo: "myorg/central-tracker" title-prefix: "[component-alpha] " @@ -66,7 +66,7 @@ tools: github: toolsets: [issues] safe-outputs: - github-token: ${{ secrets.CROSS_REPO_PAT }} + github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }} add-comment: target-repo: "myorg/central-tracker" target: "*" # Find related tracking issue @@ -99,7 +99,7 @@ tools: github: toolsets: [issues] safe-outputs: - github-token: ${{ secrets.CROSS_REPO_PAT }} + github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }} create-issue: max: 3 # May create issues in multiple tracking repos target-repo: "myorg/central-tracker" @@ -136,7 +136,7 @@ tools: toolsets: [issues] web-fetch: safe-outputs: - github-token: ${{ secrets.CROSS_REPO_PAT }} + github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }} create-issue: target-repo: "myorg/dependency-tracker" title-prefix: "[upstream] " @@ -168,7 +168,7 @@ tools: github: toolsets: [issues] safe-outputs: - github-token: ${{ secrets.CROSS_REPO_PAT }} + github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }} create-issue: max: 2 title-prefix: "[auto-triaged] " @@ -197,7 +197,7 @@ tools: github: toolsets: [issues] safe-outputs: - github-token: ${{ secrets.CROSS_REPO_PAT }} + github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }} create-discussion: target-repo: "myorg/central-tracker" category: "Status Reports" @@ -228,7 +228,7 @@ tools: github: toolsets: [issues] safe-outputs: - github-token: ${{ secrets.CROSS_REPO_PAT }} + github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }} create-issue: target-repo: "myorg/central-tracker" title-prefix: "[linked] " @@ -261,7 +261,7 @@ tools: github: toolsets: [issues] safe-outputs: - github-token: ${{ secrets.CROSS_REPO_PAT }} + github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }} create-issue: max: 1 title-prefix: "[priority-routed] " @@ -285,7 +285,7 @@ Cross-repo issue tracking requires appropriate authentication: ```bash # Create PAT with issues and repository read permissions -gh aw secrets set CROSS_REPO_PAT --value "ghp_your_token_here" +gh aw secrets set GH_AW_CROSS_REPO_PAT --value "ghp_your_token_here" ``` **Required Permissions:** @@ -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..5d2c88f2ce 100644 --- a/docs/src/content/docs/examples/project-tracking.md +++ b/docs/src/content/docs/examples/project-tracking.md @@ -64,8 +64,6 @@ safe-outputs: github-token: ${{ secrets.GH_AW_PROJECT_GITHUB_TOKEN }} ``` -### Configuration Fields - | Field | Type | Default | Description | |-------|------|---------|-------------| | `project` | string | (required) | GitHub Project URL for update-project or create-project-status-update | @@ -75,38 +73,9 @@ safe-outputs: See [Safe Outputs: Project Board Updates](/gh-aw/reference/safe-outputs/#project-board-updates-update-project) for complete configuration details. -## Prerequisites - -### 1. Create a GitHub Project - -Create a Projects V2 board in the GitHub UI before configuring your workflow. You'll need the Project URL from the browser address bar. - -### 2. Set Up Authentication - -#### For User-Owned Projects - -Use a **classic PAT** with scopes: -- `project` (required) -- `repo` (if accessing private repositories) - -#### For Organization-Owned Projects - -Use a **fine-grained PAT** with: -- Repository access: Select specific repos -- Repository permissions: - - Contents: Read - - Issues: Read (if workflow triggers on issues) - - Pull requests: Read (if workflow triggers on pull requests) -- Organization permissions: - - Projects: Read & Write - -### 3. Store the Token - -```bash -gh aw secrets set GH_AW_PROJECT_GITHUB_TOKEN --value "YOUR_PROJECT_TOKEN" -``` +### Authentication -See the [GitHub Projects V2 authentication](/gh-aw/reference/auth/#gh_aw_project_github_token) for complete details. +See [Authentication (Projects)](/gh-aw/reference/auth-projects/). ## Example: Issue Triage @@ -314,6 +283,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/central-repo-ops.mdx b/docs/src/content/docs/patterns/central-repo-ops.mdx index 52c61ac76d..15e3910f4d 100644 --- a/docs/src/content/docs/patterns/central-repo-ops.mdx +++ b/docs/src/content/docs/patterns/central-repo-ops.mdx @@ -48,7 +48,7 @@ on: tools: github: - github-token: ${{ secrets.ORG_GITHUB_MCP_SERVER_TOKEN }} + github-token: ${{ secrets.GH_AW_READ_ORG_TOKEN }} toolsets: [repos] safe-outputs: @@ -81,7 +81,7 @@ Categorize and orchestrate Dependabot rollout across repositories. ``` Compile this workflow to generate the lock file: `gh aw compile`. -Create a fine-grained PAT `ORG_GITHUB_MCP_SERVER_TOKEN` with the organization as an owner, +Create a fine-grained PAT `GH_AW_READ_ORG_TOKEN` with the organization as an owner, select "All repositories" (or allowlist of specific repos), and grant Repository permission: `Contents: Read-only`. Add this into your Actions repository secrets. This gives the orchestrator read access to all candidate repositories. @@ -113,11 +113,11 @@ permissions: tools: github: - github-token: ${{ secrets.ORG_GITHUB_MCP_SERVER_TOKEN }} + github-token: ${{ secrets.GH_AW_READ_ORG_TOKEN }} toolsets: [repos] safe-outputs: - github-token: ${{ secrets.REPO_SAFE_OUTPUTS_TOKEN }} + github-token: ${{ secretsGH_AW_CROSS_REPO_PAT }} create-pull-request: target-repo: ${{ github.event.inputs.target_repo }} title-prefix: '[dependabot] ' diff --git a/docs/src/content/docs/patterns/multi-repo-ops.md b/docs/src/content/docs/patterns/multi-repo-ops.md index bf3d468c5c..4f6c9d1a2d 100644 --- a/docs/src/content/docs/patterns/multi-repo-ops.md +++ b/docs/src/content/docs/patterns/multi-repo-ops.md @@ -28,7 +28,7 @@ permissions: contents: read actions: read safe-outputs: - github-token: ${{ secrets.CROSS_REPO_PAT }} + github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }} create-issue: target-repo: "org/tracking-repo" title-prefix: "[component-a] " @@ -58,7 +58,7 @@ Configure a Personal Access Token with access to target repositories: ```yaml wrap safe-outputs: - github-token: ${{ secrets.CROSS_REPO_PAT }} + github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }} create-issue: target-repo: "org/tracking-repo" ``` @@ -175,7 +175,7 @@ engine: uses: actions/checkout@v5 with: repository: org/secondary-repo - token: ${{ secrets.CROSS_REPO_PAT }} + token: ${{ secrets.GH_AW_CROSS_REPO_PAT }} path: secondary-repo - name: Compare and sync @@ -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..5b6d87a075 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 @@ -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..26062eefa1 100644 --- a/docs/src/content/docs/patterns/side-repo-ops.mdx +++ b/docs/src/content/docs/patterns/side-repo-ops.mdx @@ -69,7 +69,7 @@ Create a [fine-grained PAT](https://github.com/settings/personal-access-tokens/n For classic PATs, use the `repo` scope. Store the token as a secret: ```bash -gh aw secrets set MAIN_REPO_PAT --value "YOUR_PAT_HERE" +gh aw secrets set GH_AW_MAIN_REPO_TOKEN --value "YOUR_PAT_HERE" ``` > [!TIP] @@ -101,7 +101,7 @@ permissions: contents: read safe-outputs: - github-token: ${{ secrets.MAIN_REPO_PAT }} + github-token: ${{ secrets.GH_AW_MAIN_REPO_TOKEN }} create-issue: target-repo: "my-org/main-repo" title-prefix: "[automation] " @@ -147,7 +147,7 @@ permissions: contents: read safe-outputs: - github-token: ${{ secrets.MAIN_REPO_PAT }} + github-token: ${{ secrets.GH_AW_MAIN_REPO_TOKEN }} create-issue: target-repo: "my-org/main-repo" max: 5 @@ -192,14 +192,14 @@ For private repositories, your PAT must have explicit repository access with app ```yaml wrap safe-outputs: - github-token: ${{ secrets.MAIN_REPO_PAT }} # Required for private repos + github-token: ${{ secrets.GH_AW_MAIN_REPO_TOKEN }} # Required for private repos create-issue: target-repo: "my-org/private-main-repo" tools: github: mode: remote - github-token: ${{ secrets.MAIN_REPO_PAT }} # Explicit token for tools + github-token: ${{ secrets.GH_AW_MAIN_REPO_TOKEN }} # Explicit token for tools toolsets: [repos, issues, pull_requests] ``` @@ -217,7 +217,7 @@ Run triage workflows on main repository issues: on: every 6h safe-outputs: - github-token: ${{ secrets.MAIN_REPO_PAT }} + github-token: ${{ secrets.GH_AW_MAIN_REPO_TOKEN }} add-labels: target-repo: "my-org/main-repo" add-comment: @@ -243,7 +243,7 @@ Monitor main repository for quality issues: on: weekly on monday safe-outputs: - github-token: ${{ secrets.MAIN_REPO_PAT }} + github-token: ${{ secrets.GH_AW_MAIN_REPO_TOKEN }} create-issue: target-repo: "my-org/main-repo" labels: [code-quality, automation] @@ -280,7 +280,7 @@ on: default: "docs/" safe-outputs: - github-token: ${{ secrets.MAIN_REPO_PAT }} + github-token: ${{ secrets.GH_AW_MAIN_REPO_TOKEN }} create-pull-request: target-repo: "my-org/main-repo" base-branch: main @@ -302,7 +302,7 @@ Create a PR with suggested improvements. ### Authentication Failures -If you see "Resource not accessible by integration" errors, verify your PAT has access to the target repository, check permissions include required scopes, ensure the PAT hasn't expired, and confirm `github-token: ${{ secrets.MAIN_REPO_PAT }}` is configured (not `GITHUB_TOKEN`). +If you see "Resource not accessible by integration" errors, verify your PAT has access to the target repository, check permissions include required scopes, ensure the PAT hasn't expired, and confirm `github-token: ${{ secrets.GH_AW_MAIN_REPO_TOKEN }}` is configured (not `GITHUB_TOKEN`). ### GitHub Tools Not Working @@ -312,7 +312,7 @@ If the agent cannot read files from the main repository, use `mode: remote` for tools: github: mode: remote - github-token: ${{ secrets.MAIN_REPO_PAT }} + github-token: ${{ secrets.GH_AW_MAIN_REPO_TOKEN }} toolsets: [repos] ``` @@ -358,7 +358,7 @@ on: required: true safe-outputs: - github-token: ${{ secrets.MULTI_REPO_PAT }} + github-token: ${{ secrets.GH_AW_MULTI_REPO_PAT }} create-issue: target-repo: ${{ inputs.target_repo }} # Dynamic target --- @@ -385,7 +385,7 @@ on: types: [opened, labeled] safe-outputs: - github-token: ${{ secrets.SIDE_REPO_PAT }} + github-token: ${{ secrets.GH_AW_SIDE_REPO_TOKEN }} add-comment: target-repo: "my-org/automation-repo" ``` @@ -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..764726b5cf --- /dev/null +++ b/docs/src/content/docs/reference/assign-to-copilot.mdx @@ -0,0 +1,117 @@ +--- +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 Copilot coding agent to **existing** issues or PRs through workflow automation. + +If you're creating new issues and want to assign Copilot coding 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. + +**Using a Personal Access Token (PAT)**: + +The required token type and permissions depend on whether you own the repository or an organization owns it. + +1. **Create the PAT**: + + For User-owned Repositories, [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: [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 + +2. Add to repository secrets: + + ```bash wrap + gh aw secrets set GH_AW_AGENT_TOKEN --value "YOUR_AGENT_PAT" + ``` + +**Using a GitHub App**: + +Alternatively, you can use a GitHub App with appropriate permissions instead of a PAT for enhanced security. + +**Using a magic secret**: + +Alternatively, you can set the magic secret `GH_AW_AGENT_TOKEN` to a suitable PAT (see the above guide for creating one). This secret name is known to GitHub Agentic Workflows and does not need to be explicitly referenced in your workflow. + +