Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/aw/actions-lock.json
Original file line number Diff line number Diff line change
Expand Up @@ -113,7 +113,7 @@
"github/codeql-action/upload-sarif@v3": {
"repo": "github/codeql-action/upload-sarif",
"version": "v3",
"sha": "6d10af73d5896080e7b530ea0822d927c05661f1"
"sha": "323fb8c0ad5be63b7a6ebf1f32c35882fcfea2cf"
},
"github/stale-repos@v3": {
"repo": "github/stale-repos",
Expand Down
2,413 changes: 2,413 additions & 0 deletions .github/workflows/code-health-file-diet.campaign.g.lock.yml

Large diffs are not rendered by default.

6 changes: 3 additions & 3 deletions .github/workflows/daily-malicious-code-scan.lock.yml

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2,411 changes: 2,411 additions & 0 deletions .github/workflows/incident-response.campaign.g.lock.yml

Large diffs are not rendered by default.

2,413 changes: 2,413 additions & 0 deletions .github/workflows/org-modernization.campaign.g.lock.yml

Large diffs are not rendered by default.

2,413 changes: 2,413 additions & 0 deletions .github/workflows/security-compliance.campaign.g.lock.yml

Large diffs are not rendered by default.

23 changes: 22 additions & 1 deletion docs/src/content/docs/guides/campaigns.md
Original file line number Diff line number Diff line change
Expand Up @@ -272,13 +272,34 @@ gh aw campaign status --json # JSON status output
gh aw campaign new security-q1-2025 # Scaffold a new campaign spec
gh aw campaign validate # Validate all campaign specs
gh aw campaign validate --json # JSON validation report
gh aw campaign validate --no-strict # Report problems without failing
gh aw campaign validate --strict=false # Report problems without failing
```

This gives you a centralized, Git-backed catalog of campaigns in the
repository, aligned with the executable workflows in `.github/workflows/` and
the data they write into repo-memory.

### Compile Integration and Orchestrators

Campaign spec files participate in the normal `compile` workflow:

- `gh aw compile` automatically validates all `.github/workflows/*.campaign.md` specs before compiling workflows.
- Validation checks both the spec itself (IDs, tracker labels, lifecycle state, etc.) and that all referenced `workflows` exist in `.github/workflows/`.
- If any campaign spec has problems, `compile` fails with a `campaign validation failed` error until issues are fixed.

**Orchestrator workflows** are automatically generated for each campaign spec:

```bash wrap
gh aw compile
```

When specs are valid:

- Each `<name>.campaign.md` generates an orchestrator markdown workflow named `<name>.campaign.g.md` next to the spec.
- The orchestrator is compiled like any other workflow to `<name>.campaign.g.lock.yml`.
- This makes campaigns first-class, compilable entry points while keeping specs declarative.
- Orchestrators are only generated when the campaign spec has meaningful details (tracker labels, workflows, memory paths, or metrics glob).

### Interactive Campaign Designer

For a more guided, conversational experience, this repo also includes a
Expand Down
2 changes: 2 additions & 0 deletions docs/src/content/docs/setup/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -155,6 +155,8 @@ gh aw compile --strict --zizmor # Strict mode with security scanning
gh aw compile --validate --strict # Validate schema and enforce strict mode
```

**Campaign specs and orchestrators:** In repositories that define campaign spec files under `.github/workflows/*.campaign.md`, `gh aw compile` first validates those specs (including referenced `workflows`) and fails the compilation if any problems are found. By default, `compile` also synthesizes an orchestrator workflow for each valid spec that has meaningful details (e.g., `security-compliance.campaign.md` → `security-compliance-campaign.md`) and compiles it to a corresponding `.lock.yml` file. Orchestrators are only generated when the campaign spec includes tracker labels, workflows, memory paths, or a metrics glob.

See [Strict Mode reference](/gh-aw/reference/frontmatter/#strict-mode-strict) for frontmatter configuration and [Security Guide](/gh-aw/guides/security/#strict-mode-validation) for best practices.

### Testing
Expand Down
86 changes: 86 additions & 0 deletions pkg/campaign/orchestrator.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
package campaign

import (
"fmt"
"strings"

"github.com/githubnext/gh-aw/pkg/workflow"
)

// BuildOrchestrator constructs a minimal agentic workflow representation for a
// given CampaignSpec. The resulting WorkflowData is compiled via the standard
// CompileWorkflowDataWithValidation pipeline, and the orchestratorPath
// determines the emitted .lock.yml name.
func BuildOrchestrator(spec *CampaignSpec, campaignFilePath string) (*workflow.WorkflowData, string) {
// Derive orchestrator markdown path alongside the campaign spec, using a
// distinct suffix to avoid colliding with existing workflows. We use
// a `.campaign.g.md` suffix to make it clear that the file is generated
// from the corresponding `.campaign.md` spec.
base := strings.TrimSuffix(campaignFilePath, ".campaign.md")
orchestratorPath := base + ".campaign.g.md"

name := spec.Name
if strings.TrimSpace(name) == "" {
name = fmt.Sprintf("Campaign: %s", spec.ID)
}

description := spec.Description
if strings.TrimSpace(description) == "" {
description = fmt.Sprintf("Orchestrator workflow for campaign '%s' (tracker: %s)", spec.ID, spec.TrackerLabel)
}

// Default triggers: daily schedule plus manual workflow_dispatch.
onSection := "on:\n schedule:\n - cron: \"0 18 * * *\"\n workflow_dispatch:\n"

// Simple markdown body giving the agent context about the campaign.
markdownBuilder := &strings.Builder{}
markdownBuilder.WriteString("# Campaign Orchestrator\n\n")
markdownBuilder.WriteString(fmt.Sprintf("This workflow orchestrates the '%s' campaign.\n\n", name))

// Track whether we have any meaningful campaign details
hasDetails := false

if spec.TrackerLabel != "" {
markdownBuilder.WriteString(fmt.Sprintf("- Tracker label: `%s`\n", spec.TrackerLabel))
hasDetails = true
}
if len(spec.Workflows) > 0 {
markdownBuilder.WriteString("- Associated workflows: ")
markdownBuilder.WriteString(strings.Join(spec.Workflows, ", "))
markdownBuilder.WriteString("\n")
hasDetails = true
}
if len(spec.MemoryPaths) > 0 {
markdownBuilder.WriteString("- Memory paths: ")
markdownBuilder.WriteString(strings.Join(spec.MemoryPaths, ", "))
markdownBuilder.WriteString("\n")
hasDetails = true
}
if spec.MetricsGlob != "" {
markdownBuilder.WriteString(fmt.Sprintf("- Metrics glob: `%s`\n", spec.MetricsGlob))
hasDetails = true
}

// Return nil if the campaign spec has no meaningful details for the prompt
if !hasDetails {
return nil, ""
}

markdownBuilder.WriteString("\nEach time this orchestrator runs on its daily schedule (or when manually dispatched), generate a concise status report for this campaign. Summarize current metrics, highlight blockers, and update any tracker issues using the campaign label.\n")
markdownBuilder.WriteString("\nUse these details to coordinate workers, update metrics, and track progress for this campaign.\n")

data := &workflow.WorkflowData{
Name: name,
Description: description,
MarkdownContent: markdownBuilder.String(),
On: onSection,
// Use a standard Ubuntu runner for the main agent job so the
// compiled orchestrator always has a valid runs-on value.
RunsOn: "runs-on: ubuntu-latest",
// Default roles match the workflow compiler's defaults so that
// membership checks have a non-empty GH_AW_REQUIRED_ROLES value.
Roles: []string{"admin", "maintainer", "write"},
}

return data, orchestratorPath
}
49 changes: 49 additions & 0 deletions pkg/campaign/orchestrator_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
package campaign

import (
"strings"
"testing"
)

func TestBuildOrchestrator_BasicShape(t *testing.T) {
spec := &CampaignSpec{
ID: "security-q1-2025",
Name: "Security Q1 2025",
Description: "Security compliance campaign",
Workflows: []string{"security-compliance"},
MemoryPaths: []string{"memory/campaigns/security-q1-2025/**"},
MetricsGlob: "memory/campaigns/security-q1-2025/*.json",
TrackerLabel: "campaign:security-q1-2025",
}

mdPath := ".github/workflows/security-compliance.campaign.md"
data, orchestratorPath := BuildOrchestrator(spec, mdPath)

if orchestratorPath != ".github/workflows/security-compliance.campaign.g.md" {
t.Fatalf("unexpected orchestrator path: got %q", orchestratorPath)
}

if data == nil {
t.Fatalf("expected non-nil WorkflowData")
}

if data.Name != spec.Name {
t.Fatalf("unexpected workflow name: got %q, want %q", data.Name, spec.Name)
}

if strings.TrimSpace(data.On) == "" || !strings.Contains(data.On, "workflow_dispatch") {
t.Fatalf("expected On section with workflow_dispatch trigger, got %q", data.On)
}

if !strings.Contains(data.On, "schedule:") || !strings.Contains(data.On, "0 18 * * *") {
t.Fatalf("expected On section with daily schedule cron, got %q", data.On)
}

if !strings.Contains(data.MarkdownContent, "Security Q1 2025") {
t.Fatalf("expected markdown content to mention campaign name, got: %q", data.MarkdownContent)
}

if !strings.Contains(data.MarkdownContent, spec.TrackerLabel) {
t.Fatalf("expected markdown content to mention tracker label %q, got: %q", spec.TrackerLabel, data.MarkdownContent)
}
}
95 changes: 91 additions & 4 deletions pkg/cli/compile_command.go
Original file line number Diff line number Diff line change
Expand Up @@ -392,7 +392,7 @@ func CompileWorkflows(config CompileConfig) ([]*workflow.WorkflowData, error) {
// Handle campaign spec files separately from regular workflows
if strings.HasSuffix(resolvedFile, ".campaign.md") {
// Validate the campaign spec file and referenced workflows instead of
// compiling it as a regular workflow YAML.
// compiling it directly as a regular workflow YAML.
spec, problems, vErr := campaign.ValidateSpecFromFile(resolvedFile)
if vErr != nil {
errMsg := fmt.Sprintf("failed to validate campaign spec %s: %v", resolvedFile, vErr)
Expand Down Expand Up @@ -433,7 +433,45 @@ func CompileWorkflows(config CompileConfig) ([]*workflow.WorkflowData, error) {
errorCount++
stats.Errors++
stats.FailedWorkflows = append(stats.FailedWorkflows, filepath.Base(resolvedFile))
} else if verbose && !jsonOutput {
validationResults = append(validationResults, result)
continue
}

// Campaign spec is valid and referenced workflows exist.
// Synthesize an orchestrator workflow for this campaign
// and compile it via the standard workflow pipeline.
if !noEmit {
orchestratorData, orchestratorPath := campaign.BuildOrchestrator(spec, resolvedFile)

// Only compile orchestrator if BuildOrchestrator returned valid data
// (it returns nil if the campaign has no meaningful prompt content)
if orchestratorData != nil {
lockFile := strings.TrimSuffix(orchestratorPath, ".md") + ".lock.yml"
result.CompiledFile = lockFile

if err := CompileWorkflowDataWithValidation(compiler, orchestratorData, orchestratorPath, verbose && !jsonOutput, zizmor && !noEmit, poutine && !noEmit, actionlint && !noEmit, strict, validate && !noEmit); err != nil {
if !jsonOutput {
fmt.Fprintln(os.Stderr, err.Error())
}
errorMessages = append(errorMessages, err.Error())
errorCount++
stats.Errors++
stats.FailedWorkflows = append(stats.FailedWorkflows, filepath.Base(orchestratorPath))

result.Valid = false
result.Errors = append(result.Errors, ValidationError{
Type: "compilation_error",
Message: err.Error(),
})
validationResults = append(validationResults, result)
continue
}

compiledCount++
}
}

if verbose && !jsonOutput {
fmt.Fprintln(os.Stderr, console.FormatSuccessMessage(fmt.Sprintf("Validated campaign spec %s", filepath.Base(resolvedFile))))
}

Expand Down Expand Up @@ -669,7 +707,7 @@ func CompileWorkflows(config CompileConfig) ([]*workflow.WorkflowData, error) {
// Handle campaign spec files separately from regular workflows
if strings.HasSuffix(file, ".campaign.md") {
// Validate the campaign spec file and referenced workflows instead of
// compiling it as a regular workflow YAML.
// compiling it directly as a regular workflow YAML.
spec, problems, vErr := campaign.ValidateSpecFromFile(file)
if vErr != nil {
if !jsonOutput {
Expand Down Expand Up @@ -707,7 +745,44 @@ func CompileWorkflows(config CompileConfig) ([]*workflow.WorkflowData, error) {
errorCount++
stats.Errors++
stats.FailedWorkflows = append(stats.FailedWorkflows, filepath.Base(file))
} else if verbose && !jsonOutput {
validationResults = append(validationResults, result)
continue
}

// Campaign spec is valid and referenced workflows exist.
// Synthesize an orchestrator workflow for this campaign
// and compile it via the standard workflow pipeline.
if !noEmit {
orchestratorData, orchestratorPath := campaign.BuildOrchestrator(spec, file)

// Only compile orchestrator if BuildOrchestrator returned valid data
// (it returns nil if the campaign has no meaningful prompt content)
if orchestratorData != nil {
lockFile := strings.TrimSuffix(orchestratorPath, ".md") + ".lock.yml"
result.CompiledFile = lockFile

if err := CompileWorkflowDataWithValidation(compiler, orchestratorData, orchestratorPath, verbose && !jsonOutput, zizmor && !noEmit, poutine && !noEmit, actionlint && !noEmit, strict, validate && !noEmit); err != nil {
if !jsonOutput {
fmt.Fprintln(os.Stderr, err.Error())
}
errorCount++
stats.Errors++
stats.FailedWorkflows = append(stats.FailedWorkflows, filepath.Base(orchestratorPath))

result.Valid = false
result.Errors = append(result.Errors, ValidationError{
Type: "compilation_error",
Message: err.Error(),
})
validationResults = append(validationResults, result)
continue
}

successCount++
}
}

if verbose && !jsonOutput {
fmt.Fprintln(os.Stderr, console.FormatSuccessMessage(fmt.Sprintf("Validated campaign spec %s", filepath.Base(file))))
}

Expand Down Expand Up @@ -1125,6 +1200,18 @@ func compileSingleFile(compiler *workflow.Compiler, file string, stats *Compilat
}
}

// Skip campaign spec files here; they are validated via the campaign
// pipeline and are not compiled into GitHub Actions workflows in watch
// mode. Orchestrators for campaigns are generated only in non-watch
// compile paths to avoid surprising behavior while editing.
if strings.HasSuffix(file, ".campaign.md") {
compileLog.Printf("Skipping campaign spec file (not a workflow): %s", file)
if verbose {
fmt.Fprintln(os.Stderr, console.FormatInfoMessage(fmt.Sprintf("Skipping campaign spec (not a workflow): %s", filepath.Base(file))))
}
return true
}

stats.Total++

compileLog.Printf("Compiling: %s", file)
Expand Down
2 changes: 1 addition & 1 deletion pkg/workflow/data/action_pins.json
Original file line number Diff line number Diff line change
Expand Up @@ -113,7 +113,7 @@
"github/codeql-action/upload-sarif@v3": {
"repo": "github/codeql-action/upload-sarif",
"version": "v3",
"sha": "6d10af73d5896080e7b530ea0822d927c05661f1"
"sha": "323fb8c0ad5be63b7a6ebf1f32c35882fcfea2cf"
},
"github/stale-repos@v3": {
"repo": "github/stale-repos",
Expand Down
Loading