github · pelikhan · Apr 16, 2026 · Apr 16, 2026
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
 ```