From 92598febd8cbe54de171f7baa7d351fd941b4ed0 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Thu, 16 Apr 2026 11:02:03 +0000 Subject: [PATCH] docs: document byok-copilot flag, client-id migration, and status-comment object form - Add byok-copilot feature flag subsection to frontmatter.md (from #26544: bundles cli-proxy, COPILOT_API_KEY injection, and latest Copilot CLI install behind a single flag) - Update all github-app examples to use client-id (preferred) instead of app-id (deprecated alias) across auth.mdx, checkout.md, faq.md, imports.md, safe-outputs.md, safe-outputs-pull-requests.md, tokens.md, triggers.md, and glossary.md (from #26551: run gh aw fix to auto-migrate) - Add object-form documentation for status-comment in triggers.md, with issues/pull-requests/discussions toggle fields (from #26535) - Update status-comment description in frontmatter.md to mention object form Co-Authored-By: Claude Sonnet 4.6 --- docs/src/content/docs/reference/auth.mdx | 4 +-- docs/src/content/docs/reference/checkout.md | 4 +-- docs/src/content/docs/reference/faq.md | 2 +- .../src/content/docs/reference/frontmatter.md | 17 ++++++++- docs/src/content/docs/reference/glossary.md | 2 +- docs/src/content/docs/reference/imports.md | 2 +- .../reference/safe-outputs-pull-requests.md | 2 +- .../content/docs/reference/safe-outputs.md | 2 +- docs/src/content/docs/reference/tokens.md | 2 +- docs/src/content/docs/reference/triggers.md | 35 ++++++++++++++++--- 10 files changed, 57 insertions(+), 15 deletions(-) diff --git a/docs/src/content/docs/reference/auth.mdx b/docs/src/content/docs/reference/auth.mdx index 89209639ce9..74fae2521c5 100644 --- a/docs/src/content/docs/reference/auth.mdx +++ b/docs/src/content/docs/reference/auth.mdx @@ -234,7 +234,7 @@ tools: mode: remote toolsets: [repos, issues, pull_requests] github-app: - app-id: ${{ vars.APP_ID }} + client-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 @@ -254,7 +254,7 @@ You can also use GitHub App tokens for safe outputs operations: ```yaml wrap safe-outputs: github-app: - app-id: ${{ vars.APP_ID }} + client-id: ${{ vars.APP_ID }} private-key: ${{ secrets.APP_PRIVATE_KEY }} owner: "my-org" # optional: installation owner repositories: ["repo1", "repo2"] # optional: scope to specific repos diff --git a/docs/src/content/docs/reference/checkout.md b/docs/src/content/docs/reference/checkout.md index cea3db64407..d95e25509a3 100644 --- a/docs/src/content/docs/reference/checkout.md +++ b/docs/src/content/docs/reference/checkout.md @@ -27,7 +27,7 @@ Or use GitHub App authentication: checkout: fetch-depth: 0 github-app: - app-id: ${{ vars.APP_ID }} + client-id: ${{ vars.APP_ID }} private-key: ${{ secrets.APP_PRIVATE_KEY }} ``` @@ -50,7 +50,7 @@ checkout: | `ref` | string | Branch, tag, or SHA to checkout. Defaults to the triggering ref. | | `path` | string | Path within `GITHUB_WORKSPACE` to place the checkout. Defaults to workspace root. | | `github-token` | string | Token for authentication. Use `${{ secrets.MY_TOKEN }}` syntax. | -| `github-app` | object | GitHub App credentials (`app-id`, `private-key`, optional `owner`, `repositories`). Mutually exclusive with `github-token`. `app` is a deprecated alias. | +| `github-app` | object | GitHub App credentials (`client-id` or `app-id` (deprecated), `private-key`, optional `owner`, `repositories`). Mutually exclusive with `github-token`. `app` is a deprecated alias for the field name. Run `gh aw fix` to auto-migrate `app-id` to `client-id`. | | `fetch-depth` | integer | Commits to fetch. `0` = full history, `1` = shallow clone (default). | | `fetch` | string \| string[] | Additional Git refs to fetch after checkout. See [Fetching Additional Refs](#fetching-additional-refs). | | `sparse-checkout` | string | Newline-separated patterns for sparse checkout (e.g., `.github/\nsrc/`). | diff --git a/docs/src/content/docs/reference/faq.md b/docs/src/content/docs/reference/faq.md index 17244080ae7..17ef49d4b1d 100644 --- a/docs/src/content/docs/reference/faq.md +++ b/docs/src/content/docs/reference/faq.md @@ -108,7 +108,7 @@ For cross-org private packages, use `github-app:` authentication: ```yaml wrap dependencies: github-app: - app-id: ${{ vars.APP_ID }} + client-id: ${{ vars.APP_ID }} private-key: ${{ secrets.APP_PRIVATE_KEY }} packages: - acme-org/acme-plugins diff --git a/docs/src/content/docs/reference/frontmatter.md b/docs/src/content/docs/reference/frontmatter.md index df421f31b27..80959be60cf 100644 --- a/docs/src/content/docs/reference/frontmatter.md +++ b/docs/src/content/docs/reference/frontmatter.md @@ -30,7 +30,7 @@ The `on:` section uses standard GitHub Actions syntax to define workflow trigger - Standard GitHub Actions triggers (push, pull_request, issues, schedule, etc.) - `reaction:` - Add emoji reactions to triggering items -- `status-comment:` - Post a started/completed comment with a workflow run link (automatically enabled for `slash_command` and `label_command` triggers; must be explicitly set to `true` for other trigger types) +- `status-comment:` - Post a started/completed comment with a workflow run link (automatically enabled for `slash_command` and `label_command` triggers; must be explicitly set to `true` for other trigger types). Accepts a boolean or an object with optional `issues`, `pull-requests`, and `discussions` toggle fields to selectively disable status comments for specific target types. - `stop-after:` - Automatically disable triggers after a deadline - `manual-approval:` - Require manual approval using environment protection rules - `forks:` - Configure fork filtering for pull_request triggers @@ -419,6 +419,21 @@ Debug workflow using script mode for custom actions. **Note:** The `action-mode` can also be overridden via the CLI flag `--action-mode` or the environment variable `GH_AW_ACTION_MODE`. The precedence is: CLI flag > feature flag > environment variable > auto-detection. +#### Copilot BYOK Mode (`features.byok-copilot`) + +Enables Copilot offline Bring Your Own Key (BYOK) mode with a single flag, bundling three required behaviors: injecting a dummy `COPILOT_API_KEY` to trigger the AWF BYOK runtime path, implicitly enabling `cli-proxy`, and forcing the Copilot CLI to install at `latest` (ignoring any pinned `engine.version`). + +```yaml wrap +engine: copilot +features: + byok-copilot: true +``` + +Without this flag, BYOK mode requires manual composition of all three behaviors. With `byok-copilot: true`, the compiler handles the wiring automatically. + +> [!NOTE] +> `byok-copilot` applies only to `engine: copilot` workflows. The implicit `cli-proxy` enablement does not apply to other engines. + #### Reaction-based Trust Signals (`features.integrity-reactions`) Enables maintainers to promote or demote content past the integrity filter using GitHub reactions (👍, ❤️, 👎, 😕), without adding labels or modifying issue state. Available from gh-aw v0.68.2. diff --git a/docs/src/content/docs/reference/glossary.md b/docs/src/content/docs/reference/glossary.md index 98d79b82dc4..7c2ef1632fb 100644 --- a/docs/src/content/docs/reference/glossary.md +++ b/docs/src/content/docs/reference/glossary.md @@ -365,7 +365,7 @@ A secure, encrypted variable stored in repository or organization settings holdi ### GitHub App (`github-app:`) -A GitHub App installation used for authentication and token minting in workflows. The `github-app:` field (which replaces the deprecated `app:` key) accepts `app-id` and `private-key` to mint short-lived installation access tokens with fine-grained, automatically-revoked permissions. Can be configured in `safe-outputs:` to override the default `GITHUB_TOKEN` for all safe output operations, or in `checkout:` for accessing private repositories. See [Authentication Reference](/gh-aw/reference/auth/#using-a-github-app-for-authentication). +A GitHub App installation used for authentication and token minting in workflows. The `github-app:` field (which replaces the deprecated `app:` key) accepts `client-id` (preferred) or `app-id` (deprecated alias) together with `private-key` to mint short-lived installation access tokens with fine-grained, automatically-revoked permissions. Can be configured in `safe-outputs:` to override the default `GITHUB_TOKEN` for all safe output operations, or in `checkout:` for accessing private repositories. Run `gh aw fix` to automatically migrate `app-id` to `client-id`. See [Authentication Reference](/gh-aw/reference/auth/#using-a-github-app-for-authentication). ### YAML diff --git a/docs/src/content/docs/reference/imports.md b/docs/src/content/docs/reference/imports.md index 9efb833e534..55aa8e58860 100644 --- a/docs/src/content/docs/reference/imports.md +++ b/docs/src/content/docs/reference/imports.md @@ -370,7 +370,7 @@ steps: id: get-token uses: actions/create-github-app-token@v1 with: - app-id: ${{ vars.APP_ID }} + client-id: ${{ vars.APP_ID }} private-key: ${{ secrets.APP_PRIVATE_KEY }} --- ``` diff --git a/docs/src/content/docs/reference/safe-outputs-pull-requests.md b/docs/src/content/docs/reference/safe-outputs-pull-requests.md index e5c00adb9c1..6c214c027e1 100644 --- a/docs/src/content/docs/reference/safe-outputs-pull-requests.md +++ b/docs/src/content/docs/reference/safe-outputs-pull-requests.md @@ -364,7 +364,7 @@ Set `allow-workflows: true` on `create-pull-request` or `push-to-pull-request-br ```yaml wrap safe-outputs: github-app: - app-id: ${{ vars.APP_ID }} + client-id: ${{ vars.APP_ID }} private-key: ${{ secrets.APP_PRIVATE_KEY }} create-pull-request: allow-workflows: true diff --git a/docs/src/content/docs/reference/safe-outputs.md b/docs/src/content/docs/reference/safe-outputs.md index e1c0d75518a..644d5ebeee6 100644 --- a/docs/src/content/docs/reference/safe-outputs.md +++ b/docs/src/content/docs/reference/safe-outputs.md @@ -1229,7 +1229,7 @@ The top-level `environment:` field is automatically propagated to all safe-outpu safe-outputs: environment: dev # overrides top-level environment for safe-output jobs only github-app: - app-id: ${{ secrets.WORKFLOW_APP_ID }} + client-id: ${{ secrets.WORKFLOW_APP_ID }} private-key: ${{ secrets.WORKFLOW_APP_PRIVATE_KEY }} ``` diff --git a/docs/src/content/docs/reference/tokens.md b/docs/src/content/docs/reference/tokens.md index b8b3db330ec..5b70b15722a 100644 --- a/docs/src/content/docs/reference/tokens.md +++ b/docs/src/content/docs/reference/tokens.md @@ -273,7 +273,7 @@ Reference them in your workflow frontmatter: tools: github: github-app: - app-id: ${{ vars.APP_ID }} + client-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 diff --git a/docs/src/content/docs/reference/triggers.md b/docs/src/content/docs/reference/triggers.md index e4168da2087..b83d4ee3239 100644 --- a/docs/src/content/docs/reference/triggers.md +++ b/docs/src/content/docs/reference/triggers.md @@ -377,6 +377,33 @@ When `status-comment: true`, the activation job posts a comment when the workflo To suppress status comments, omit `status-comment:` or set it to `false`. +#### Selective target control (object form) + +Use an object to enable status comments while selectively disabling specific targets. The object form implies status comments are enabled; each field defaults to `true`: + +```yaml wrap +on: + issues: + types: [opened] + pull_request: + types: [opened] + discussion: + types: [created] + status-comment: + issues: true # post on issue events (default) + pull-requests: false # skip pull request events + discussions: false # skip discussion events +``` + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `issues` | boolean | `true` | Enable status comments for `issues` and `issue_comment` events | +| `pull-requests` | boolean | `true` | Enable status comments for `pull_request` and `pull_request_review_comment` events | +| `discussions` | boolean | `true` | Enable status comments for `discussion` and `discussion_comment` events | + +> [!NOTE] +> Setting all three fields to `false` is a compilation error. If no targets are enabled, use `status-comment: false` instead. + ### Activation Token (`on.github-token:`, `on.github-app:`) Configure a custom GitHub token or GitHub App for the activation job **and all skip-if search checks**. The activation job posts the initial reaction (and status comment if `status-comment: true`) on the triggering item, and skip-if checks use the same token to query the GitHub Search API. By default all of these operations use the workflow's `GITHUB_TOKEN`. @@ -399,7 +426,7 @@ on: types: [opened] reaction: "rocket" github-app: - app-id: ${{ vars.APP_ID }} + client-id: ${{ vars.APP_ID }} private-key: ${{ secrets.APP_KEY }} ``` @@ -412,7 +439,7 @@ Both `github-token` and `github-app` can be defined in a **shared agentic workfl on: workflow_call: github-app: - app-id: ${{ secrets.ORG_APP_ID }} + client-id: ${{ secrets.ORG_APP_ID }} private-key: ${{ secrets.ORG_APP_PRIVATE_KEY }} owner: myorg ``` @@ -485,7 +512,7 @@ on: query: "org:myorg label:ops:in-progress is:issue is:open" scope: none github-app: - app-id: ${{ secrets.WORKFLOW_APP_ID }} + client-id: ${{ secrets.WORKFLOW_APP_ID }} private-key: ${{ secrets.WORKFLOW_APP_PRIVATE_KEY }} owner: myorg ``` @@ -527,7 +554,7 @@ on: query: "org:myorg label:agent-fix -label:ops:agentic is:issue is:open" scope: none github-app: - app-id: ${{ secrets.WORKFLOW_APP_ID }} + client-id: ${{ secrets.WORKFLOW_APP_ID }} private-key: ${{ secrets.WORKFLOW_APP_PRIVATE_KEY }} owner: myorg ```