[Code Quality] Expand secret-masking field documentation with configuration examples

[github-actions]

Description

The secret-masking field has detailed schema configuration but minimal documentation in the frontmatter reference.

Current Status

• ✅ Schema: Defines secret-masking.steps array with GitHub Actions step objects
• ✅ Schema Examples: Shows custom secret redaction patterns
• ⚠️ Documentation: Only mentioned in import/merge contexts
• ❌ Configuration Guide: No guide on configuring secret-masking.steps

Schema Capabilities

The schema defines powerful secret masking features:

{
  "secret-masking": {
    "properties": {
      "steps": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "name": { "type": "string" },
            "run": { "type": "string" }
          }
        }
      }
    }
  }
}

Schema Example:

{
  "name": "Redact custom secrets",
  "run": "find /tmp/gh-aw -type f -exec sed -i 's/password123/REDACTED/g' {} +"
}

Impact

Users may not understand how to implement custom secret masking for workflow-specific sensitive data beyond built-in GitHub secrets.

Suggested Changes

Add a dedicated section to docs/src/content/docs/reference/frontmatter.md:

### Secret Masking (`secret-masking:`)

Configure additional secret redaction steps beyond GitHub's built-in secret masking. Use this to redact workflow-specific sensitive data.

``````yaml
secret-masking:
  steps:
    - name: Redact API keys
      run: |
        find /tmp/gh-aw -type f -name "*.log" \
          -exec sed -i 's/sk-[a-zA-Z0-9]{40}/REDACTED_API_KEY/g' {} +
    
    - name: Redact internal URLs
      run: |
        sed -i 's|(internal.company.com/redacted)|(redacted/redacted)|g' \
          /tmp/gh-aw/agent/output.txt

Use Cases:

• Redact workflow-specific API keys or tokens
• Mask internal URLs or hostnames
• Remove personally identifiable information (PII)
• Sanitize custom log formats

Built-in vs Custom Masking:

• Built-in: GitHub automatically masks secrets defined in repository/organization settings
• Custom: Use secret-masking.steps for workflow-specific patterns

Security Notes:

• Steps run after agent execution
• Use regex patterns carefully to avoid false positives
• Test with non-sensitive data first

## Files Affected

- `docs/src/content/docs/reference/frontmatter.md` (add new section with examples)

## Success Criteria

- `secret-masking` field is documented with clear examples
- Users understand when to use custom secret masking
- Documentation explains difference from built-in GitHub masking
- Examples show common patterns (API keys, URLs, PII)
- Security best practices are noted

## Source

Extracted from [Schema Consistency Audit discussion #13424](https://github.com/github/gh-aw/discussions/13424) - identified as **Low Severity** documentation gap.

## Priority

**Medium** - Security feature with limited documentation (affects security-conscious users)


<!-- gh-aw-tracker-id: discussion-task-miner -->




> AI generated by [Discussion Task Miner - Code Quality Improvement Agent](https://github.com/github/gh-aw/actions/runs/21623941328)
> - [x] expires <!-- gh-aw-expires: 2026-02-17T09:11:58.254Z --> on Feb 17, 2026, 9:11 AM UTC

<!-- gh-aw-agentic-workflow: Discussion Task Miner - Code Quality Improvement Agent, gh-aw-tracker-id: discussion-task-miner, engine: copilot, run: https://github.com/github/gh-aw/actions/runs/21623941328 -->

<!-- gh-aw-workflow-id: discussion-task-miner -->