From 6bee0a46838c8d98fbec80feb56e4ea67823e658 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 18 Jun 2026 04:46:11 +0000 Subject: [PATCH 1/2] Initial plan From f2eadb06b56fcb524e27df07b91801140988ef93 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 18 Jun 2026 05:58:40 +0000 Subject: [PATCH 2/2] Surface new AWF schema fields in docs Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- .github/aw/safe-outputs-content.md | 3 + .github/aw/syntax-agentic.md | 1 + .../content/docs/guides/open-telemetry.mdx | 15 +++ .../docs/reference/frontmatter-full.md | 94 +++++++++++++++++-- .../src/content/docs/reference/frontmatter.md | 2 +- .../content/docs/reference/open-telemetry.mdx | 2 + .../reference/safe-outputs-pull-requests.md | 2 + .../content/docs/reference/safe-outputs.md | 7 ++ 8 files changed, 119 insertions(+), 7 deletions(-) diff --git a/.github/aw/safe-outputs-content.md b/.github/aw/safe-outputs-content.md index a40762f4392..750876edc5b 100644 --- a/.github/aw/safe-outputs-content.md +++ b/.github/aw/safe-outputs-content.md @@ -21,6 +21,7 @@ description: Safe-output reference for issue, discussion, comment, and pull requ close-older-issues: true # Optional: close previous issues from same workflow (default: false) close-older-key: "my-key" # Optional: explicit deduplication key for close-older matching (uses gh-aw-close-key marker) deduplicate-by-title: true # Optional: skip creating an issue when one with the same title exists; integer N allows fuzzy matches up to edit distance N (default: off) + normalize-closing-keywords: true # Optional: strip backticks around recognized issue-closing keywords in body text footer: false # Optional: omit AI-generated footer while preserving XML markers (default: true) target-repo: "owner/repo" # Optional: cross-repository allowed-repos: [owner/other] # Optional: additional repos agent can target (agent uses `repo` field in output) @@ -125,6 +126,7 @@ description: Safe-output reference for issue, discussion, comment, and pull requ required-title-prefix: "[bot]" # Optional: issue/PR title must start with this prefix hide-older-comments: true # Optional: minimize previous comments from same workflow allowed-reasons: [outdated] # Optional: restrict hiding reasons (default: outdated) + normalize-closing-keywords: true # Optional: strip backticks around recognized issue-closing keywords in body text discussions: true # Optional: opt-in to discussions:write permission for discussion comments/replies (default: false) issues: true # Optional: set false to exclude issues:write permission (default: true) pull-requests: true # Optional: set false to exclude pull-requests:write permission (default: true) @@ -182,6 +184,7 @@ description: Safe-output reference for issue, discussion, comment, and pull requ fallback-labels: [needs-review] # Optional: labels for fallback issues (defaults to PR labels) fallback-as-issue: false # Optional: when true (default), creates a fallback issue on PR creation failure; on permission errors, the issue includes a one-click link to create the PR via GitHub's compare URL auto-close-issue: false # Optional: when true (default), adds "Fixes #N" closing keyword when triggered from an issue; set to false to prevent auto-closing the triggering issue on merge. Accepts a boolean or GitHub Actions expression. + normalize-closing-keywords: true # Optional: strip backticks around recognized issue-closing keywords in PR body text target-repo: "owner/repo" # Optional: cross-repository github-token-for-extra-empty-commit: ${{ secrets.MY_CI_PAT }} # Optional: PAT or "app" to trigger CI on created PRs allowed-files: # Recommended: always restrict to specific paths or extensions to limit agent scope diff --git a/.github/aw/syntax-agentic.md b/.github/aw/syntax-agentic.md index 3d32e1dd76a..3ba9e56f91c 100644 --- a/.github/aw/syntax-agentic.md +++ b/.github/aw/syntax-agentic.md @@ -153,6 +153,7 @@ description: Agentic workflow specific frontmatter fields for GitHub Agentic Wor - OIDC mode is used when `github-app` is configured without credentials (`app-id`/`client-id` + `private-key`). - OIDC mode requires `permissions.id-token: write` on the workflow/job. - `headers:` - Comma-separated `key=value` HTTP headers included in every OTLP export request (e.g. `Authorization=Bearer `). Injected as `OTEL_EXPORTER_OTLP_HEADERS`. Supports GitHub Actions expressions. + - `resource-attributes:` - Optional map of additional OTEL resource attributes appended to gh-aw/GitHub defaults. Values may be static strings or GitHub Actions expressions. Do not use `secrets.*` or `vars.*` here because resource attributes are exported to external observability backends and are not treated as secret values. - Example: ```yaml diff --git a/docs/src/content/docs/guides/open-telemetry.mdx b/docs/src/content/docs/guides/open-telemetry.mdx index 001f9b634d3..16f8842b44d 100644 --- a/docs/src/content/docs/guides/open-telemetry.mdx +++ b/docs/src/content/docs/guides/open-telemetry.mdx @@ -75,6 +75,21 @@ observability: Values are plain strings. GitHub Actions expressions also work here, so you can populate attributes from run metadata, variables, or secrets. Empty values are omitted, and non-empty values are masked in runner logs. +## Custom resource attributes + +`observability.otlp.resource-attributes` appends additional resource attributes to the standard gh-aw and GitHub resource attribute set: + +```yaml wrap +observability: + otlp: + endpoint: ${{ secrets.OTLP_ENDPOINT }} + resource-attributes: + service.namespace: platform-automation + deployment.environment: ${{ github.ref_name }} +``` + +Use static strings or GitHub Actions expressions. Do **not** use `secrets.*` or `vars.*` values in `resource-attributes` because resource attributes are exported to external observability backends and are not treated as secret values. + ## Built-in telemetry emitted by gh-aw gh-aw emits a small set of built-in spans and trace artifacts once OTLP is configured. diff --git a/docs/src/content/docs/reference/frontmatter-full.md b/docs/src/content/docs/reference/frontmatter-full.md index 7bff2c00ed5..9861a391b63 100644 --- a/docs/src/content/docs/reference/frontmatter-full.md +++ b/docs/src/content/docs/reference/frontmatter-full.md @@ -3324,6 +3324,11 @@ tools: allowed-extensions: [] # Array of strings + # When true, all .json files are pretty-printed (2-space indent) before being + # committed, making them human-readable in the repository (default: false) + # (optional) + format-json: true + # Format 4: Array of repo-memory configurations for multiple memory locations repo-memory: [] # Array items: object @@ -3569,6 +3574,11 @@ safe-outputs: samples: {} + # When true, strip backticks from recognized issue-closing keywords (e.g. `Closes + # #1` → Closes #1) in body fields for this output type. + # (optional) + normalize-closing-keywords: true + # Format 2: Enable issue creation with default configuration create-issue: null @@ -4097,6 +4107,12 @@ safe-outputs: # (optional) close-older-key: "example-value" + # Required category for matching when close-older-discussions is enabled. Only + # discussions in this category will be considered when searching for older + # discussions to close. + # (optional) + required-category: "example-value" + # When true (default), fallback to creating an issue if discussion creation fails # due to permissions. The fallback issue will include a note indicating it was # intended to be a discussion. If close-older-discussions is enabled, the @@ -4699,6 +4715,11 @@ safe-outputs: samples: {} + # When true, strip backticks from recognized issue-closing keywords (e.g. `Closes + # #1` → Closes #1) in body fields for this output type. + # (optional) + normalize-closing-keywords: true + # Format 2: Enable issue comment creation with default configuration add-comment: null @@ -4912,7 +4933,7 @@ safe-outputs: # Maximum allowed size for git patches in kilobytes (KB) for create-pull-request # only. Overrides safe-outputs max-patch-size for this output type. Defaults to - # 4096 KB (4 MB) when unset. + # 1024 KB (1 MB) when unset. # (optional) max-patch-size: 1 @@ -5104,6 +5125,11 @@ safe-outputs: # (optional) allow-workflows: true + # When true, strip backticks from recognized issue-closing keywords (e.g. `Closes + # #1` → Closes #1) in body fields for this output type. + # (optional) + normalize-closing-keywords: true + # Format 2: Enable pull request creation with default configuration create-pull-request: null @@ -6839,6 +6865,22 @@ safe-outputs: allowed-branches: [] # Array of strings + # Target for merging: 'triggering' (default, current PR), or '*' (any PR with + # pull_request_number field) + # (optional) + target: "example-value" + + # Target repository in format 'owner/repo' for cross-repository operations. Takes + # precedence over trial target repo settings. + # (optional) + target-repo: "example-value" + + # List of additional repositories in format 'owner/repo' that pull requests can be + # merged in. The target repository is always implicitly allowed. + # (optional) + allowed-repos: [] + # Array of strings + # GitHub token to use for this specific output type. Overrides global github-token # if specified. # (optional) @@ -6849,6 +6891,24 @@ safe-outputs: # (optional) staged: true + # Internal hidden feature. Optional list of declarative sample payloads that + # exercise this safe-output handler. Used by the hidden `gh aw compile + # --use-samples` flag to replace the agentic step with a deterministic replay + # through the safe-outputs MCP server. Each entry should conform to the + # corresponding MCP tool inputSchema; recognized sidecar keys (currently `patch` + # for create-pull-request and push-to-pull-request-branch) are stripped before + # schema validation and consumed by the replay driver. + # (optional) + # Accepted formats: + + # Format 1: array + samples: [] + # Array items: object + + # Format 2: object + samples: + {} + # The target item's title must start with this prefix for this operation to # proceed # (optional) @@ -6925,7 +6985,7 @@ safe-outputs: # Maximum allowed size for git patches in kilobytes (KB) for # push-to-pull-request-branch only. Overrides safe-outputs max-patch-size for this - # output type. Defaults to 4096 KB (4 MB) when unset. + # output type. Defaults to 1024 KB (1 MB) when unset. # (optional) max-patch-size: 1 @@ -8117,7 +8177,7 @@ safe-outputs: # (optional) workflows: "read" - # Maximum allowed size for git patches in kilobytes (KB). Defaults to 4096 KB (4 + # Maximum allowed size for git patches in kilobytes (KB). Defaults to 1024 KB (1 # MB). If patch exceeds this size, the job will fail. # (optional) max-patch-size: 1 @@ -8425,12 +8485,25 @@ safe-outputs: # (optional) group-reports: true - # When false, disables creating failure tracking issues when workflows fail. - # Useful for workflows where failures are expected or handled elsewhere. Defaults - # to true. # (optional) + # Accepted formats: + + # Format 1: When false, disables creating failure tracking issues when workflows + # fail. When true, all failures trigger issues. Defaults to true. report-failure-as-issue: true + # Format 2: List of failure categories that should trigger issue creation. + # Categories can be prefixed with '!' to exclude them (e.g., + # '!inference_access_error'). If only non-prefixed categories are specified, only + # those categories trigger issues. If only prefixed (excluded) categories are + # specified, all categories except those trigger issues. If both are specified, + # categories must match included AND not match excluded. Common categories: + # agent_failure, timed_out, missing_safe_outputs, report_incomplete, missing_tool, + # missing_data, inference_access_error, mcp_policy_error, + # ai_credits_rate_limit_error, max_ai_credits_exceeded. + report-failure-as-issue: [] + # Array items: string + # Repository to create failure tracking issues in, in the format 'owner/repo'. # Useful when the current repository has issues disabled. Defaults to the current # repository. @@ -8700,6 +8773,15 @@ observability: # (optional) if-missing: "error" + # Additional OTEL_RESOURCE_ATTRIBUTES entries to append to the standard + # gh-aw/GitHub resource attributes. Values may be static strings or GitHub Actions + # expressions such as '${{ github.repository }}'. Do not use secrets.* or vars.* + # expressions here: resource attributes are exported to external tracing backends + # and are not treated as secret values. + # (optional) + resource-attributes: + {} + # Optional runtime authentication for OTLP export. Supports GitHub App credentials # (client-id/app-id + private-key) for token minting, or implicit GitHub OIDC mode # when the github-app object is present without credentials. diff --git a/docs/src/content/docs/reference/frontmatter.md b/docs/src/content/docs/reference/frontmatter.md index 98d548d8b33..2dcecf527c5 100644 --- a/docs/src/content/docs/reference/frontmatter.md +++ b/docs/src/content/docs/reference/frontmatter.md @@ -335,7 +335,7 @@ observability: X-Tenant: my-org ``` -`endpoint` accepts a string, a `{url, headers}` object, or an array of endpoint objects for fan-out; `headers` accepts a map or comma-separated `key=value` string; `if-missing` supports `error` (default), `warn`, and `ignore`; and `attributes` is an optional map of custom span attributes (values support GitHub Actions expressions). See the [OpenTelemetry guide](/gh-aw/guides/open-telemetry/) for setup and the [OpenTelemetry attribute reference](/gh-aw/reference/open-telemetry/) for emitted fields. +`endpoint` accepts a string, a `{url, headers}` object, or an array of endpoint objects for fan-out; `headers` accepts a map or comma-separated `key=value` string; `if-missing` supports `error` (default), `warn`, and `ignore`; `attributes` is an optional map of custom span attributes (values support GitHub Actions expressions); and `resource-attributes` appends custom OTel resource attributes to the built-in gh-aw/GitHub set. Use static strings or GitHub Actions expressions for `resource-attributes`, but do not use `secrets.*` or `vars.*` values because resource attributes are exported to external observability backends and are not treated as secret values. See the [OpenTelemetry guide](/gh-aw/guides/open-telemetry/) for setup and the [OpenTelemetry attribute reference](/gh-aw/reference/open-telemetry/) for emitted fields. ### Resources (`resources:`) diff --git a/docs/src/content/docs/reference/open-telemetry.mdx b/docs/src/content/docs/reference/open-telemetry.mdx index 6fce3f17cf3..37b198f6427 100644 --- a/docs/src/content/docs/reference/open-telemetry.mdx +++ b/docs/src/content/docs/reference/open-telemetry.mdx @@ -15,6 +15,8 @@ Unless stated otherwise, attributes are emitted only when the underlying value i Resource attributes identify the workflow run, repository, runner, and gh-aw environment attached to emitted spans. +`observability.otlp.resource-attributes` can append custom resource attributes at runtime. Use static strings or GitHub Actions expressions. Do **not** use `secrets.*` or `vars.*` values for this field because resource attributes are exported to external observability backends and are not treated as secret values. + 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 c968bfe4241..67c42ceac88 100644 --- a/docs/src/content/docs/reference/safe-outputs-pull-requests.md +++ b/docs/src/content/docs/reference/safe-outputs-pull-requests.md @@ -48,6 +48,7 @@ safe-outputs: - release/* fallback-as-issue: false # disable issue fallback (default: true) auto-close-issue: false # don't auto-add "Fixes #N" to PR description (default: true) + normalize-closing-keywords: true # strip backticks around recognized issue-closing keywords in PR body text preserve-branch-name: true # omit random salt suffix from branch name (default: false) recreate-ref: true # force-recreate remote branch when it already exists (requires preserve-branch-name; default: false) excluded-files: # strip these files from the patch entirely @@ -81,6 +82,7 @@ By default a random hex suffix is appended to the agent-provided branch name to - `draft` is a **policy**, not a default — the agent cannot override it at runtime. - `auto-close-issue` (default `true`) appends `Fixes #N` to the PR description when the workflow is triggered from an issue. Set to `false` for partial-work or multi-PR flows. +- `normalize-closing-keywords` strips wrapping backticks from recognized issue-closing keywords in the PR body (for example, `` `Closes #123` `` → `Closes #123`). - When `create-pull-request` is configured, git commands (`checkout`, `branch`, `switch`, `add`, `rm`, `commit`, `merge`) are automatically enabled. - PRs do not trigger CI by default. See [Triggering CI](/gh-aw/reference/triggering-ci/). diff --git a/docs/src/content/docs/reference/safe-outputs.md b/docs/src/content/docs/reference/safe-outputs.md index 5ea181ef0f9..43f90ee930a 100644 --- a/docs/src/content/docs/reference/safe-outputs.md +++ b/docs/src/content/docs/reference/safe-outputs.md @@ -118,6 +118,7 @@ safe-outputs: group: true # group as sub-issues under parent close-older-issues: true # close previous issues from same workflow deduplicate-by-title: 1 # drop duplicate titles (true=exact, integer=edit distance) + normalize-closing-keywords: true # strip backticks around recognized issue-closing keywords in body text target-repo: "owner/repo" # cross-repository allowed-repos: ["org/repo1", "org/repo2"] # additional allowed repositories github-token: ${{ secrets.SOME_CUSTOM_TOKEN }} # optional custom token for permissions @@ -300,6 +301,7 @@ safe-outputs: hide-older-comments: true # hide previous comments from same workflow allowed-reasons: [outdated] # restrict hiding reasons (optional) footer: false # omit AI-generated footer (default: true) + normalize-closing-keywords: true # strip backticks around recognized issue-closing keywords in body text required-labels: [bot, automated] # only comment if item has ALL of these labels required-title-prefix: "[bot] " # only comment if item title starts with this prefix ``` @@ -307,6 +309,10 @@ safe-outputs: > [!TIP] > Use `footer: false` to suppress the "Generated by..." attribution line in posted comments. See [Footer Control](/gh-aw/reference/footers/) for global and per-handler options. +#### Normalize closing keywords + +Set `normalize-closing-keywords: true` to strip wrapping backticks from recognized issue-closing keywords in body text (for example, `` `Closes #123` `` becomes `Closes #123` so GitHub can process it as a closing keyword). This field is supported by `create-issue` and `add-comment` on this page, and by `create-pull-request` in [Safe Outputs (Pull Requests)](/gh-aw/reference/safe-outputs-pull-requests/#pull-request-creation-create-pull-request). + The author of the parent issue, PR, or discussion receiving the comment is automatically preserved as an allowed mention. This means `@username` references to the issue/PR/discussion author are not neutralized when the workflow posts a reply. #### Hide Older Comments @@ -865,6 +871,7 @@ safe-outputs: labels: [automation] reviewers: [user1, copilot] assignees: [user1] # assignees for fallback issues created when PR creation cannot proceed (including protected-files fallback) + normalize-closing-keywords: true # strip backticks around recognized issue-closing keywords in PR body text protected-files: fallback-to-issue # create review issue if protected files modified, git commands (`checkout`, `branch`, `switch`, `add`, `rm`, `commit`, `merge`) are automatically enabled. ```