From 880fc9746cd0699eadd81ce9adf40802b7faf2e6 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 8 Feb 2026 09:44:09 +0000 Subject: [PATCH 1/3] Initial plan From 73fd92bc959ffb2259da4796d3871f09cb238041 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 8 Feb 2026 09:51:57 +0000 Subject: [PATCH 2/3] Add missing godoc comments to compiler functions - Enhanced CompileWorkflow() documentation with detailed description - Enhanced CompileWorkflowData() documentation with usage context - Enhanced shouldAddCheckoutStep() documentation with decision logic - Added package-level documentation to compiler_orchestrator.go - All comments follow Go documentation conventions Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- pkg/workflow/compiler.go | 29 ++++++++++++++++++++++++--- pkg/workflow/compiler_jobs.go | 13 +++++++++++- pkg/workflow/compiler_orchestrator.go | 14 +++++++++++++ 3 files changed, 52 insertions(+), 4 deletions(-) diff --git a/pkg/workflow/compiler.go b/pkg/workflow/compiler.go index 39a38289571..842ce2507ce 100644 --- a/pkg/workflow/compiler.go +++ b/pkg/workflow/compiler.go @@ -78,7 +78,19 @@ func formatCompilerMessage(filePath string, msgType string, message string) stri }) } -// CompileWorkflow converts a markdown workflow to GitHub Actions YAML +// CompileWorkflow compiles a workflow markdown file into a GitHub Actions YAML file. +// It reads the file from disk, parses frontmatter and markdown sections, and generates +// the corresponding workflow YAML. Returns the compiled workflow data or an error. +// +// The compilation process includes: +// - Reading and parsing the markdown file +// - Extracting frontmatter configuration +// - Validating workflow configuration +// - Generating GitHub Actions YAML +// - Writing the compiled workflow to a .lock.yml file +// +// This is the main entry point for compiling workflows from disk. For compiling +// pre-parsed workflow data, use CompileWorkflowData instead. func (c *Compiler) CompileWorkflow(markdownPath string) error { // Store markdownPath for use in dynamic tool generation c.markdownPath = markdownPath @@ -419,8 +431,19 @@ func (c *Compiler) writeWorkflowOutput(lockFile, yamlContent string, markdownPat return nil } -// CompileWorkflowData compiles a workflow from already-parsed WorkflowData -// This avoids re-parsing when the data has already been parsed +// CompileWorkflowData compiles pre-parsed workflow content into GitHub Actions YAML. +// Unlike CompileWorkflow, this accepts already-parsed frontmatter and markdown content +// rather than reading from disk. This is useful for testing and programmatic workflow generation. +// +// The compilation process includes: +// - Validating workflow configuration and features +// - Checking permissions and tool configurations +// - Generating GitHub Actions YAML structure +// - Writing the compiled workflow to a .lock.yml file +// +// This function avoids re-parsing when workflow data has already been extracted, +// making it efficient for scenarios where the same workflow is compiled multiple times +// or when workflow data comes from a non-file source. func (c *Compiler) CompileWorkflowData(workflowData *WorkflowData, markdownPath string) error { // Store markdownPath for use in dynamic tool generation and prompt generation c.markdownPath = markdownPath diff --git a/pkg/workflow/compiler_jobs.go b/pkg/workflow/compiler_jobs.go index 2fcf669ee51..adf1629f998 100644 --- a/pkg/workflow/compiler_jobs.go +++ b/pkg/workflow/compiler_jobs.go @@ -432,7 +432,18 @@ func (c *Compiler) buildCustomJobs(data *WorkflowData, activationJobCreated bool return nil } -// shouldAddCheckoutStep determines if the checkout step should be added based on permissions and custom steps +// shouldAddCheckoutStep returns true if the workflow requires a checkout step. +// A checkout is needed when the workflow uses custom agent files, accesses local +// actions in dev/script mode, or needs to reference .github directory content. +// +// The checkout step is skipped in the following cases: +// - Custom steps already contain a checkout action +// - Workflow is in release mode without a custom agent file +// +// The checkout step is always added when: +// - A custom agent file is specified (via imports) +// - Running in dev or script mode (requires .github and .actions access) +// - Action mode is uninitialized (defaults to requiring checkout) func (c *Compiler) shouldAddCheckoutStep(data *WorkflowData) bool { // Check condition 1: If custom steps already contain checkout, don't add another one if data.CustomSteps != "" && ContainsCheckout(data.CustomSteps) { diff --git a/pkg/workflow/compiler_orchestrator.go b/pkg/workflow/compiler_orchestrator.go index 9fdbcf0f746..dec9b745e1b 100644 --- a/pkg/workflow/compiler_orchestrator.go +++ b/pkg/workflow/compiler_orchestrator.go @@ -1,3 +1,17 @@ +// Package workflow implements workflow compilation orchestration. +// +// The compiler orchestrator is split into 5 focused modules for maintainability: +// +// - orchestrator.go: Shared logger and constants used across orchestrator modules +// - orchestrator_engine.go: Engine detection, validation, and setup logic +// - orchestrator_frontmatter.go: Frontmatter parsing and validation +// - orchestrator_tools.go: Tool configuration and MCP server setup +// - orchestrator_workflow.go: Main workflow orchestration and YAML generation +// +// The orchestrator follows a phased approach with typed result structures +// for clear data flow between compilation stages. Each module handles a specific +// concern in the compilation pipeline, making the codebase easier to understand +// and maintain. package workflow import ( From 900876f0d90c993df456638b97ae0796ee40ed9c Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 8 Feb 2026 09:57:40 +0000 Subject: [PATCH 3/3] Complete documentation improvements - all functions documented MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit All requested godoc comments have been added and validated: - CompileWorkflow() enhanced with detailed documentation - CompileWorkflowData() enhanced with usage context - shouldAddCheckoutStep() enhanced with decision logic - Package-level documentation added to compiler_orchestrator.go - containsRuntimeImports() verified as test-only helper (already documented) All validation passed: - make fmt: ✓ - make lint: ✓ - make build: ✓ - make test-unit: ✓ - go doc output verified for all functions Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- docs/src/content/docs/agent-factory-status.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/content/docs/agent-factory-status.mdx b/docs/src/content/docs/agent-factory-status.mdx index 950a8d5f72e..946cd1956e3 100644 --- a/docs/src/content/docs/agent-factory-status.mdx +++ b/docs/src/content/docs/agent-factory-status.mdx @@ -132,7 +132,7 @@ These are experimental agentic workflows used by the GitHub Next team to learn, | [Smoke Codex](https://github.com/github/gh-aw/blob/main/.github/workflows/smoke-codex.md) | codex | [![Smoke Codex](https://github.com/github/gh-aw/actions/workflows/smoke-codex.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/smoke-codex.lock.yml) | - | - | | [Smoke Copilot](https://github.com/github/gh-aw/blob/main/.github/workflows/smoke-copilot.md) | copilot | [![Smoke Copilot](https://github.com/github/gh-aw/actions/workflows/smoke-copilot.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/smoke-copilot.lock.yml) | - | - | | [Smoke OpenCode](https://github.com/github/gh-aw/blob/main/.github/workflows/smoke-opencode.md) | copilot | [![Smoke OpenCode](https://github.com/github/gh-aw/actions/workflows/smoke-opencode.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/smoke-opencode.lock.yml) | - | - | -| [Smoke Project](https://github.com/github/gh-aw/blob/main/.github/workflows/smoke-project.md) | codex | [![Smoke Project](https://github.com/github/gh-aw/actions/workflows/smoke-project.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/smoke-project.lock.yml) | - | - | +| [Smoke Project](https://github.com/github/gh-aw/blob/main/.github/workflows/smoke-project.md) | copilot | [![Smoke Project](https://github.com/github/gh-aw/actions/workflows/smoke-project.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/smoke-project.lock.yml) | - | - | | [Stale Repository Identifier](https://github.com/github/gh-aw/blob/main/.github/workflows/stale-repo-identifier.md) | copilot | [![Stale Repository Identifier](https://github.com/github/gh-aw/actions/workflows/stale-repo-identifier.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/stale-repo-identifier.lock.yml) | - | - | | [Static Analysis Report](https://github.com/github/gh-aw/blob/main/.github/workflows/static-analysis-report.md) | claude | [![Static Analysis Report](https://github.com/github/gh-aw/actions/workflows/static-analysis-report.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/static-analysis-report.lock.yml) | - | - | | [Step Name Alignment](https://github.com/github/gh-aw/blob/main/.github/workflows/step-name-alignment.md) | claude | [![Step Name Alignment](https://github.com/github/gh-aw/actions/workflows/step-name-alignment.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/step-name-alignment.lock.yml) | `daily` | - |