Skip to content

[Code Quality] Add documentation for tracker-id field in frontmatter #13439

@github-actions

Description

@github-actions

Description

The tracker-id field is fully implemented with detailed schema validation rules but lacks any documentation in the frontmatter reference.

Current Status

  • Schema: Fully defined with validation rules (8-128 chars, alphanumeric + hyphens/underscores)
  • Examples in Schema: workflow-2024-q1, team-alpha-bot, security_audit_v2
  • Production Use: Multiple workflows use it (audit-workflows-daily, blog-auditor-weekly, etc.)
  • Documentation: Not documented in frontmatter reference

Schema Definition

{
  "type": "string",
  "minLength": 8,
  "maxLength": 128,
  "pattern": "^[a-zA-Z0-9_-]+$",
  "description": "Optional tracker identifier to tag all created assets..."
}

Impact

Users miss out on this valuable feature for tracking workflow-created assets (issues, PRs, discussions) across multiple runs.

Suggested Changes

Add comprehensive documentation to docs/src/content/docs/reference/frontmatter.md:

### Asset Tracking (`tracker-id:`)

Assign a unique identifier to all assets created by a workflow (issues, PRs, discussions). This enables querying and managing workflow outputs across multiple runs.

``````yaml
tracker-id: workflow-2024-q1

Requirements:

  • Length: 8-128 characters
  • Characters: Alphanumeric, hyphens, underscores only (a-zA-Z0-9_-)
  • Format: Use descriptive names like workflow-name-v2 or team-alpha-bot

Use Cases:

  • Track all issues created by a specific workflow
  • Query GitHub for assets by tracker ID
  • Organize workflow outputs by campaign or version
  • Clean up assets when workflows are deprecated

Example Query:

gh issue list --label "gh-aw-tracker-id:workflow-2024-q1"

## Files Affected

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

## Success Criteria

- `tracker-id` field is documented with format constraints
- Users understand the asset tracking use case
- Examples show proper naming conventions
- Validation rules (8-128 chars, pattern) are explained

## Source

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

## Priority

**Medium** - Useful asset management feature with zero documentation


<!-- 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:59.872Z --> 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 -->

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions