Add workflow documentation URL frontmatter

[Copilot]

Workflows need a canonical, machine-discoverable link to operator and user documentation. This adds a single optional documentation frontmatter field for that purpose.

• Frontmatter and metadata

  • Accept documentation as a non-empty absolute HTTPS URL.
  • Preserve it in generated lock-file metadata for downstream tooling.

• Schema and references

  • Add schema validation, typed frontmatter support, generated-reference handling, and a schema coverage demo.
  • Document the field in the frontmatter guide.

---
name: Repository Health Report
description: Reviews repository health and publishes a weekly report
documentation: https://docs.example.com/automation/repository-health
on:
  schedule: weekly
---

• Fixes Proposal: support top-level doclink workflow frontmatter #55468

---

Generated by 👨‍🍳 PR Sous Chef · pi · gpt54 · 17.3 AIC · ⌖ 7.98 AIC · ⊞ 6.2K · ◷
_{Comment /souschef to run again}

---

gh-aw-pr-sous-chef
Run: https://github.com/github/gh-aw/actions/runs/32777439671

Generated by 👨‍🍳 PR Sous Chef · pi · gpt54 · 6.4 AIC · ⌖ 8 AIC · ⊞ 6.2K · ◷
_{Comment /souschef to run again}

[Copilot]

Pull request overview

Adds a canonical HTTPS documentation URL to workflow frontmatter and compiled lock metadata.

Changes:

• Adds schema validation and typed compiler support.
• Preserves documentation URLs in lock metadata.
• Adds tests, schema coverage, and reference documentation.

Show a summary per file

File	Description
scripts/generate-schema-docs.js	Generates a valid documentation URL example.
schema-demos/schema-demo-documentation.md	Demonstrates the new field.
pkg/workflow/workflow_data.go	Stores the documentation URL.
pkg/workflow/workflow_builder.go	Extracts documentation into workflow data.
pkg/workflow/lock_schema.go	Adds documentation to lock metadata.
pkg/workflow/frontmatter_types.go	Adds typed frontmatter support.
pkg/workflow/frontmatter_types_test.go	Tests typed parsing.
pkg/workflow/frontmatter_extraction_metadata.go	Implements field extraction.
pkg/workflow/compiler_yaml_test.go	Tests emitted lock metadata.
pkg/workflow/compiler_yaml_header.go	Serializes documentation metadata.
pkg/workflow/compiler_orchestrator_workflow_test.go	Tests workflow-data construction.
pkg/parser/schemas/main_workflow_schema.json	Defines URL validation constraints.
pkg/parser/schema_test.go	Tests accepted and rejected values.
docs/src/content/docs/reference/frontmatter.md	Documents the field.
docs/src/content/docs/reference/frontmatter-full.md	Updates generated reference output.

Review details

• Files reviewed: 15/15 changed files
• Comments generated: 3
• Review effort level: Balanced

[gh-aw-bot]

gh-aw-pr-sous-chef
@copilot PR Sous Chef triage: this PR still needs a forward-progress pass before maintainer investigation is likely to be productive.

Please do one focused follow-up pass:

• review the open PR feedback, close the loop in the relevant review threads, and address any remaining maintainer-facing concerns
• refresh the branch if needed and use the pr-finisher skill before handing back for review

I also attempted a branch refresh for this PR in this run.

Run: https://github.com/github/gh-aw/actions/runs/32771472228

Generated by 👨‍🍳 PR Sous Chef · pi · gpt54 · 17.3 AIC · ⌖ 7.98 AIC · ⊞ 6.2K · ◷
_{Comment /souschef to run again}

[pelikhan]

@copilot move the documentation field under metadata, rename "docs"

[Copilot]

gh-aw-pr-sous-chef
@copilot PR Sous Chef triage: this PR still needs a forward-progress pass before maintainer investigation is likely to be productive.
...

Completed the focused follow-up in efa8d4f: applied the maintainer’s metadata.docs shape, addressed URL validation/import precedence/release-note feedback, refreshed docs/tests, and ran the pr-finisher pass.

@copilot move the documentation field under metadata, rename "docs"

Implemented in efa8d4f. The field is now metadata.docs in workflow frontmatter and docs in generated lock metadata.

[pelikhan]

/matt

[github-actions]

🧠 Matt Pocock Skills Reviewer has completed the skills-based review. ✅

🧠 Reviewed using Matt Pocock's skills by Matt Pocock Skills Reviewer

[github-actions]

Skills-Based Review 🧠

Applied /codebase-design and /tdd — requesting minor changes on duplication and test completeness.

📋 Key Themes & Highlights

Key Themes

• Duplicate extraction logic (/codebase-design): extractMetadataDocs in pkg/workflow/frontmatter_extraction_metadata.go mirrors the same map-walk already in pkg/parser/import_field_extractor.go. A cross-reference comment (or shared helper) prevents future divergence.
• Missing t.Parallel() in sub-tests (/tdd): TestCompileWorkflowMetadataDocsImportPrecedence omits t.Parallel() inside the t.Run closure, inconsistent with every other table-driven test in this file.
• No negative test for absent docs (/tdd): Only the "docs is present" path is exercised end-to-end; a test asserting metadata.Docs == "" when the field is omitted would close the regression gap.
• Port-validation comment gap (/diagnosing-bugs): The two-step URL + port validation is correct but uncommented; future simplification could accidentally drop the range check.

Positive Highlights

• ✅ Schema validation (validateMetadataDocs) is called for both main and included workflow files — good symmetry.
• ✅ First-wins import precedence is clearly tested with two cases (main overrides import, import fallback).
• ✅ (redacted) and (redacted) URLs are explicitly rejected in the schema test — good security coverage.
• ✅ omitempty on LockMetadata.Docs keeps the lock file clean when the field is absent.
• ✅ Changeset entry and documentation updates are present and accurate.

🧠 Reviewed using Matt Pocock's skills by Matt Pocock Skills Reviewer · copilot · sonnet46 · 58.3 AIC · ⌖ 10.3 AIC · ⊞ 7.6K
_{Comment /matt to run again}

Comments that could not be inline-anchored

pkg/workflow/frontmatter_extraction_metadata.go:362

[/codebase-design] extractMetadataDocs duplicates the same metadata["docs"] map-walk that already exists in pkg/parser/import_field_extractor.go (~line 60). Two diverging implementations of the same extraction logic is a maintenance hazard.

<details>
<summary>💡 Suggested fix</summary>

Add a cross-reference comment to keep future editors aligned:

// NOTE: parallel extraction exists in pkg/parser/import_field_extractor.go
// (importAccumulator.extractConfigFields). Keep both i…

</details>

<details><summary>pkg/parser/schema_validation.go:171</summary>

**[/diagnosing-bugs]** The port validation is correct but the two-step logic (separate `ParseRequestURI` + `strconv.ParseUint`) is easy to accidentally simplify in future. The reason the port must be validated separately is that `url.Parse` accepts strings like `(example.com/redacted)` or `(example.com/redacted)` without error — `strconv.ParseUint(..., 10, 16)` is what actually enforces the 1–65535 range.

&lt;details&gt;
&lt;summary&gt;💡 Suggested comment&lt;/summary&gt;

```go
// url.ParseRequestURI allows po…

</details>

<details><summary>pkg/workflow/compiler_yaml_test.go:299</summary>

**[/tdd]** `TestCompileWorkflowMetadataDocsImportPrecedence` does not run its sub-tests in parallel (`t.Parallel()` is missing inside the `t.Run` closure). The outer loop uses `tt` in a closure — with Go ≤1.21 this would capture the loop variable by reference. Even with Go 1.22+ range semantics, adding `t.Parallel()` inside each sub-test is the idiomatic pattern used consistently throughout this file.

&lt;details&gt;
&lt;summary&gt;💡 Suggested fix&lt;/summary&gt;

```go
t.Run(tt.name, func(t *testing.T) {
    …

</details>

<details><summary>pkg/workflow/compiler_yaml_test.go:253</summary>

**[/tdd]** There is no test covering the case where `metadata.docs` is _absent_ from the lock file — i.e. a workflow compiled without the field should produce `metadata.Docs == &quot;&quot;`. `TestCompileWorkflowMetadataIncludesDocs` only verifies the present case. Without a negative case a regression that unconditionally emits a default URL would pass all tests.

&lt;details&gt;
&lt;summary&gt;💡 Suggested test case to add&lt;/summary&gt;

```go
func TestCompileWorkflowMetadataDocsAbsent(t *testing.T) {
    // workflow w…

</details>

done

[gh-aw-bot]

gh-aw-pr-sous-chef
@copilot PR Sous Chef triage: this PR still needs forward progress before maintainer investigation is likely to be productive.

Please use the pr-finisher skill and do one focused follow-up pass on this PR.

• review the latest maintainer and reviewer feedback, then either push the smallest needed follow-up or reply in-thread if no code change is still required
• refresh the branch if needed and run make fmt if you touch code
• hand back only after the branch is ready for re-review

I also attempted a branch refresh for this PR in this run.

Run: https://github.com/github/gh-aw/actions/runs/32777439671

Generated by 👨‍🍳 PR Sous Chef · pi · gpt54 · 6.4 AIC · ⌖ 8 AIC · ⊞ 6.2K · ◷
_{Comment /souschef to run again}

[Copilot]

gh-aw-pr-sous-chef
@copilot PR Sous Chef triage: this PR still needs forward progress before maintainer investigation is likely to be productive.
...

Completed the PR-finisher pass: all review threads are resolved, the branch is current with main, and local unit tests, full tests, and workflow recompilation pass. make lint remains blocked by two unrelated warnings introduced in upstream commit 55d6bae; the latest CI runs are approval-gated with no failed jobs.

[github-actions]

🎉 This pull request is included in a new release.

Release: v0.87.5