From f710893ba198ff058bdba6d2d703462460519a36 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Thu, 28 Aug 2025 22:58:31 +0100 Subject: [PATCH 1/8] safe outputs revamp --- docs/safe-outputs.md | 124 +++++++++++++++++++------------------------ 1 file changed, 54 insertions(+), 70 deletions(-) diff --git a/docs/safe-outputs.md b/docs/safe-outputs.md index f31f1bacdd1..e41bf5af307 100644 --- a/docs/safe-outputs.md +++ b/docs/safe-outputs.md @@ -12,45 +12,21 @@ The `output:` element of your workflow's frontmatter declares that your agentic 3. The compiler automatically generates additional jobs that read this output and perform the requested actions 4. Only these generated jobs receive the necessary write permissions +For example, if you want your agent to create a GitHub issue based on its analysis, you can add the following to your workflow frontmatter: + ```yaml output: - allowed-domains: # Optional: domains allowed in agent output URIs - - github.com # Default GitHub domains are always included - - api.github.com # Additional trusted domains can be specified - - trusted-domain.com # URIs from unlisted domains are replaced with "(redacted)" issue: - title-prefix: "[ai] " # Optional: prefix for issue titles - labels: [automation, ai-agent] # Optional: labels to attach to issues - issue_comment: {} # Create comments on issues/PRs from agent output - pull-request: - title-prefix: "[ai] " # Optional: prefix for PR titles - labels: [automation, ai-agent] # Optional: labels to attach to PRs - draft: true # Optional: create as draft PR (defaults to true) - labels: - allowed: [triage, bug, enhancement] # Mandatory: allowed labels for addition - max-count: 3 # Optional: maximum number of labels to add (default: 3) ``` -## Security and Sanitization +This declares that the workflow can create one new issue in the repository - and that's all. +This is done in a separate, non-agentic job that creates the issue after your main agentic job completes. This second job will implicitly have `issues: write` permissions, but your main job does not need `issues: write` permission, enhancing security. -All agent output is automatically sanitized for security before being processed: +### Available Output Types -- **XML Character Escaping**: Special characters (`<`, `>`, `&`, `"`, `'`) are escaped to prevent injection attacks -- **URI Protocol Filtering**: Only HTTPS URIs are allowed; other protocols (HTTP, FTP, file://, javascript:, etc.) are replaced with "(redacted)" -- **Domain Allowlisting**: HTTPS URIs are checked against the `allowed-domains` list. Unlisted domains are replaced with "(redacted)" -- **Default Allowed Domains**: When `allowed-domains` is not specified, safe GitHub domains are used by default: - - `github.com` - - `github.io` - - `githubusercontent.com` - - `githubassets.com` - - `github.dev` - - `codespaces.new` -- **Length and Line Limits**: Content is truncated if it exceeds safety limits (0.5MB or 65,000 lines) -- **Control Character Removal**: Non-printable characters and ANSI escape sequences are stripped +## Issue Creation (`issue:`) -## Issue Creation (`output.issue`) - -Adding `output.issue` to your workflow declares that the workflow should conclude with the creation of a GitHub issue based on the agent's output. +Adding `issue:` to the `output:` section of your workflow declares that the workflow should conclude with the creation of a GitHub issue based on the agent's output. **How Your Agent Provides Output:** Your agentic workflow writes its content to `${{ env.GITHUB_AW_OUTPUT }}`. The output should be structured as: @@ -58,21 +34,17 @@ Your agentic workflow writes its content to `${{ env.GITHUB_AW_OUTPUT }}`. The o - **Remaining content**: Becomes the issue body **What This Configuration Does:** -When you add `output.issue` to your frontmatter, the compiler automatically generates a separate `create_issue` job that: +The compiler automatically generates a separate `create_issue` job that: - Runs after your main agentic job completes - Reads the content from `${{ env.GITHUB_AW_OUTPUT }}` - Parses it to extract title and body - Creates a GitHub issue with optional title prefix and labels - **Security**: Only this generated job gets `issues: write` permission—your agentic code runs with minimal permissions -**Example workflow using issue creation:** +**Example using issue creation:** ```yaml --- -on: push -permissions: - contents: read # Main job only needs minimal permissions - actions: read -engine: claude +... output: issue: title-prefix: "[analysis] " @@ -88,15 +60,15 @@ The first line of your output will become the issue title. The rest will become the issue body. ``` -## Issue Comment Creation (`output.issue_comment`) +## Issue Comment Creation (`issue_comment:`) -Adding `output.issue_comment` to your workflow declares that the workflow should conclude with posting a comment on the triggering issue or pull request based on the agent's output. +Adding `issue_comment:` to the output section of your workflow declares that the workflow should conclude with posting a comment on the triggering issue or pull request based on the agent's output. **How Your Agent Provides Output:** Your agentic workflow writes its content to `${{ env.GITHUB_AW_OUTPUT }}`. The entire content becomes the comment body—no special formatting is required. **What This Configuration Does:** -When you add `output.issue_comment` to your frontmatter, the compiler automatically generates a separate `create_issue_comment` job that: +The compiler automatically generates a separate `create_issue_comment` job that: - Only runs when triggered by an issue or pull request event - Reads the content from `${{ env.GITHUB_AW_OUTPUT }}` - Posts the entire output as a comment on the triggering issue or PR @@ -106,17 +78,9 @@ When you add `output.issue_comment` to your frontmatter, the compiler automatica **Example workflow using comment creation:** ```yaml --- -on: - issues: - types: [opened, labeled] - pull_request: - types: [opened, synchronize] -permissions: - contents: read # Main job only needs minimal permissions - actions: read -engine: claude +... output: - issue_comment: {} + issue_comment: --- # Issue/PR Analysis Agent @@ -129,9 +93,9 @@ Your entire output will be posted as a comment on the triggering issue or PR. This automatically creates GitHub issues or comments from the agent's analysis without requiring write permissions on the main job. -## Pull Request Creation (`output.pull-request`) +## Pull Request Creation (`pull-request:`) -Adding `output.pull-request` to your workflow declares that the workflow should conclude with the creation of a pull request containing code changes generated by the agent. +Adding `pull-request:` to the `output:` section of your workflow declares that the workflow should conclude with the creation of a pull request containing code changes generated by the agent. **How Your Agent Provides Output:** Your agentic workflow provides output in two ways: @@ -141,7 +105,7 @@ Your agentic workflow provides output in two ways: - **Remaining content**: Becomes the PR description **What This Configuration Does:** -When you add `output.pull-request` to your frontmatter, the compiler automatically: +The compiler automatically: 1. **Adds a git patch generation step** to your main job that: - Runs `git add -A` to stage any file changes made by your agent - Commits staged files with message "[agent] staged files" @@ -164,12 +128,9 @@ output: ``` **Example workflow using pull request creation:** -```markdown +````markdown --- -on: push -permissions: - actions: read # Main job only needs minimal permissions -engine: claude +... output: pull-request: title-prefix: "[bot] " @@ -197,6 +158,7 @@ Fix coding style issues - Fixed indentation in helper functions - Added missing documentation ``` +```` **Automatic Patch Generation:** The workflow automatically handles patch creation—your agent simply makes file changes, and the system: @@ -205,9 +167,9 @@ The workflow automatically handles patch creation—your agent simply makes file 3. Generates git patches using `git format-patch` 4. Validates patch existence and content before proceeding with PR creation -## Label Addition (`output.labels`) +## Label Addition (`labels:`) -Adding `output.labels` to your workflow declares that the workflow should conclude with adding labels to the current issue or pull request based on the agent's analysis. +Adding `labels:` to the `output:` section of your workflow declares that the workflow should conclude with adding labels to the current issue or pull request based on the agent's analysis. **How Your Agent Provides Output:** Your agentic workflow writes labels to add to `${{ env.GITHUB_AW_OUTPUT }}`, one label per line: @@ -218,7 +180,7 @@ needs-review ``` **What This Configuration Does:** -When you add `output.labels` to your frontmatter, the compiler automatically generates a separate `add_labels` job that: +The compiler automatically generates a separate `add_labels` job that: - Only runs when triggered by an issue or pull request event - Reads the labels from `${{ env.GITHUB_AW_OUTPUT }}` (one per line) - Validates each label against the mandatory `allowed` list @@ -254,16 +216,11 @@ needs-review **Example workflow using label addition:** ```yaml --- -on: - issues: - types: [opened] -permissions: - contents: read - actions: read # Main job only needs minimal permissions -engine: claude +... + output: labels: - allowed: [triage, bug, enhancement, documentation, needs-review] + allowed: [triage, bug, enhancement] --- # Issue Labeling Agent @@ -275,6 +232,33 @@ Write the labels you want to add (one per line) to ${{ env.GITHUB_AW_OUTPUT }}. Only use labels from the allowed list: triage, bug, enhancement, documentation, needs-review. ``` +## Security and Sanitization + +All agent output is automatically sanitized for security before being processed: + +- **XML Character Escaping**: Special characters (`<`, `>`, `&`, `"`, `'`) are escaped to prevent injection attacks +- **URI Protocol Filtering**: Only HTTPS URIs are allowed; other protocols (HTTP, FTP, file://, javascript:, etc.) are replaced with "(redacted)" +- **Domain Allowlisting**: HTTPS URIs are checked against the `allowed-domains` list. Unlisted domains are replaced with "(redacted)" +- **Default Allowed Domains**: When `allowed-domains` is not specified, safe GitHub domains are used by default: + - `github.com` + - `github.io` + - `githubusercontent.com` + - `githubassets.com` + - `github.dev` + - `codespaces.new` +- **Length and Line Limits**: Content is truncated if it exceeds safety limits (0.5MB or 65,000 lines) +- **Control Character Removal**: Non-printable characters and ANSI escape sequences are stripped + +**Configuration:** + +```yaml +output: + allowed-domains: # Optional: domains allowed in agent output URIs + - github.com # Default GitHub domains are always included + - api.github.com # Additional trusted domains can be specified + - trusted-domain.com # URIs from unlisted domains are replaced with "(redacted)" +``` + ## Related Documentation - [Frontmatter Options](frontmatter.md) - All configuration options for workflows From ecfcd3aced0d4a5b3269a99d10f1f9a4a1b0efc6 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Thu, 28 Aug 2025 23:07:23 +0100 Subject: [PATCH 2/8] fix lint --- docs/safe-outputs.md | 97 +++++++++++++++++++------------------------- 1 file changed, 41 insertions(+), 56 deletions(-) diff --git a/docs/safe-outputs.md b/docs/safe-outputs.md index e41bf5af307..3e74990378b 100644 --- a/docs/safe-outputs.md +++ b/docs/safe-outputs.md @@ -28,12 +28,20 @@ This is done in a separate, non-agentic job that creates the issue after your ma Adding `issue:` to the `output:` section of your workflow declares that the workflow should conclude with the creation of a GitHub issue based on the agent's output. +**Configuration Options:** +```yaml +output: + issue: + title-prefix: "[ai] " # Optional: prefix for issue titles + labels: [automation, ai-agent] # Optional: labels to attach to issues +``` + **How Your Agent Provides Output:** Your agentic workflow writes its content to `${{ env.GITHUB_AW_OUTPUT }}`. The output should be structured as: - **First non-empty line**: Becomes the issue title (markdown heading syntax like `# Title` is automatically stripped) - **Remaining content**: Becomes the issue body -**What This Configuration Does:** +**What This Output Option Does:** The compiler automatically generates a separate `create_issue` job that: - Runs after your main agentic job completes - Reads the content from `${{ env.GITHUB_AW_OUTPUT }}` @@ -41,16 +49,8 @@ The compiler automatically generates a separate `create_issue` job that: - Creates a GitHub issue with optional title prefix and labels - **Security**: Only this generated job gets `issues: write` permission—your agentic code runs with minimal permissions -**Example using issue creation:** +**Example natural language to generate the output:** ```yaml ---- -... -output: - issue: - title-prefix: "[analysis] " - labels: [automation, code-review] ---- - # Code Analysis Agent Analyze the latest commit and provide insights. @@ -64,10 +64,16 @@ The rest will become the issue body. Adding `issue_comment:` to the output section of your workflow declares that the workflow should conclude with posting a comment on the triggering issue or pull request based on the agent's output. +**Configuration Options:** +```yaml +output: + issue_comment: {} # Create comments on issues/PRs from agent output +``` + **How Your Agent Provides Output:** Your agentic workflow writes its content to `${{ env.GITHUB_AW_OUTPUT }}`. The entire content becomes the comment body—no special formatting is required. -**What This Configuration Does:** +**What This Output Option Does:** The compiler automatically generates a separate `create_issue_comment` job that: - Only runs when triggered by an issue or pull request event - Reads the content from `${{ env.GITHUB_AW_OUTPUT }}` @@ -75,14 +81,8 @@ The compiler automatically generates a separate `create_issue_comment` job that: - Automatically skips execution if not running in an issue/PR context - **Security**: Only this generated job gets `issues: write` and `pull-requests: write` permissions -**Example workflow using comment creation:** -```yaml ---- -... -output: - issue_comment: ---- - +**Example natural language to generate the output:** +```markdown # Issue/PR Analysis Agent Analyze the issue or pull request and provide feedback. @@ -97,6 +97,15 @@ This automatically creates GitHub issues or comments from the agent's analysis w Adding `pull-request:` to the `output:` section of your workflow declares that the workflow should conclude with the creation of a pull request containing code changes generated by the agent. +**Configuration Options:** +```yaml +output: + pull-request: + title-prefix: "[ai] " # Optional: prefix for PR titles + labels: [automation, ai-agent] # Optional: labels to attach to PRs + draft: true # Optional: create as draft PR (defaults to true) +``` + **How Your Agent Provides Output:** Your agentic workflow provides output in two ways: 1. **File changes**: Make any file changes in the working directory—these are automatically collected using `git add -A` and committed @@ -104,7 +113,7 @@ Your agentic workflow provides output in two ways: - **First non-empty line**: Becomes the PR title - **Remaining content**: Becomes the PR description -**What This Configuration Does:** +**What This Output Option Does:** The compiler automatically: 1. **Adds a git patch generation step** to your main job that: - Runs `git add -A` to stage any file changes made by your agent @@ -118,25 +127,8 @@ The compiler automatically: - Creates a pull request with optional title prefix, labels, and draft status - **Security**: Only this generated job gets `contents: write`, `issues: write`, and `pull-requests: write` permissions -**Configuration:** -```yaml -output: - pull-request: - title-prefix: "[ai] " # Optional: prefix for PR titles - labels: [automation, ai-agent] # Optional: labels to attach to PRs - draft: true # Optional: create as draft PR (defaults to true) -``` - -**Example workflow using pull request creation:** +**Example natural language to generate the output:** ````markdown ---- -... -output: - pull-request: - title-prefix: "[bot] " - labels: [automation, ai-generated] ---- - # Code Improvement Agent Analyze the latest commit and suggest improvements. @@ -171,6 +163,14 @@ The workflow automatically handles patch creation—your agent simply makes file Adding `labels:` to the `output:` section of your workflow declares that the workflow should conclude with adding labels to the current issue or pull request based on the agent's analysis. +**Configuration Options:** +```yaml +output: + labels: + allowed: [triage, bug, enhancement] # Mandatory: allowed labels for addition + max-count: 3 # Optional: maximum number of labels to add (default: 3) +``` + **How Your Agent Provides Output:** Your agentic workflow writes labels to add to `${{ env.GITHUB_AW_OUTPUT }}`, one label per line: ``` @@ -179,7 +179,7 @@ bug needs-review ``` -**What This Configuration Does:** +**What This Output Option Does:** The compiler automatically generates a separate `add_labels` job that: - Only runs when triggered by an issue or pull request event - Reads the labels from `${{ env.GITHUB_AW_OUTPUT }}` (one per line) @@ -189,14 +189,6 @@ The compiler automatically generates a separate `add_labels` job that: - **Security**: Only label addition is supported—no removal operations are allowed - **Validation**: The job fails if any requested label is not in the `allowed` list -**Configuration:** -```yaml -output: - labels: - allowed: [triage, bug, enhancement] # Mandatory: list of allowed labels (must be non-empty) - max-count: 3 # Optional: maximum number of labels to add (default: 3) -``` - **Agent Output Format:** The agent should write labels to add, one per line, to the `${{ env.GITHUB_AW_OUTPUT }}` file: ``` @@ -213,16 +205,9 @@ needs-review - Label count is limited by `max-count` setting (default: 3) - exceeding this limit causes job failure - Only GitHub's `issues.addLabels` API endpoint is used (no removal endpoints) -**Example workflow using label addition:** -```yaml ---- -... - -output: - labels: - allowed: [triage, bug, enhancement] ---- +**Example natural language to generate the output:** +```markdown # Issue Labeling Agent Analyze the issue content and determine appropriate labels. From 602e300446fd31523ca46057c3a05a6178267c94 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Thu, 28 Aug 2025 23:08:37 +0100 Subject: [PATCH 3/8] fix lint --- docs/safe-outputs.md | 20 +++++--------------- 1 file changed, 5 insertions(+), 15 deletions(-) diff --git a/docs/safe-outputs.md b/docs/safe-outputs.md index 3e74990378b..22e4d65561d 100644 --- a/docs/safe-outputs.md +++ b/docs/safe-outputs.md @@ -12,19 +12,9 @@ The `output:` element of your workflow's frontmatter declares that your agentic 3. The compiler automatically generates additional jobs that read this output and perform the requested actions 4. Only these generated jobs receive the necessary write permissions -For example, if you want your agent to create a GitHub issue based on its analysis, you can add the following to your workflow frontmatter: +## Available Output Types -```yaml -output: - issue: -``` - -This declares that the workflow can create one new issue in the repository - and that's all. -This is done in a separate, non-agentic job that creates the issue after your main agentic job completes. This second job will implicitly have `issues: write` permissions, but your main job does not need `issues: write` permission, enhancing security. - -### Available Output Types - -## Issue Creation (`issue:`) +### New Issue Creation (`issue:`) Adding `issue:` to the `output:` section of your workflow declares that the workflow should conclude with the creation of a GitHub issue based on the agent's output. @@ -60,7 +50,7 @@ The first line of your output will become the issue title. The rest will become the issue body. ``` -## Issue Comment Creation (`issue_comment:`) +### Issue Comment Creation (`issue_comment:`) Adding `issue_comment:` to the output section of your workflow declares that the workflow should conclude with posting a comment on the triggering issue or pull request based on the agent's output. @@ -93,7 +83,7 @@ Your entire output will be posted as a comment on the triggering issue or PR. This automatically creates GitHub issues or comments from the agent's analysis without requiring write permissions on the main job. -## Pull Request Creation (`pull-request:`) +### Pull Request Creation (`pull-request:`) Adding `pull-request:` to the `output:` section of your workflow declares that the workflow should conclude with the creation of a pull request containing code changes generated by the agent. @@ -159,7 +149,7 @@ The workflow automatically handles patch creation—your agent simply makes file 3. Generates git patches using `git format-patch` 4. Validates patch existence and content before proceeding with PR creation -## Label Addition (`labels:`) +### Label Addition (`labels:`) Adding `labels:` to the `output:` section of your workflow declares that the workflow should conclude with adding labels to the current issue or pull request based on the agent's analysis. From 46bf3ec8eb12ebe0a630fa3116c72409a6ac7c84 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Thu, 28 Aug 2025 23:09:50 +0100 Subject: [PATCH 4/8] fix lint --- docs/safe-outputs.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/docs/safe-outputs.md b/docs/safe-outputs.md index 22e4d65561d..e90c0f0c531 100644 --- a/docs/safe-outputs.md +++ b/docs/safe-outputs.md @@ -27,11 +27,13 @@ output: ``` **How Your Agent Provides Output:** + Your agentic workflow writes its content to `${{ env.GITHUB_AW_OUTPUT }}`. The output should be structured as: - **First non-empty line**: Becomes the issue title (markdown heading syntax like `# Title` is automatically stripped) - **Remaining content**: Becomes the issue body **What This Output Option Does:** + The compiler automatically generates a separate `create_issue` job that: - Runs after your main agentic job completes - Reads the content from `${{ env.GITHUB_AW_OUTPUT }}` @@ -40,6 +42,7 @@ The compiler automatically generates a separate `create_issue` job that: - **Security**: Only this generated job gets `issues: write` permission—your agentic code runs with minimal permissions **Example natural language to generate the output:** + ```yaml # Code Analysis Agent @@ -55,15 +58,18 @@ The rest will become the issue body. Adding `issue_comment:` to the output section of your workflow declares that the workflow should conclude with posting a comment on the triggering issue or pull request based on the agent's output. **Configuration Options:** + ```yaml output: issue_comment: {} # Create comments on issues/PRs from agent output ``` **How Your Agent Provides Output:** + Your agentic workflow writes its content to `${{ env.GITHUB_AW_OUTPUT }}`. The entire content becomes the comment body—no special formatting is required. **What This Output Option Does:** + The compiler automatically generates a separate `create_issue_comment` job that: - Only runs when triggered by an issue or pull request event - Reads the content from `${{ env.GITHUB_AW_OUTPUT }}` @@ -72,6 +78,7 @@ The compiler automatically generates a separate `create_issue_comment` job that: - **Security**: Only this generated job gets `issues: write` and `pull-requests: write` permissions **Example natural language to generate the output:** + ```markdown # Issue/PR Analysis Agent @@ -88,6 +95,7 @@ This automatically creates GitHub issues or comments from the agent's analysis w Adding `pull-request:` to the `output:` section of your workflow declares that the workflow should conclude with the creation of a pull request containing code changes generated by the agent. **Configuration Options:** + ```yaml output: pull-request: @@ -97,6 +105,7 @@ output: ``` **How Your Agent Provides Output:** + Your agentic workflow provides output in two ways: 1. **File changes**: Make any file changes in the working directory—these are automatically collected using `git add -A` and committed 2. **PR description**: Write to `${{ env.GITHUB_AW_OUTPUT }}` with: @@ -118,6 +127,7 @@ The compiler automatically: - **Security**: Only this generated job gets `contents: write`, `issues: write`, and `pull-requests: write` permissions **Example natural language to generate the output:** + ````markdown # Code Improvement Agent @@ -143,6 +153,7 @@ Fix coding style issues ```` **Automatic Patch Generation:** + The workflow automatically handles patch creation—your agent simply makes file changes, and the system: 1. Stages changes with `git add -A` 2. Commits them as "[agent] staged files" @@ -154,6 +165,7 @@ The workflow automatically handles patch creation—your agent simply makes file Adding `labels:` to the `output:` section of your workflow declares that the workflow should conclude with adding labels to the current issue or pull request based on the agent's analysis. **Configuration Options:** + ```yaml output: labels: @@ -162,6 +174,7 @@ output: ``` **How Your Agent Provides Output:** + Your agentic workflow writes labels to add to `${{ env.GITHUB_AW_OUTPUT }}`, one label per line: ``` triage @@ -170,6 +183,7 @@ needs-review ``` **What This Output Option Does:** + The compiler automatically generates a separate `add_labels` job that: - Only runs when triggered by an issue or pull request event - Reads the labels from `${{ env.GITHUB_AW_OUTPUT }}` (one per line) @@ -180,6 +194,7 @@ The compiler automatically generates a separate `add_labels` job that: - **Validation**: The job fails if any requested label is not in the `allowed` list **Agent Output Format:** + The agent should write labels to add, one per line, to the `${{ env.GITHUB_AW_OUTPUT }}` file: ``` triage @@ -188,6 +203,7 @@ needs-review ``` **Safety Features:** + - Empty lines in agent output are ignored - Lines starting with `-` are rejected (no removal operations allowed) - Duplicate labels are automatically removed From ca7ed399de07049baa91b9c7cf80e31f4513e3e0 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Thu, 28 Aug 2025 23:10:41 +0100 Subject: [PATCH 5/8] fix lint --- docs/safe-outputs.md | 43 ------------------------------------------- 1 file changed, 43 deletions(-) diff --git a/docs/safe-outputs.md b/docs/safe-outputs.md index e90c0f0c531..26e4e593488 100644 --- a/docs/safe-outputs.md +++ b/docs/safe-outputs.md @@ -32,15 +32,6 @@ Your agentic workflow writes its content to `${{ env.GITHUB_AW_OUTPUT }}`. The o - **First non-empty line**: Becomes the issue title (markdown heading syntax like `# Title` is automatically stripped) - **Remaining content**: Becomes the issue body -**What This Output Option Does:** - -The compiler automatically generates a separate `create_issue` job that: -- Runs after your main agentic job completes -- Reads the content from `${{ env.GITHUB_AW_OUTPUT }}` -- Parses it to extract title and body -- Creates a GitHub issue with optional title prefix and labels -- **Security**: Only this generated job gets `issues: write` permission—your agentic code runs with minimal permissions - **Example natural language to generate the output:** ```yaml @@ -68,15 +59,6 @@ output: Your agentic workflow writes its content to `${{ env.GITHUB_AW_OUTPUT }}`. The entire content becomes the comment body—no special formatting is required. -**What This Output Option Does:** - -The compiler automatically generates a separate `create_issue_comment` job that: -- Only runs when triggered by an issue or pull request event -- Reads the content from `${{ env.GITHUB_AW_OUTPUT }}` -- Posts the entire output as a comment on the triggering issue or PR -- Automatically skips execution if not running in an issue/PR context -- **Security**: Only this generated job gets `issues: write` and `pull-requests: write` permissions - **Example natural language to generate the output:** ```markdown @@ -112,20 +94,6 @@ Your agentic workflow provides output in two ways: - **First non-empty line**: Becomes the PR title - **Remaining content**: Becomes the PR description -**What This Output Option Does:** -The compiler automatically: -1. **Adds a git patch generation step** to your main job that: - - Runs `git add -A` to stage any file changes made by your agent - - Commits staged files with message "[agent] staged files" - - Generates git patches using `git format-patch` and saves to `/tmp/aw.patch` -2. **Generates a separate `create_pull_request` job** that: - - Reads the patches from `/tmp/aw.patch` and validates they exist and are valid - - Creates a new branch with cryptographically secure random naming - - Applies the git patches to create the code changes - - Reads the PR description from `${{ env.GITHUB_AW_OUTPUT }}` - - Creates a pull request with optional title prefix, labels, and draft status - - **Security**: Only this generated job gets `contents: write`, `issues: write`, and `pull-requests: write` permissions - **Example natural language to generate the output:** ````markdown @@ -182,17 +150,6 @@ bug needs-review ``` -**What This Output Option Does:** - -The compiler automatically generates a separate `add_labels` job that: -- Only runs when triggered by an issue or pull request event -- Reads the labels from `${{ env.GITHUB_AW_OUTPUT }}` (one per line) -- Validates each label against the mandatory `allowed` list -- Enforces the `max-count` limit (default: 3 labels) -- Adds only valid labels to the current issue or pull request -- **Security**: Only label addition is supported—no removal operations are allowed -- **Validation**: The job fails if any requested label is not in the `allowed` list - **Agent Output Format:** The agent should write labels to add, one per line, to the `${{ env.GITHUB_AW_OUTPUT }}` file: From 84e410183d26bd3dbb60cd6459b22e22832d835c Mon Sep 17 00:00:00 2001 From: Don Syme Date: Thu, 28 Aug 2025 23:15:15 +0100 Subject: [PATCH 6/8] fix docs --- docs/safe-outputs.md | 50 ++++++++++++-------------------------------- 1 file changed, 13 insertions(+), 37 deletions(-) diff --git a/docs/safe-outputs.md b/docs/safe-outputs.md index 26e4e593488..353fbf912c4 100644 --- a/docs/safe-outputs.md +++ b/docs/safe-outputs.md @@ -4,11 +4,11 @@ One of the primary security features of GitHub Agentic Workflows is "safe output ## Overview (`output:`) -The `output:` element of your workflow's frontmatter declares that your agentic workflow should conclude with optional automated actions based on the agent's output. This enables your AI agent to write content that is then automatically processed to create GitHub issues, comments, pull requests, or add labels—all without giving the agentic portion of the workflow any write permissions. +The `output:` element of your workflow's frontmatter declares that your agentic workflow should conclude with optional automated actions based on the agentic workflow's output. This enables your workflow to write content that is then automatically processed to create GitHub issues, comments, pull requests, or add labels—all without giving the agentic portion of the workflow any write permissions. **How It Works:** -1. Your agentic workflow runs with minimal read-only permissions -2. The agent writes its output to the special `${{ env.GITHUB_AW_OUTPUT }}` environment variable +1. The agentic part of your workflow runs with minimal read-only permissions +2. The workflow writes its output to the special `${{ env.GITHUB_AW_OUTPUT }}` environment variable 3. The compiler automatically generates additional jobs that read this output and perform the requested actions 4. Only these generated jobs receive the necessary write permissions @@ -16,14 +16,14 @@ The `output:` element of your workflow's frontmatter declares that your agentic ### New Issue Creation (`issue:`) -Adding `issue:` to the `output:` section of your workflow declares that the workflow should conclude with the creation of a GitHub issue based on the agent's output. +Adding `issue:` to the `output:` section of your workflow declares that the workflow should conclude with the creation of a GitHub issue based on the workflow's output. **Configuration Options:** ```yaml output: issue: title-prefix: "[ai] " # Optional: prefix for issue titles - labels: [automation, ai-agent] # Optional: labels to attach to issues + labels: [automation, agent] # Optional: labels to attach to issues ``` **How Your Agent Provides Output:** @@ -46,13 +46,13 @@ The rest will become the issue body. ### Issue Comment Creation (`issue_comment:`) -Adding `issue_comment:` to the output section of your workflow declares that the workflow should conclude with posting a comment on the triggering issue or pull request based on the agent's output. +Adding `issue_comment:` to the output section of your workflow declares that the workflow should conclude with posting a comment on the triggering issue or pull request based on the workflow's output. **Configuration Options:** ```yaml output: - issue_comment: {} # Create comments on issues/PRs from agent output + issue_comment: {} # Create comments on issues/PRs from workflow output ``` **How Your Agent Provides Output:** @@ -70,11 +70,11 @@ Write your analysis to ${{ env.GITHUB_AW_OUTPUT }} at the end. Your entire output will be posted as a comment on the triggering issue or PR. ``` -This automatically creates GitHub issues or comments from the agent's analysis without requiring write permissions on the main job. +This automatically creates GitHub issues or comments from the workflow's analysis without requiring write permissions on the main job. ### Pull Request Creation (`pull-request:`) -Adding `pull-request:` to the `output:` section of your workflow declares that the workflow should conclude with the creation of a pull request containing code changes generated by the agent. +Adding `pull-request:` to the `output:` section of your workflow declares that the workflow should conclude with the creation of a pull request containing code changes generated by the workflow. **Configuration Options:** @@ -96,37 +96,22 @@ Your agentic workflow provides output in two ways: **Example natural language to generate the output:** -````markdown +```markdown # Code Improvement Agent Analyze the latest commit and suggest improvements. 1. Make any file changes directly in the working directory 2. Write a PR title and description to ${{ env.GITHUB_AW_OUTPUT }} - -The workflow will automatically: -- Stage your changes with `git add -A` -- Commit them as "[agent] staged files" -- Generate patches with `git format-patch` -- Create a pull request with your changes - -Example output format for ${{ env.GITHUB_AW_OUTPUT }}: ``` -Fix coding style issues -- Updated variable naming conventions -- Fixed indentation in helper functions -- Added missing documentation -``` -```` - -**Automatic Patch Generation:** +**Which Files are Included in Pull Request** -The workflow automatically handles patch creation—your agent simply makes file changes, and the system: +The agentic part of your workflow simply makes file changes, and the system: 1. Stages changes with `git add -A` 2. Commits them as "[agent] staged files" 3. Generates git patches using `git format-patch` -4. Validates patch existence and content before proceeding with PR creation +4. Creates a pull request with these changes ### Label Addition (`labels:`) @@ -150,15 +135,6 @@ bug needs-review ``` -**Agent Output Format:** - -The agent should write labels to add, one per line, to the `${{ env.GITHUB_AW_OUTPUT }}` file: -``` -triage -bug -needs-review -``` - **Safety Features:** - Empty lines in agent output are ignored From 2b415fa77bc942a16ec80a7d43ddf1797b84ab3d Mon Sep 17 00:00:00 2001 From: Don Syme Date: Thu, 28 Aug 2025 23:17:11 +0100 Subject: [PATCH 7/8] fix docs --- docs/safe-outputs.md | 24 ++++-------------------- 1 file changed, 4 insertions(+), 20 deletions(-) diff --git a/docs/safe-outputs.md b/docs/safe-outputs.md index 353fbf912c4..c4439d0c33a 100644 --- a/docs/safe-outputs.md +++ b/docs/safe-outputs.md @@ -26,9 +26,7 @@ output: labels: [automation, agent] # Optional: labels to attach to issues ``` -**How Your Agent Provides Output:** - -Your agentic workflow writes its content to `${{ env.GITHUB_AW_OUTPUT }}`. The output should be structured as: +The agentic part of your workflow should write its content to `${{ env.GITHUB_AW_OUTPUT }}`. The output should be structured as: - **First non-empty line**: Becomes the issue title (markdown heading syntax like `# Title` is automatically stripped) - **Remaining content**: Becomes the issue body @@ -55,9 +53,7 @@ output: issue_comment: {} # Create comments on issues/PRs from workflow output ``` -**How Your Agent Provides Output:** - -Your agentic workflow writes its content to `${{ env.GITHUB_AW_OUTPUT }}`. The entire content becomes the comment body—no special formatting is required. +The agentic part of your workflow should writes its content to `${{ env.GITHUB_AW_OUTPUT }}`. The entire content becomes the comment body—no special formatting is required. **Example natural language to generate the output:** @@ -86,9 +82,7 @@ output: draft: true # Optional: create as draft PR (defaults to true) ``` -**How Your Agent Provides Output:** - -Your agentic workflow provides output in two ways: +The agentic part of your workflow should provide output in two ways: 1. **File changes**: Make any file changes in the working directory—these are automatically collected using `git add -A` and committed 2. **PR description**: Write to `${{ env.GITHUB_AW_OUTPUT }}` with: - **First non-empty line**: Becomes the PR title @@ -105,14 +99,6 @@ Analyze the latest commit and suggest improvements. 2. Write a PR title and description to ${{ env.GITHUB_AW_OUTPUT }} ``` -**Which Files are Included in Pull Request** - -The agentic part of your workflow simply makes file changes, and the system: -1. Stages changes with `git add -A` -2. Commits them as "[agent] staged files" -3. Generates git patches using `git format-patch` -4. Creates a pull request with these changes - ### Label Addition (`labels:`) Adding `labels:` to the `output:` section of your workflow declares that the workflow should conclude with adding labels to the current issue or pull request based on the agent's analysis. @@ -126,9 +112,7 @@ output: max-count: 3 # Optional: maximum number of labels to add (default: 3) ``` -**How Your Agent Provides Output:** - -Your agentic workflow writes labels to add to `${{ env.GITHUB_AW_OUTPUT }}`, one label per line: +The agentic part of your workflow writes should labels to add to `${{ env.GITHUB_AW_OUTPUT }}`, one label per line: ``` triage bug From e2caffa4e3e7f3ae8fd0ef8f7fad5354b1b59d62 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Thu, 28 Aug 2025 23:19:36 +0100 Subject: [PATCH 8/8] fix docs --- docs/safe-outputs.md | 7 ------- 1 file changed, 7 deletions(-) diff --git a/docs/safe-outputs.md b/docs/safe-outputs.md index c4439d0c33a..06ea92106a6 100644 --- a/docs/safe-outputs.md +++ b/docs/safe-outputs.md @@ -18,7 +18,6 @@ The `output:` element of your workflow's frontmatter declares that your agentic Adding `issue:` to the `output:` section of your workflow declares that the workflow should conclude with the creation of a GitHub issue based on the workflow's output. -**Configuration Options:** ```yaml output: issue: @@ -46,8 +45,6 @@ The rest will become the issue body. Adding `issue_comment:` to the output section of your workflow declares that the workflow should conclude with posting a comment on the triggering issue or pull request based on the workflow's output. -**Configuration Options:** - ```yaml output: issue_comment: {} # Create comments on issues/PRs from workflow output @@ -72,8 +69,6 @@ This automatically creates GitHub issues or comments from the workflow's analysi Adding `pull-request:` to the `output:` section of your workflow declares that the workflow should conclude with the creation of a pull request containing code changes generated by the workflow. -**Configuration Options:** - ```yaml output: pull-request: @@ -103,8 +98,6 @@ Analyze the latest commit and suggest improvements. Adding `labels:` to the `output:` section of your workflow declares that the workflow should conclude with adding labels to the current issue or pull request based on the agent's analysis. -**Configuration Options:** - ```yaml output: labels: