Review and update GitHub agentic workflows instruction files#4414
Review and update GitHub agentic workflows instruction files#4414
Conversation
|
@copilot continue work |
- Added tracker-id field documentation with examples - Added secret-masking field with custom redaction steps example - Added runtimes field with Node.js and Python examples - Added jobs field for advanced multi-job workflows - Added brief references to imports and mcp-servers fields - All fields aligned with main_workflow_schema.json Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
Completed updating the GitHub agentic workflows instruction file. Added all missing schema fields with documentation and examples in commit 8860d59:
All fields are aligned with the main JSON schema and include practical examples. Build and tests pass successfully. |
There was a problem hiding this comment.
Pull Request Overview
This PR updates the GitHub Agentic Workflows instruction files to comprehensively document all user-facing frontmatter fields from the main JSON schema. The changes ensure that AI agents and developers have complete reference material for working with agentic workflows.
- Added documentation for six previously undocumented schema fields:
tracker-id,secret-masking,runtimes,jobs,imports, andmcp-servers - Aligned documentation with the authoritative main workflow schema (
main_workflow_schema.json) - Included practical examples for each new field to help users understand their usage
Reviewed Changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
.github/instructions/github-agentic-workflows.instructions.md |
Added comprehensive documentation for tracker-id, secret-masking, runtimes, jobs, imports, and mcp-servers fields with examples and usage guidance |
pkg/cli/templates/github-agentic-workflows.instructions.md |
Applied identical updates to the template version to maintain consistency across instruction files |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| @@ -71,6 +71,64 @@ The YAML frontmatter supports these fields: | |||
| - Available roles: `admin`, `maintainer`, `write`, `read`, `all` | |||
There was a problem hiding this comment.
The roles field documentation lists read as an available role, but according to the main workflow schema (pkg/parser/schemas/main_workflow_schema.json lines 3203-3204), the valid roles are: ["admin", "maintainer", "maintain", "write", "triage"].
The documentation should be updated to reflect the correct available roles. Note that maintain is an alternative to maintainer, and triage is included but read is not.
| - Available roles: `admin`, `maintainer`, `write`, `read`, `all` | |
| - Available roles: `admin`, `maintainer`, `maintain`, `write`, `triage`, `all` | |
| - `maintain` is an alternative spelling for `maintainer` | |
| - `triage` is also supported | |
| - `read` is **not** a valid role |
| @@ -71,6 +71,64 @@ The YAML frontmatter supports these fields: | |||
| - Available roles: `admin`, `maintainer`, `write`, `read`, `all` | |||
There was a problem hiding this comment.
The roles field documentation lists read as an available role, but according to the main workflow schema (pkg/parser/schemas/main_workflow_schema.json lines 3203-3204), the valid roles are: ["admin", "maintainer", "maintain", "write", "triage"].
The documentation should be updated to reflect the correct available roles. Note that maintain is an alternative to maintainer, and triage is included but read is not.
| - Available roles: `admin`, `maintainer`, `write`, `read`, `all` | |
| - Available roles: `admin`, `maintainer`, `maintain` (alias for `maintainer`), `write`, `triage` |
Review and Update GitHub Agentic Workflows Instruction Files
Objective: Update the
.github/instructions/github-agentic-workflows.instructions.mdfile to align with the current state of documentation, main frontmatter schema, and existing workflows.Analysis Findings
Missing Schema Fields in Instruction File:
tracker-id- Optional identifier to tag all created assetssecret-masking- Configuration for secret redaction behaviorruntimes- Runtime environment version overridesjobs- Groups together all the jobs in the workflowtimeout_minutes- Deprecated field (hyphenated version is preferred)githubActionsStep- Internal type definition (not user-facing)imports- Documented elsewhere but should be in main schema sectionmcp-servers- Documented elsewhere but should be in main schema sectionDocumentation Sources:
/home/runner/work/gh-aw/gh-aw/pkg/parser/schemas/main_workflow_schema.json/home/runner/work/gh-aw/gh-aw/docs/src/content/docs/reference/frontmatter-full.md/home/runner/work/gh-aw/gh-aw/docs/src/content/docs/reference/frontmatter.md/home/runner/work/gh-aw/gh-aw/.github/instructions/github-agentic-workflows.instructions.mdChanges Made
Added to Agentic Workflow Specific Fields section:
tracker-id- Optional identifier for tagging created assets"workflow-2024-q1","team-alpha-bot"secret-masking- Configuration for secret redactionruntimes- Runtime environment version overridesversion,action-repo,action-versionjobs- Standard GitHub Actions jobs configurationimports- Brief reference with link to detailed section.github/agents/mcp-servers- Brief reference with link to detailed sectionAll additions are aligned with the main JSON schema and include practical examples.
Validation
The instruction file now comprehensively documents all user-facing frontmatter fields from the schema, providing AI agents and developers with complete reference material for working with GitHub Agentic Workflows.
Original prompt
💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.