The workflows subject contains automation scripts that support GitHub Actions workflows, CLI tools, and repository automation. These scripts handle tasks like PR labeling, cache purging, content change analysis, and repository maintenance.

This subject is responsible for:

• PR and issue automation (labeling, metadata, reviewer assignment)
• Cache management (Fastly edge cache purging)
• Content validation and reporting (content type checking, change tables)
• Repository maintenance (orphan file cleanup, syncing)
• Husky git hooks (pre-commit checks)
• GitHub Actions support scripts

Note: This directory does not contain a scripts/ folder since every file here would belong in scripts/. Files are organized flat at the top level with supporting utilities in lib/.

Scripts are registered in package.json:

npm run test -- src/workflows/tests

Many scripts are called from GitHub Actions workflows in .github/workflows/. They typically:

1. Run automatically on PR events, pushes, or schedules
2. Use GitHub Actions context (@actions/github, @actions/core)
3. Require GITHUB_TOKEN environment variable
4. Post results as PR comments or update PR/issue metadata

.github/workflows/docs-feedback-internal.yml runs only in github/docs, even though the workflow is maintained in github/docs-internal and mirrored publicly. Applying docs-feedback-internal to an issue or pull request records its title, description, author, and source link as a comment in the single internal feedback tracker, then posts a public handoff explanation and closes the source. It does not copy the conversation or code changes, and never includes the private tracker link in the public handoff comment.

The workflow requires DOCS_BOT_PAT_BASE in github/docs with permission to read and comment on issues in github/technical-content. The repository's GITHUB_TOKEN comments on and closes the public source with issues: write and pull-requests: write. Fork pull requests use pull_request_target without checking out or executing contributor code.

Keep the tracker configured in the workflow open. If recording fails, the source is not closed. Rerun a failed workflow to retry the handoff. Per-source concurrency and comment markers prevent duplicate entries on reruns or when a label is removed and reapplied. Descriptions longer than 60,000 characters are explicitly truncated with a link back to the full source.

• GitHub API: PR data, issue data, file changes, commit history
• Git repository: File contents, frontmatter, diff information
• Environment variables: GITHUB_TOKEN, FASTLY_TOKEN, BASE_SHA, HEAD_SHA

• @actions/github, @actions/core - GitHub Actions SDK
• @octokit/rest - GitHub API client
• Fastly API - For cache purging
• Various internal subjects for content parsing and validation

• PR/issue comments - Content change summaries, validation results
• PR/issue labels - Applied via GitHub API
• Cache purges - Fastly CDN invalidations
• Exit codes - Success/failure for CI/CD

• src/frame - Frontmatter reading and path utilities
• src/versions - Version detection for content changes
• src/content-linter - Content validation
• src/git - Git utilities (if exists)
• GitHub Actions workflows in .github/workflows/ - Primary consumers

• Team: Docs Engineering

• Some scripts require specific environment variables and can't easily run locally without setup
• Error handling varies across scripts
• Documentation for individual scripts is sometimes inline-only

• Most workflow scripts have limited automated test coverage
• Test locally before deploying to Actions when possible
• Use CLI variants (e.g., content-changes-table-comment-cli.ts) for local testing

When adding a new script:

1. Create the .ts file in src/workflows/
2. Add to package.json scripts if it should be runnable via npm
3. Document any required environment variables
4. Add to .github/workflows/ if it should run automatically
5. Consider creating a -cli.ts variant for local testing
6. Update this README if the script introduces new patterns

• Standardize error handling and logging across scripts