Proposal: support top-level `doclink` workflow frontmatter

[dsyme]

Summary

Add an optional top-level documentation URL field to agentic workflow frontmatter, with doclink as one possible spelling. It would provide a canonical link to human-facing documentation for the workflow.

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

The workflow Markdown explains the task to the agent, while doclink would point operators and users to documentation covering purpose, ownership, expected outputs, operating procedures, or troubleshooting.

Motivation

Workflows increasingly act like maintained operational services. A short description is useful for discovery, but it is not enough for runbooks or detailed user documentation. There is currently no standard metadata field that lets tools reliably answer "where is the documentation for this workflow?"

A first-class field would avoid burying links in prompt text or encoding them in ad hoc metadata keys. It could eventually be surfaced consistently by CLI commands, status views, workflow catalogs, generated reports, and other tooling.

Proposed syntax

The exact key is open for discussion. Here are examples of candidate spellings:

doclink: https://docs.example.com/automation/repository-health

doc-url: https://docs.example.com/automation/repository-health

docs-url: https://docs.example.com/automation/repository-health

documentation: https://docs.example.com/automation/repository-health

url: https://docs.example.com/automation/repository-health

• doclink is compact and specific, but is a compound spelling that may feel unconventional.
• doc-url or docs-url makes the value type obvious and remains specific to documentation.
• documentation reads naturally but does not signal whether the value is a URL, path, or structured object.
• url is shortest and could act as a general workflow homepage, but may be too ambiguous about what the destination represents.
• homepage is familiar package metadata terminology, but may imply a project or product page rather than operational documentation.

The examples below continue to use doclink only as a placeholder.

Absolute URL:

doclink: https://docs.example.com/automation/repository-health

Repository documentation:

doclink: https://github.com/OWNER/REPO/blob/main/docs/workflows/repository-health.md

GitHub Pages documentation:

doclink: https://owner.github.io/repo/workflows/repository-health/

The minimal proposal is a single optional string rather than a structured object or list.

Potential behavior

• Accept doclink as an optional top-level frontmatter field.
• Validate that the value is a non-empty absolute https:// URL.
• Preserve the value in compiler metadata so downstream tooling can discover it.
• Do not fetch or verify the URL during ordinary compilation.
• Treat the field as descriptive metadata with no effect on workflow execution, permissions, network access, or the agent prompt.
• Include the field in the JSON schema, frontmatter reference, schema demos, and relevant generated metadata/types.
• Allow imported or source-managed workflows to carry the field using the same ownership and precedence rules as other top-level metadata.

Possible CLI presentation

gh aw status

Could display or link the documentation URL when available.

gh aw list --json name,description,doclink
gh aw inspect repo-health --json doclink
gh aw edit repo-health "doclink: https://docs.example.com/repo-health"

The field would also be useful to workflow catalogs and repository automation that inventory deployed workflows.

Validation examples

Valid:

doclink: https://docs.example.com/workflows/repo-health

Invalid or worth rejecting:

doclink: docs/workflows/repo-health.md
doclink: javascript:alert(1)
doclink: ""
doclink:
  user: https://docs.example.com/user-guide
  operator: https://docs.example.com/runbook

Restricting v1 to one absolute HTTPS URL keeps consumers simple and avoids ambiguity about how relative paths should resolve for imported workflows.

Open questions

• Which field name best communicates the intent: doclink, doc-url, docs-url, documentation, homepage, or url?
• Should repository-relative links such as docs/workflow.md be supported? If so, should they resolve against the workflow repository, source repository, or current checkout?
• Should http:// be allowed for local or enterprise installations, or should validation require HTTPS?
• Should the compiled GitHub Actions workflow expose the link in run-name, annotations, or the job summary, or only preserve it as metadata?
• Should gh aw status, a future gh aw inspect, and machine-readable output surface it immediately?
• Do we anticipate needing multiple audiences, such as user guide, operator runbook, and design document, or is a single canonical link preferable?
• How should an importing workflow override a doclink supplied by its source?

Interested in feedback on the field name, accepted URL forms, the first CLI or UI surface where this metadata would be most useful, and whether the link should mean documentation specifically or a more general workflow homepage.

[pelikhan]

@copilot pick the field name most obvious