github · pelikhan · Jun 18, 2026 · Jun 18, 2026 · Jun 18, 2026
diff --git 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
@@ -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 <token>`). 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
@@ -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
@@ -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
@@ -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
@@ -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.
+
 <table>
   <thead>
     <tr>

diff --git 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
@@ -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,13 +301,18 @@ 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
 ```
 
 > [!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.
 ```
-Original file line number
+Diff line change
@@ Expand Up @@
     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.
     <table>
       <thead>
         <tr>
@@ Expand Down @@