From 681ac61a62e64aabc7d431c5a7b68021b6b777bb Mon Sep 17 00:00:00 2001 From: Landon Cox Date: Wed, 25 Mar 2026 08:25:40 -0700 Subject: [PATCH 1/4] docs: add consolidated token reference page Comprehensive reference documenting all tokens and secrets used by agentic workflows: AI engine tokens, GitHub API tokens, purpose-specific tokens, GitHub App tokens, internal runtime tokens, and full precedence chains for each token resolution context. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/astro.config.mjs | 1 + docs/src/content/docs/reference/auth.mdx | 1 + docs/src/content/docs/reference/tokens.md | 466 ++++++++++++++++++++++ 3 files changed, 468 insertions(+) create mode 100644 docs/src/content/docs/reference/tokens.md diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index d614656a88e..d5fb960e67f 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -326,6 +326,7 @@ export default defineConfig({ { label: 'Schedule Syntax', link: '/reference/schedule-syntax/' }, { label: 'Templating', link: '/reference/templating/' }, { label: 'Threat Detection', link: '/reference/threat-detection/' }, + { label: 'Token Reference', link: '/reference/tokens/' }, { label: 'Tools', link: '/reference/tools/' }, { label: 'Triggering CI', link: '/reference/triggering-ci/' }, { label: 'Triggers', link: '/reference/triggers/' }, diff --git a/docs/src/content/docs/reference/auth.mdx b/docs/src/content/docs/reference/auth.mdx index 185281dcea1..7137c4f21ba 100644 --- a/docs/src/content/docs/reference/auth.mdx +++ b/docs/src/content/docs/reference/auth.mdx @@ -206,6 +206,7 @@ For both tool authentication and safe outputs, you can scope the GitHub App toke ## Related Documentation +- [Token Reference](/gh-aw/reference/tokens/) - Consolidated reference for all tokens, precedence chains, and permissions - [Engines](/gh-aw/reference/engines/) - Engine-specific authentication - [Safe Outputs](/gh-aw/reference/safe-outputs/) - Safe output token configuration - [Tools](/gh-aw/reference/tools/) - Tool authentication and modes diff --git a/docs/src/content/docs/reference/tokens.md b/docs/src/content/docs/reference/tokens.md new file mode 100644 index 00000000000..bccf7042adf --- /dev/null +++ b/docs/src/content/docs/reference/tokens.md @@ -0,0 +1,466 @@ +--- +title: Token Reference +description: Comprehensive reference for all tokens, secrets, and credentials used by GitHub Agentic Workflows +sidebar: + order: 660 +--- + +This page is a consolidated reference for every token and secret used by GitHub Agentic Workflows — where each comes from, what permissions it needs, and what it is used for. + +## Quick Reference + +| Secret Name | Purpose | Required? | Fallback | +|---|---|---|---| +| [`COPILOT_GITHUB_TOKEN`](#copilot_github_token) | Copilot CLI authentication | Yes (Copilot engine) | None | +| [`ANTHROPIC_API_KEY`](#anthropic_api_key) | Claude engine authentication | Yes (Claude engine) | None | +| [`OPENAI_API_KEY`](#openai_api_key) | Codex engine authentication | Yes (Codex engine) | `CODEX_API_KEY` | +| [`GEMINI_API_KEY`](#gemini_api_key) | Gemini engine authentication | Yes (Gemini engine) | None | +| [`GH_AW_GITHUB_MCP_SERVER_TOKEN`](#gh_aw_github_mcp_server_token) | GitHub MCP server authentication | Optional | `GH_AW_GITHUB_TOKEN` → `GITHUB_TOKEN` | +| [`GH_AW_GITHUB_TOKEN`](#gh_aw_github_token) | General-purpose GitHub token | Optional | `GITHUB_TOKEN` | +| [`GH_AW_AGENT_TOKEN`](#gh_aw_agent_token) | Assign AI agents to issues/PRs | Optional | `GH_AW_GITHUB_TOKEN` → `GITHUB_TOKEN` | +| [`GH_AW_PROJECT_GITHUB_TOKEN`](#gh_aw_project_github_token) | GitHub Projects v2 operations | Yes (Projects) | None | +| [`GH_AW_CI_TRIGGER_TOKEN`](#gh_aw_ci_trigger_token) | Trigger CI on workflow-created PRs | Yes (CI trigger) | None | +| [`GH_AW_PLUGINS_TOKEN`](#gh_aw_plugins_token) | APM plugin/dependency access | Optional | `GH_AW_GITHUB_TOKEN` → `GITHUB_TOKEN` | +| [`APP_ID` / `APP_PRIVATE_KEY`](#github-app-tokens) | GitHub App authentication | Optional | PAT-based tokens | +| [`GITHUB_TOKEN`](#github_token) | Default GitHub Actions token | Automatic | None (always available) | + +## AI Engine Tokens + +These tokens authenticate the AI coding agent. Exactly one is required, depending on which engine your workflow uses. + +### `COPILOT_GITHUB_TOKEN` + +Authenticates the [GitHub Copilot CLI](/gh-aw/reference/engines/#github-copilot-default) as the AI engine. + +| Property | Value | +|---|---| +| **Source** | User-created fine-grained PAT stored as repository secret | +| **Required** | Yes, when using `engine: copilot` (the default engine) | +| **Permissions** | Account permission: **Copilot Requests: Read** | +| **Resource owner** | Must be the user's **personal account**, not an organization | +| **Fallback** | None — the `GITHUB_TOKEN` does not have Copilot permissions | +| **Used by** | Copilot CLI inference step, secret validation, Copilot-related safe outputs | + +When the `copilot-requests` [feature flag](/gh-aw/reference/frontmatter/#features) is enabled, the compiler uses `${{ github.token }}` instead of this secret, allowing the built-in GitHub Actions token to authenticate Copilot directly. + +**Setup:** + +```bash wrap +gh aw secrets set COPILOT_GITHUB_TOKEN --value "" +``` + +See [Authentication](/gh-aw/reference/auth/#copilot_github_token) for detailed setup instructions. + +--- + +### `ANTHROPIC_API_KEY` + +Authenticates the [Claude by Anthropic](/gh-aw/reference/engines/#claude-by-anthropic) engine. + +| Property | Value | +|---|---| +| **Source** | Anthropic API key stored as repository secret | +| **Required** | Yes, when using `engine: claude` | +| **Permissions** | Anthropic API access (external service) | +| **Fallback** | None | +| **Used by** | Claude inference step | + +```bash wrap +gh aw secrets set ANTHROPIC_API_KEY --value "" +``` + +--- + +### `OPENAI_API_KEY` + +Authenticates the [Codex by OpenAI](/gh-aw/reference/engines/#codex-by-openai) engine. + +| Property | Value | +|---|---| +| **Source** | OpenAI API key stored as repository secret | +| **Required** | Yes, when using `engine: codex` | +| **Permissions** | OpenAI API access (external service) | +| **Fallback** | `CODEX_API_KEY` (alternative secret name) | +| **Used by** | Codex inference step | + +```bash wrap +gh aw secrets set OPENAI_API_KEY --value "" +``` + +--- + +### `GEMINI_API_KEY` + +Authenticates the [Gemini by Google](/gh-aw/reference/engines/#gemini-by-google) engine. + +| Property | Value | +|---|---| +| **Source** | Google AI Studio API key stored as repository secret | +| **Required** | Yes, when using `engine: gemini` | +| **Permissions** | Google AI Studio API access (external service) | +| **Fallback** | None | +| **Used by** | Gemini inference step | + +```bash wrap +gh aw secrets set GEMINI_API_KEY --value "" +``` + +--- + +## GitHub API Tokens + +These tokens control access to the GitHub API across different parts of a compiled workflow. + +### `GH_AW_GITHUB_MCP_SERVER_TOKEN` + +The primary token for authenticating GitHub API operations through the [GitHub MCP server](/gh-aw/reference/github-tools/). This is a **"magic secret"** — if present in repository secrets, it is automatically used without being referenced in your workflow frontmatter. + +| Property | Value | +|---|---| +| **Source** | User-created PAT stored as repository secret | +| **Required** | Depends on mode — required for [remote mode](/gh-aw/reference/github-tools/#remote-vs-local-mode) and [lockdown mode](/gh-aw/reference/lockdown-mode/) | +| **Permissions** | Depends on [toolsets](/gh-aw/reference/github-tools/#github-toolsets) used (e.g., repo scope for repos toolset, project scope for projects) | +| **Fallback** | `GH_AW_GITHUB_TOKEN` → `GITHUB_TOKEN` | +| **Used by** | GitHub MCP server (local and remote modes), guard policy enforcement | + +**How the magic secret works:** The compiler automatically injects this token into the workflow-level environment. You do not need to reference it in your frontmatter — if the secret exists in your repository, it is used. The resolved expression is: + +```yaml wrap +${{ secrets.GH_AW_GITHUB_MCP_SERVER_TOKEN || secrets.GH_AW_GITHUB_TOKEN || secrets.GITHUB_TOKEN }} +``` + +**When additional permissions are needed:** +- **Remote mode**: Requires a PAT (classic or fine-grained) — the default `GITHUB_TOKEN` is not sufficient +- **Lockdown mode**: Requires a PAT for elevated access control +- **Projects toolset**: Requires `project` scope (see [Authentication (Projects)](/gh-aw/reference/auth-projects/)) +- **Cross-repository access**: Requires access to the target repositories + +```bash wrap +gh aw secrets set GH_AW_GITHUB_MCP_SERVER_TOKEN --value "" +``` + +--- + +### `GH_AW_GITHUB_TOKEN` + +A general-purpose GitHub token that serves as a fallback across multiple token chains. Use this when you want a single PAT to cover multiple workflow operations without configuring purpose-specific tokens. + +| Property | Value | +|---|---| +| **Source** | User-created PAT stored as repository secret | +| **Required** | Optional — provides a middle-tier fallback | +| **Permissions** | Depends on operations (typically `repo` scope) | +| **Fallback** | `GITHUB_TOKEN` | +| **Used by** | MCP server (when `GH_AW_GITHUB_MCP_SERVER_TOKEN` is not set), safe outputs, agent assignment, APM dependencies | + +This token appears in the fallback chain of almost every token resolution function. It is a good choice when you need a PAT with broader permissions than `GITHUB_TOKEN` but don't want to configure multiple purpose-specific secrets. + +--- + +### `GITHUB_TOKEN` + +The default token automatically provided by GitHub Actions to every workflow run. It is repository-scoped and cannot access cross-repo resources, Projects v2, or trigger other workflows. + +| Property | Value | +|---|---| +| **Source** | Automatically provided by GitHub Actions | +| **Required** | No (always available) | +| **Permissions** | Repository-scoped, controlled by workflow `permissions:` block | +| **Fallback** | None (this is the final fallback) | +| **Used by** | Last-resort fallback for MCP server, safe outputs, `gh` CLI, checkout steps | + +> [!CAUTION] +> `GITHUB_TOKEN` cannot access GitHub Projects v2, trigger other workflow runs, or access resources outside the current repository. Use purpose-specific tokens for those operations. + +--- + +## Purpose-Specific Tokens + +These tokens serve specific workflow features and have tailored fallback chains. + +### `GH_AW_AGENT_TOKEN` + +Used when a workflow assigns an AI coding agent (e.g., Copilot coding agent) to issues or pull requests via [safe outputs](/gh-aw/reference/assign-to-copilot/). + +| Property | Value | +|---|---| +| **Source** | User-created PAT stored as repository secret | +| **Required** | Recommended for agent assignment operations | +| **Permissions** | `issues: write`, `pull_requests: write`, and bot assignment permissions | +| **Fallback** | `GH_AW_GITHUB_TOKEN` → `GITHUB_TOKEN` (may lack permissions) | +| **Used by** | `assign-to-copilot` safe output, agent assignment steps | + +```bash wrap +gh aw secrets set GH_AW_AGENT_TOKEN --value "" +``` + +--- + +### `GH_AW_PROJECT_GITHUB_TOKEN` + +Used for GitHub Projects v2 operations. This token has **no fallback** because the default `GITHUB_TOKEN` cannot access the Projects GraphQL API. + +| Property | Value | +|---|---| +| **Source** | User-created PAT stored as repository secret | +| **Required** | Yes, for any Projects v2 operation | +| **Permissions** | Classic PAT: `project` + `repo` scopes. Fine-grained: Organization permissions → Projects: Read and write | +| **Fallback** | None — `GITHUB_TOKEN` cannot access Projects v2 | +| **Used by** | `update-project`, `create-project`, `create-project-status-update` safe outputs, `projects` toolset | + +```bash wrap +gh aw secrets set GH_AW_PROJECT_GITHUB_TOKEN --value "" +``` + +For separate read/write tokens, see [Authentication (Projects)](/gh-aw/reference/auth-projects/#recommended-secret-layout). + +--- + +### `GH_AW_CI_TRIGGER_TOKEN` + +Used when a workflow needs to push commits that trigger CI checks on pull requests it creates. This token has **no fallback** because events created with `GITHUB_TOKEN` [do not trigger other workflow runs](https://docs.github.com/en/actions/using-workflows/triggering-a-workflow#triggering-a-workflow-from-a-workflow) by design. + +| Property | Value | +|---|---| +| **Source** | User-created PAT stored as repository secret | +| **Required** | Yes, when using [CI triggering](/gh-aw/reference/triggering-ci/) | +| **Permissions** | `contents: write` on the target repository | +| **Fallback** | None — `GITHUB_TOKEN` events cannot trigger workflows | +| **Used by** | Empty commit push step for CI triggering on workflow-created PRs | + +```bash wrap +gh aw secrets set GH_AW_CI_TRIGGER_TOKEN --value "" +``` + +See [Triggering CI](/gh-aw/reference/triggering-ci/) for usage details. + +--- + +### `GH_AW_PLUGINS_TOKEN` + +Used for APM (Agentic Package Manager) plugin and dependency operations, such as fetching packages from private registries or cross-organization repositories. + +| Property | Value | +|---|---| +| **Source** | User-created PAT stored as repository secret | +| **Required** | Optional — only needed for private/cross-org dependencies | +| **Permissions** | `repo` scope for accessing private repositories containing plugins | +| **Fallback** | `GH_AW_GITHUB_TOKEN` → `GITHUB_TOKEN` | +| **Used by** | APM dependency resolution and installation steps | + +```bash wrap +gh aw secrets set GH_AW_PLUGINS_TOKEN --value "" +``` + +--- + +## GitHub App Tokens + +For enhanced security, you can configure a [GitHub App](https://docs.github.com/en/apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps) instead of PATs. App tokens are short-lived, automatically scoped, and revoked at workflow end. + +### Configuration + +Store the App ID as a repository **variable** and the private key as a repository **secret**: + +```bash wrap +gh variable set APP_ID --body "123456" +gh aw secrets set APP_PRIVATE_KEY --value "$(cat path/to/private-key.pem)" +``` + +Reference them in your workflow frontmatter: + +```yaml wrap +tools: + github: + github-app: + app-id: ${{ vars.APP_ID }} + private-key: ${{ secrets.APP_PRIVATE_KEY }} + owner: "my-org" # Optional: defaults to current repo owner + repositories: ["repo1", "repo2"] # Optional: defaults to current repo only +``` + +### How App tokens work + +When a GitHub App is configured, the compiler generates [`actions/create-github-app-token`](https://github.com/actions/create-github-app-token) steps that mint short-lived installation access tokens at workflow runtime. These tokens: + +- **Override all PAT-based tokens** — when configured, App tokens take highest precedence +- **Are scoped to the job's `permissions:` block** — the token receives only the permissions declared in your workflow +- **Are automatically revoked** at the end of the workflow run (even on failure) +- **Support repository scoping** — limit access to specific repositories for least privilege + +### Where App tokens are minted + +The compiler generates App token mint steps in multiple locations depending on what features your workflow uses: + +| Location | Step ID | Used For | +|---|---|---| +| Pre-activation job | `pre-activation-app-token` | Membership checks, skip-if evaluations | +| Agent job (GitHub MCP) | `github-mcp-app-token` | GitHub MCP server authentication | +| Safe outputs job | `safe-outputs-app-token` | Write operations (issues, PRs, comments) | +| APM dependencies | `apm-app-token` | Plugin and dependency access | + +Each mint step includes `github-api-url: ${{ github.api_url }}` for [GitHub Enterprise compatibility](/gh-aw/troubleshooting/debug-ghe/). + +### App token vs PAT precedence + +When a GitHub App is configured, it always takes precedence: + +``` +GitHub App token (highest priority) + └── Custom github-token field + └── Purpose-specific secret (e.g., GH_AW_GITHUB_MCP_SERVER_TOKEN) + └── GH_AW_GITHUB_TOKEN + └── GITHUB_TOKEN (lowest priority) +``` + +> [!NOTE] +> `COPILOT_GITHUB_TOKEN` is the one token that **cannot** use a GitHub App. It must be a fine-grained PAT with Copilot Requests permission on a personal account. + +See [Authentication](/gh-aw/reference/auth/#using-a-github-app-for-authentication) for full GitHub App setup instructions. + +--- + +## Internal Runtime Tokens + +These tokens are set by the compiler at workflow runtime. You do not configure them as repository secrets — they are derived from the tokens above. + +### `GITHUB_MCP_SERVER_TOKEN` + +An environment variable set on the agent job step that carries the resolved GitHub token into the MCP gateway container. Its value is determined by the [token precedence chain](#token-precedence-chains) and may be a GitHub App token, a custom PAT, or the default `GITHUB_TOKEN`. + +| Property | Value | +|---|---| +| **Source** | Compiler-generated from configured tokens | +| **Set on** | Agent job steps, MCP gateway Docker container | +| **Resolves to** | App token → custom `github-token` → `GH_AW_GITHUB_MCP_SERVER_TOKEN` → `GH_AW_GITHUB_TOKEN` → `GITHUB_TOKEN` | + +### `GITHUB_PERSONAL_ACCESS_TOKEN` + +An environment variable passed to the GitHub MCP server Docker container. It carries the same resolved token as `GITHUB_MCP_SERVER_TOKEN` and is used internally by the MCP server process. + +### `GH_TOKEN` + +Set on various workflow steps (checkout, `gh` CLI commands, pre-agentic steps) to authenticate GitHub CLI operations. Typically resolves to `${{ github.token }}` or a minted App token. + +--- + +## Token Precedence Chains + +The compiler uses different precedence chains depending on the operation context. Each chain is a cascade expression — the first non-empty secret wins. + +### GitHub MCP Server + +``` +getEffectiveGitHubToken(): + 1. Custom github-token (from tools.github.github-token) + 2. GH_AW_GITHUB_MCP_SERVER_TOKEN + 3. GH_AW_GITHUB_TOKEN + 4. GITHUB_TOKEN +``` + +If a GitHub App is configured, the App token overrides this entire chain. + +### Safe Outputs + +``` +getEffectiveSafeOutputGitHubToken(): + 1. Custom github-token (from safe-outputs..github-token) + 2. GH_AW_GITHUB_TOKEN + 3. GITHUB_TOKEN +``` + +> [!NOTE] +> `GH_AW_GITHUB_MCP_SERVER_TOKEN` is intentionally **not** in the safe outputs chain. Safe outputs use a simpler chain because MCP server-specific tokens should not leak into write operations. + +### Copilot Operations + +``` +getEffectiveCopilotRequestsToken(): + 1. Custom github-token + 2. COPILOT_GITHUB_TOKEN + (no further fallback) +``` + +### Agent Assignment + +``` +getEffectiveCopilotCodingAgentGitHubToken(): + 1. Custom github-token + 2. GH_AW_AGENT_TOKEN + 3. GH_AW_GITHUB_TOKEN + 4. GITHUB_TOKEN +``` + +### Projects v2 + +``` +getEffectiveProjectGitHubToken(): + 1. Custom github-token + 2. GH_AW_PROJECT_GITHUB_TOKEN + (no further fallback) +``` + +### CI Triggering + +``` +getEffectiveCITriggerGitHubToken(): + 1. Custom github-token + 2. GH_AW_CI_TRIGGER_TOKEN + (no further fallback) +``` + +### APM Dependencies + +``` +getEffectiveAPMGitHubToken(): + 1. Custom github-token (from dependencies.github-token) + 2. GH_AW_PLUGINS_TOKEN + 3. GH_AW_GITHUB_TOKEN + 4. GITHUB_TOKEN +``` + +--- + +## Overriding Tokens with `github-token` + +Many workflow features accept an explicit `github-token` field that takes highest priority in the precedence chain (above any repository secret): + +```yaml wrap +tools: + github: + github-token: ${{ secrets.MY_CUSTOM_PAT }} + +safe-outputs: + create-issue: + github-token: ${{ secrets.MY_ISSUES_PAT }} + update-project: + github-token: ${{ secrets.MY_PROJECT_PAT }} +``` + +This allows fine-grained control over which token is used for each operation, independent of the default fallback chains. + +--- + +## Tokens That Do Not Fall Back to `GITHUB_TOKEN` + +Three tokens intentionally have **no fallback** to `GITHUB_TOKEN` because the default token lacks the necessary capabilities: + +| Token | Reason `GITHUB_TOKEN` cannot be used | +|---|---| +| `COPILOT_GITHUB_TOKEN` | `GITHUB_TOKEN` does not have Copilot Requests permission | +| `GH_AW_PROJECT_GITHUB_TOKEN` | `GITHUB_TOKEN` is repository-scoped and cannot access the Projects v2 GraphQL API | +| `GH_AW_CI_TRIGGER_TOKEN` | Events created by `GITHUB_TOKEN` [do not trigger other workflows](https://docs.github.com/en/actions/using-workflows/triggering-a-workflow#triggering-a-workflow-from-a-workflow) | + +If these secrets are not configured and no custom `github-token` is provided, the relevant workflow steps will fail at runtime. + +--- + +## Related Documentation + +- [Authentication](/gh-aw/reference/auth/) — AI engine secrets and GitHub App setup +- [Authentication (Projects)](/gh-aw/reference/auth-projects/) — Projects-specific token configuration +- [GitHub Tools](/gh-aw/reference/github-tools/) — MCP server modes and toolset authentication +- [Permissions](/gh-aw/reference/permissions/) — Permission model and scopes +- [Environment Variables](/gh-aw/reference/environment-variables/) — Environment variable scopes and precedence +- [Triggering CI](/gh-aw/reference/triggering-ci/) — CI trigger token usage +- [Lockdown Mode](/gh-aw/reference/lockdown-mode/) — Elevated authentication requirements From bdacf9b4eb1d8ba341703b2e65c6585072bd2418 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 25 Mar 2026 22:13:34 +0000 Subject: [PATCH 2/4] docs: fix Codex token resolution order in tokens.md Agent-Logs-Url: https://github.com/github/gh-aw/sessions/f47f1723-1148-49ad-8cd5-c3d5eeac6d72 Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- docs/src/content/docs/reference/tokens.md | 4 ++-- pkg/workflow/schemas/github-workflow.json | 23 +++++++++++++++++++++-- 2 files changed, 23 insertions(+), 4 deletions(-) diff --git a/docs/src/content/docs/reference/tokens.md b/docs/src/content/docs/reference/tokens.md index bccf7042adf..384509bd75b 100644 --- a/docs/src/content/docs/reference/tokens.md +++ b/docs/src/content/docs/reference/tokens.md @@ -13,7 +13,7 @@ This page is a consolidated reference for every token and secret used by GitHub |---|---|---|---| | [`COPILOT_GITHUB_TOKEN`](#copilot_github_token) | Copilot CLI authentication | Yes (Copilot engine) | None | | [`ANTHROPIC_API_KEY`](#anthropic_api_key) | Claude engine authentication | Yes (Claude engine) | None | -| [`OPENAI_API_KEY`](#openai_api_key) | Codex engine authentication | Yes (Codex engine) | `CODEX_API_KEY` | +| [`OPENAI_API_KEY`](#openai_api_key) | Codex engine authentication | Yes (Codex engine) | `CODEX_API_KEY` → `OPENAI_API_KEY` | | [`GEMINI_API_KEY`](#gemini_api_key) | Gemini engine authentication | Yes (Gemini engine) | None | | [`GH_AW_GITHUB_MCP_SERVER_TOKEN`](#gh_aw_github_mcp_server_token) | GitHub MCP server authentication | Optional | `GH_AW_GITHUB_TOKEN` → `GITHUB_TOKEN` | | [`GH_AW_GITHUB_TOKEN`](#gh_aw_github_token) | General-purpose GitHub token | Optional | `GITHUB_TOKEN` | @@ -80,7 +80,7 @@ Authenticates the [Codex by OpenAI](/gh-aw/reference/engines/#codex-by-openai) e | **Source** | OpenAI API key stored as repository secret | | **Required** | Yes, when using `engine: codex` | | **Permissions** | OpenAI API access (external service) | -| **Fallback** | `CODEX_API_KEY` (alternative secret name) | +| **Fallback** | None — the Codex engine resolves `CODEX_API_KEY` first, then `OPENAI_API_KEY` (`${{ secrets.CODEX_API_KEY \|\| secrets.OPENAI_API_KEY }}`) | | **Used by** | Codex inference step | ```bash wrap diff --git a/pkg/workflow/schemas/github-workflow.json b/pkg/workflow/schemas/github-workflow.json index 9c5ed2c6ea0..afa39b90149 100644 --- a/pkg/workflow/schemas/github-workflow.json +++ b/pkg/workflow/schemas/github-workflow.json @@ -257,6 +257,19 @@ "$comment": "https://docs.github.com/en/free-pro-team@latest/actions/reference/workflow-syntax-for-github-actions#example-using-environment-name-and-url", "description": "A deployment URL", "type": "string" + }, + "deployment": { + "$comment": "https://docs.github.com/en/actions/how-tos/deploy/configure-and-manage-deployments/control-deployments#using-environments-without-deployments", + "description": "Whether to create a deployment for this job. Setting to false lets the job use environment secrets and variables without creating a deployment record. Wait timers and required reviewers still apply.", + "oneOf": [ + { + "type": "boolean" + }, + { + "$ref": "#/definitions/expressionSyntax" + } + ], + "default": true } }, "required": ["name"], @@ -1656,16 +1669,22 @@ "description": "You can use the GitHub API to trigger a webhook event called repository_dispatch when you want to trigger a workflow for activity that happens outside of GitHub. For more information, see https://developer.github.com/v3/repos/#create-a-repository-dispatch-event.\nTo trigger the custom repository_dispatch webhook event, you must send a POST request to a GitHub API endpoint and provide an event_type name to describe the activity type. To trigger a workflow run, you must also configure your workflow to use the repository_dispatch event." }, "schedule": { - "$comment": "https://help.github.com/en/github/automating-your-workflow-with-github-actions/events-that-trigger-workflows#scheduled-events-schedule", - "description": "You can schedule a workflow to run at specific UTC times using POSIX cron syntax (https://pubs.opengroup.org/onlinepubs/9699919799/utilities/crontab.html#tag_20_25_07). Scheduled workflows run on the latest commit on the default or base branch. The shortest interval you can run scheduled workflows is once every 5 minutes.\nNote: GitHub Actions does not support the non-standard syntax @yearly, @monthly, @weekly, @daily, @hourly, and @reboot.\nYou can use crontab guru (https://crontab.guru/). to help generate your cron syntax and confirm what time it will run. To help you get started, there is also a list of crontab guru examples (https://crontab.guru/examples.html).", + "$comment": "https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#schedule", + "description": "You can schedule a workflow to run at specific UTC times using POSIX cron syntax (https://pubs.opengroup.org/onlinepubs/9699919799/utilities/crontab.html#tag_20_25_07). You can optionally specify a timezone using an IANA timezone string (https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) for timezone-aware scheduling. Scheduled workflows run on the latest commit on the default or base branch. The shortest interval you can run scheduled workflows is once every 5 minutes.\nNote: GitHub Actions does not support the non-standard syntax @yearly, @monthly, @weekly, @daily, @hourly, and @reboot.\nYou can use crontab guru (https://crontab.guru/) to help generate your cron syntax and confirm what time it will run. To help you get started, there is also a list of crontab guru examples (https://crontab.guru/examples.html).", "type": "array", "items": { "type": "object", "properties": { "cron": { + "description": "A cron expression that represents a schedule. A scheduled workflow will run at most once every 5 minutes.", + "type": "string" + }, + "timezone": { + "description": "A string that represents the time zone a scheduled workflow will run relative to in IANA format (e.g. 'America/New_York' or 'Europe/London'). If omitted, the workflow will run relative to midnight UTC.", "type": "string" } }, + "required": ["cron"], "additionalProperties": false }, "minItems": 1 From 970ef66168af4644166493a75ebf02e627176461 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 25 Mar 2026 22:14:17 +0000 Subject: [PATCH 3/4] docs: remove unnecessary escape sequences in markdown table Agent-Logs-Url: https://github.com/github/gh-aw/sessions/f47f1723-1148-49ad-8cd5-c3d5eeac6d72 Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- docs/src/content/docs/reference/tokens.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/content/docs/reference/tokens.md b/docs/src/content/docs/reference/tokens.md index 384509bd75b..814ea5f0579 100644 --- a/docs/src/content/docs/reference/tokens.md +++ b/docs/src/content/docs/reference/tokens.md @@ -80,7 +80,7 @@ Authenticates the [Codex by OpenAI](/gh-aw/reference/engines/#codex-by-openai) e | **Source** | OpenAI API key stored as repository secret | | **Required** | Yes, when using `engine: codex` | | **Permissions** | OpenAI API access (external service) | -| **Fallback** | None — the Codex engine resolves `CODEX_API_KEY` first, then `OPENAI_API_KEY` (`${{ secrets.CODEX_API_KEY \|\| secrets.OPENAI_API_KEY }}`) | +| **Fallback** | None — the Codex engine resolves `CODEX_API_KEY` first, then `OPENAI_API_KEY` (resolution order: `CODEX_API_KEY` → `OPENAI_API_KEY`) | | **Used by** | Codex inference step | ```bash wrap From b8761f253249abc67b367a7b28fcbb5cd7ae38d6 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 26 Mar 2026 03:50:36 +0000 Subject: [PATCH 4/4] docs: fix inaccuracies found during token cross-reference review Agent-Logs-Url: https://github.com/github/gh-aw/sessions/454cd983-9767-4419-9c54-6739fd54db76 Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- docs/src/content/docs/reference/tokens.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/src/content/docs/reference/tokens.md b/docs/src/content/docs/reference/tokens.md index 814ea5f0579..1afa414c069 100644 --- a/docs/src/content/docs/reference/tokens.md +++ b/docs/src/content/docs/reference/tokens.md @@ -80,7 +80,7 @@ Authenticates the [Codex by OpenAI](/gh-aw/reference/engines/#codex-by-openai) e | **Source** | OpenAI API key stored as repository secret | | **Required** | Yes, when using `engine: codex` | | **Permissions** | OpenAI API access (external service) | -| **Fallback** | None — the Codex engine resolves `CODEX_API_KEY` first, then `OPENAI_API_KEY` (resolution order: `CODEX_API_KEY` → `OPENAI_API_KEY`) | +| **Fallback** | Both `CODEX_API_KEY` and `OPENAI_API_KEY` are accepted; the runtime tries `CODEX_API_KEY` first (`${{ secrets.CODEX_API_KEY \|\| secrets.OPENAI_API_KEY }}`). No fallback to `GITHUB_TOKEN`. | | **Used by** | Codex inference step | ```bash wrap @@ -295,6 +295,7 @@ The compiler generates App token mint steps in multiple locations depending on w | Location | Step ID | Used For | |---|---|---| | Pre-activation job | `pre-activation-app-token` | Membership checks, skip-if evaluations | +| Activation job | `activation-app-token` | Reactions, status comments, label removal | | Agent job (GitHub MCP) | `github-mcp-app-token` | GitHub MCP server authentication | | Safe outputs job | `safe-outputs-app-token` | Write operations (issues, PRs, comments) | | APM dependencies | `apm-app-token` | Plugin and dependency access |