Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/minor-stable-github-safe-outputs.md

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

3 changes: 1 addition & 2 deletions .github/aw/safe-outputs-automation.md
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,7 @@ description: Safe-output reference for workflow dispatch, code scanning, checks,
```

Triggers other agentic workflows using workflow_dispatch. Agent output includes `workflow_name` (without .md extension) and optional `inputs` (key-value pairs). Cross-repo dispatch is supported via `target-repo` plus an `allowed-repos` allowlist; cross-repo targets require a token with `actions: write` on the target repository. For queue workers, load [work-queue.md](work-queue.md) and use `work_queue_dispatch_next` to request a bounded pool prefix. Trusted processing selects Work and the installed worker profile; do not select `work_id` through `dispatch_workflow` or declare reserved assignment/caller inputs.
- `dispatch-repository:` - Dispatch `repository_dispatch` events to external repositories (experimental)
- `dispatch-repository:` - Dispatch `repository_dispatch` events to external repositories
Comment thread
pelikhan marked this conversation as resolved.
Resolved
Comment thread
pelikhan marked this conversation as resolved.
Resolved

```yaml
safe-outputs:
Expand All @@ -100,7 +100,6 @@ description: Safe-output reference for workflow dispatch, code scanning, checks,

Accepts both `dispatch-repository` (dash, canonical) and `dispatch_repository` (underscore, deprecated alias). Each key in the config defines a named MCP tool. Requires a token with `repo` scope since `GITHUB_TOKEN` cannot trigger `repository_dispatch` in external repositories. Use `github-token` or set a PAT as `GH_AW_SAFE_OUTPUTS_TOKEN`.

**⚠️ Experimental**: Compilation emits a warning when this feature is used.
- `call-workflow:` - Call reusable workflows via workflow_call fan-out (orchestrator pattern)

```yaml
Expand Down
2 changes: 1 addition & 1 deletion .github/aw/test-coverage.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ safe-outputs:
upload-code-coverage:
```

`upload-code-coverage` is experimental and publishes a Cobertura XML coverage report to GitHub's code coverage API via [`actions/upload-code-coverage`](https://github.com/actions/upload-code-coverage). Compilation emits a warning when this feature is used. The compiler automatically grants the dedicated `code-quality: write` (and `pull-requests: read` for push-triggered workflows) permission needed by the upload job — no need to add it to the `permissions:` block above.
`upload-code-coverage` publishes a Cobertura XML coverage report to GitHub's code coverage API via [`actions/upload-code-coverage`](https://github.com/actions/upload-code-coverage). The compiler automatically grants the dedicated `code-quality: write` (and `pull-requests: read` for push-triggered workflows) permission needed by the upload job — no need to add it to the `permissions:` block above.

## Fallback: Run Tests

Expand Down
2 changes: 1 addition & 1 deletion actions/setup/js/safe_outputs_tools.json
Original file line number Diff line number Diff line change
Expand Up @@ -1601,7 +1601,7 @@
},
{
"name": "upload_code_coverage",
"description": "Experimental. Upload a code coverage report (e.g. a Cobertura XML file) to GitHub's code coverage API via actions/upload-code-coverage. Before calling this tool, write or copy the coverage report file into the upload-code-coverage staging directory at /tmp/gh-aw/safeoutputs/upload-code-coverage/ (or provide an absolute path / workspace-relative path, which will be auto-copied into staging). Shell variable syntax (for example, \"$VAR/...\") must NOT appear in file values because variables are not expanded in JSON strings. Only one coverage report can be uploaded per run.",
"description": "Upload a code coverage report (e.g. a Cobertura XML file) to GitHub's code coverage API via actions/upload-code-coverage. Before calling this tool, write or copy the coverage report file into the upload-code-coverage staging directory at /tmp/gh-aw/safeoutputs/upload-code-coverage/ (or provide an absolute path / workspace-relative path, which will be auto-copied into staging). Shell variable syntax (for example, \"$VAR/...\") must NOT appear in file values because variables are not expanded in JSON strings. Only one coverage report can be uploaded per run.",
"inputSchema": {
"type": "object",
"required": ["file", "language", "label"],
Expand Down
14 changes: 6 additions & 8 deletions docs/src/content/docs/reference/frontmatter-full.md
Original file line number Diff line number Diff line change
Expand Up @@ -20721,17 +20721,15 @@ safe-outputs:
# Format 2: Enable artifact uploads with default configuration
upload-artifact: null

# ⚠️ Experimental. Enable AI agents to upload a code coverage report (e.g. a
# Cobertura XML file) to GitHub's code coverage API via
# actions/upload-code-coverage. Using this field emits a compile-time warning. The
# agent stages the report file and calls the tool with file/language/label; a
# separate job performs the actual upload with dedicated code-quality: write
# permissions.
# Enable AI agents to upload a code coverage report (e.g. a Cobertura XML file) to
# GitHub's code coverage API via actions/upload-code-coverage. The agent stages the
# report file and calls the tool with file/language/label; a separate job performs
# the actual upload with dedicated code-quality: write permissions.
# (optional)
# Accepted formats:

# Format 1: ⚠️ Experimental. Configuration for uploading a code coverage report
# via actions/upload-code-coverage
# Format 1: Configuration for uploading a code coverage report via
# actions/upload-code-coverage
upload-code-coverage:
# Trusted queue coverage target; independently resolved to the immutable worker
# revision before upload.
Expand Down
4 changes: 2 additions & 2 deletions docs/src/content/docs/reference/glossary.md
Original file line number Diff line number Diff line change
Expand Up @@ -440,7 +440,7 @@ An `artifacts:` array on a custom safe-outputs job that declares agent-job files

### Dispatch Repository (`dispatch-repository`)

An experimental safe output type that triggers `repository_dispatch` events in external repositories for cross-repository orchestration. Each key under `safe-outputs.dispatch-repository:` defines a named tool exposed to the agent. A tool requires a `workflow` identifier (forwarded in `client_payload` for routing), an `event_type`, and either a static `repository` slug or an `allowed_repositories` list. GitHub Actions expressions (`${{ ... }}`) are supported in repository fields and are passed through without format validation. At compile time the compiler emits a warning: `Using experimental feature: dispatch-repository`. See [Safe Outputs Reference](/gh-aw/reference/safe-outputs/#repository-dispatch-dispatch-repository).
A safe output type that triggers `repository_dispatch` events in external repositories for cross-repository orchestration. Each key under `safe-outputs.dispatch-repository:` defines a named tool exposed to the agent. A tool requires a `workflow` identifier (forwarded in `client_payload` for routing), an `event_type`, and either a static `repository` slug or an `allowed_repositories` list. GitHub Actions expressions (`${{ ... }}`) are supported in repository fields and are passed through without format validation. See [Safe Outputs Reference](/gh-aw/reference/safe-outputs/#repository-dispatch-dispatch-repository).

### Runner Group (`runs-on: {group: ...}`)

Expand Down Expand Up @@ -514,7 +514,7 @@ An Azure DevOps work-item field that assigns items to a sprint or release cycle

### Approve Workflow Run (`approve-workflow-run:`)

An experimental safe output capability that approves a GitHub Actions workflow run in the "action required" state, such as runs for fork pull requests or pull requests created by Copilot. The agent supplies a positive integer `run_id`; the handler verifies the run is a pull request run tied to an authorized pull request and is still awaiting approval (status `action_required` or `waiting`, or conclusion `action_required`) before calling GitHub's approval API. Requires `actions: write` and an explicit external `github-token` or `github-app`, since the default `github.token` cannot approve workflow runs; `pull-requests: write` is required when `comment` is enabled (the default), otherwise `pull-requests: read` suffices. `allowed-workflows` is required and restricts approval to matching workflow filenames; `allowed-pull-requests` extends authorization beyond the triggering pull request. Only pull requests whose head branch lives in the current repository (including agent-initiated `copilot/*` pull requests) are approvable by default; pull requests from other repositories are refused unless their repository matches an `allowed-repos` entry. The safe output always refuses to run from `pull_request_target`. After a successful approval, a comment announcing the run has started (with a generated attribution footer) is posted on each associated pull request unless `comment: false` is set. Compiling a workflow with `approve-workflow-run` emits an experimental feature warning. See [Safe Outputs (Pull Requests)](/gh-aw/reference/safe-outputs-pull-requests/#approve-workflow-run-approve-workflow-run).
A safe output capability that approves a GitHub Actions workflow run in the "action required" state, such as runs for fork pull requests or pull requests created by Copilot. The agent supplies a positive integer `run_id`; the handler verifies the run is a pull request run tied to an authorized pull request and is still awaiting approval (status `action_required` or `waiting`, or conclusion `action_required`) before calling GitHub's approval API. Requires `actions: write` and an explicit external `github-token` or `github-app`, since the default `github.token` cannot approve workflow runs; `pull-requests: write` is required when `comment` is enabled (the default), otherwise `pull-requests: read` suffices. `allowed-workflows` is required and restricts approval to matching workflow filenames; `allowed-pull-requests` extends authorization beyond the triggering pull request. Only pull requests whose head branch lives in the current repository (including agent-initiated `copilot/*` pull requests) are approvable by default; pull requests from other repositories are refused unless their repository matches an `allowed-repos` entry. The safe output always refuses to run from `pull_request_target`. After a successful approval, a comment announcing the run has started (with a generated attribution footer) is posted on each associated pull request unless `comment: false` is set. See [Safe Outputs (Pull Requests)](/gh-aw/reference/safe-outputs-pull-requests/#approve-workflow-run-approve-workflow-run).

### Merge Pull Request (`merge-pull-request:`)

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ sidebar:
order: 801
---

This page covers pull-request-focused safe outputs: [`create-pull-request`](#pull-request-creation-create-pull-request), [`update-pull-request`](#pull-request-updates-update-pull-request), [`close-pull-request`](#close-pull-request-close-pull-request), [`approve-workflow-run`](#approve-workflow-run-approve-workflow-run) (experimental), [`merge-pull-request`](#merge-pull-request-merge-pull-request) (experimental), [`create-pull-request-review-comment`](#pr-review-comments-create-pull-request-review-comment), [`submit-pull-request-review`](#submit-pr-review-submit-pull-request-review), [`reply-to-pull-request-review-comment`](#reply-to-pr-review-comment-reply-to-pull-request-review-comment), [`resolve-pull-request-review-thread`](#resolve-pr-review-thread-resolve-pull-request-review-thread), [`push-to-pull-request-branch`](#push-to-pr-branch-push-to-pull-request-branch), and [`add-reviewer`](#add-reviewer-add-reviewer).
This page covers pull-request-focused safe outputs: [`create-pull-request`](#pull-request-creation-create-pull-request), [`update-pull-request`](#pull-request-updates-update-pull-request), [`close-pull-request`](#close-pull-request-close-pull-request), [`approve-workflow-run`](#approve-workflow-run-approve-workflow-run), [`merge-pull-request`](#merge-pull-request-merge-pull-request) (experimental), [`create-pull-request-review-comment`](#pr-review-comments-create-pull-request-review-comment), [`submit-pull-request-review`](#submit-pr-review-submit-pull-request-review), [`reply-to-pull-request-review-comment`](#reply-to-pr-review-comment-reply-to-pull-request-review-comment), [`resolve-pull-request-review-thread`](#resolve-pr-review-thread-resolve-pull-request-review-thread), [`push-to-pull-request-branch`](#push-to-pr-branch-push-to-pull-request-branch), and [`add-reviewer`](#add-reviewer-add-reviewer).

Code-writing types (`create-pull-request` and `push-to-pull-request-branch`) enforce [Protected Files](#protected-files) by default. For all other safe-output types, see [Safe Outputs](/gh-aw/reference/safe-outputs/).

Expand Down Expand Up @@ -227,10 +227,6 @@ safe-outputs:

## Approve Workflow Run (`approve-workflow-run:`)

:::caution[Experimental]
`approve-workflow-run` is an experimental safe output. `gh aw compile` emits an experimental feature warning when a workflow uses it.
:::

Approves a GitHub Actions workflow run in the "action required" state, such as runs for fork pull requests or pull requests created by Copilot. The agent supplies a positive integer `run_id`; the handler verifies that the run is a pull request run, is associated with an authorized pull request, and is still awaiting approval (status `action_required` or `waiting`, or conclusion `action_required`) before calling GitHub's workflow-run approval API.

```yaml wrap
Expand Down
7 changes: 2 additions & 5 deletions docs/src/content/docs/reference/safe-outputs.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,7 @@ The tables below summarize the built-in safe output handlers. `noop`, `report-mi
| [Create PR](/gh-aw/reference/safe-outputs-pull-requests/#pull-request-creation-create-pull-request) | `create-pull-request` | Create pull requests with code changes (default max: 1, configurable) |
| [Update PR](/gh-aw/reference/safe-outputs-pull-requests/#pull-request-updates-update-pull-request) | `update-pull-request` | Update PR title or body (max: 1) |
| [Close PR](/gh-aw/reference/safe-outputs-pull-requests/#close-pull-request-close-pull-request) | `close-pull-request` | Close pull requests without merging (max: 10) |
| [Approve Workflow Run](/gh-aw/reference/safe-outputs-pull-requests/#approve-workflow-run-approve-workflow-run) | `approve-workflow-run` | Approve a pending workflow run in the "action required" state (max: 1, experimental) |
| [Approve Workflow Run](/gh-aw/reference/safe-outputs-pull-requests/#approve-workflow-run-approve-workflow-run) | `approve-workflow-run` | Approve a pending workflow run in the "action required" state (max: 1) |
| [Merge PR](/gh-aw/reference/safe-outputs-pull-requests/#merge-pull-request-merge-pull-request) | `merge-pull-request` | Merge pull requests after policy gates pass (max: 1, experimental) |
| [PR Review Comments](/gh-aw/reference/safe-outputs-pull-requests/#pr-review-comments-create-pull-request-review-comment) | `create-pull-request-review-comment` | Create review comments on code lines (max: 10) |
| [Reply to PR Review Comment](/gh-aw/reference/safe-outputs-pull-requests/#reply-to-pr-review-comment-reply-to-pull-request-review-comment) | `reply-to-pull-request-review-comment` | Reply to existing review comments (max: 10) |
Expand Down Expand Up @@ -140,7 +140,7 @@ The tables below summarize the built-in safe output handlers. `noop`, `report-mi
|--------|-----|-------------|
| [Dispatch Workflow](#workflow-dispatch-dispatch-workflow) | `dispatch-workflow` | Trigger other workflows with inputs (max: 3, same-repo only) |
| [Call Workflow](#workflow-call-call-workflow) | `call-workflow` | Call reusable workflows via compile-time fan-out (max: 1, same-repo only) |
| [Dispatch Repository Event](#repository-dispatch-dispatch-repository) | `dispatch-repository` | Trigger `repository_dispatch` events in external repositories, experimental (cross-repo) |
| [Dispatch Repository Event](#repository-dispatch-dispatch-repository) | `dispatch-repository` | Trigger `repository_dispatch` events in external repositories (cross-repo) |
| [Code Scanning Alerts](#code-scanning-alerts-create-code-scanning-alert) | `create-code-scanning-alert` | Generate SARIF security advisories (max: unlimited, same-repo only) |
| [Autofix Code Scanning Alerts](#autofix-code-scanning-alerts-autofix-code-scanning-alert) | `autofix-code-scanning-alert` | Create automated fixes for code scanning alerts (max: 10, same-repo only) |
| [Create Check Run](#check-run-creation-create-check-run) | `create-check-run` | Create GitHub Check Runs to surface analysis results in the PR checks UI (default max: 1, same-repo only) |
Expand Down Expand Up @@ -1579,9 +1579,6 @@ Use `call-workflow` for deterministic fan-out where actor attribution and zero A

### Repository Dispatch (`dispatch-repository`)

> [!CAUTION]
> This is an experimental feature. Compiling a workflow with `dispatch-repository` emits a warning: `Using experimental feature: dispatch-repository`. The API may change in future releases.

Triggers [`repository_dispatch`](https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#repository_dispatch) events in external repositories. Unlike `dispatch-workflow` (same-repo only), `dispatch-repository` is designed for cross-repository orchestration.

Each key under `dispatch-repository:` defines a named tool exposed to the agent:
Expand Down
2 changes: 0 additions & 2 deletions docs/src/content/docs/specs/safe-outputs-specification.md
Original file line number Diff line number Diff line change
Expand Up @@ -3684,8 +3684,6 @@ For all Linear types, GraphQL source, endpoint, protocol, and host are implement
**Cross-Repository Support**: No
**Mandatory**: No

**Experimental**: Yes. Compiling a workflow with `approve-workflow-run` emits: `Using experimental feature: approve-workflow-run`.

**MCP Tool Schema**:

```json
Expand Down
4 changes: 2 additions & 2 deletions pkg/parser/schemas/main_workflow_schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -12520,7 +12520,7 @@
"oneOf": [
{
"type": "object",
"description": "⚠️ Experimental. Configuration for uploading a code coverage report via actions/upload-code-coverage",
"description": "Configuration for uploading a code coverage report via actions/upload-code-coverage",
"properties": {
"target-ref": {
"type": "string",
Expand Down Expand Up @@ -12590,7 +12590,7 @@
"description": "Enable code coverage report uploads with default configuration"
}
],
"description": "⚠️ Experimental. Enable AI agents to upload a code coverage report (e.g. a Cobertura XML file) to GitHub's code coverage API via actions/upload-code-coverage. Using this field emits a compile-time warning. The agent stages the report file and calls the tool with file/language/label; a separate job performs the actual upload with dedicated code-quality: write permissions."
"description": "Enable AI agents to upload a code coverage report (e.g. a Cobertura XML file) to GitHub's code coverage API via actions/upload-code-coverage. The agent stages the report file and calls the tool with file/language/label; a separate job performs the actual upload with dedicated code-quality: write permissions."
},
"update-release": {
"oneOf": [
Expand Down
2 changes: 1 addition & 1 deletion pkg/workflow/app_token_permissions_validation_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -149,7 +149,7 @@ func TestAppTokenPermissionsGeneratedWildcardRepositories(t *testing.T) {
config: "safe-outputs:\n github-app:\n app-id: ${{ vars.APP_ID }}\n private-key: ${{ secrets.APP_KEY }}\n repositories: [\"*\"]\n" +
" dispatch-repository:\n trigger-ci:\n workflow: ci.yml\n event_type: ci_trigger\n repository: github/gh-aw\n",
stepID: "safe-outputs-app-token",
warnings: 1,
warnings: 0,
},
} {
t.Run(tc.name, func(t *testing.T) {
Expand Down
Loading
Loading