Activation job missing `ref:` in cross-repo checkout for workflow_call triggers

[johnwilliams-12]

Analysis

When using cross-repository triggers with uses: org/platform-repo/.github/workflows/workflow.lock.yml@BRANCH, the activation job generated by gh-aw always checks out the default branch (usually main) of the platform repo, instead of checking out the branch specified in the uses clause.

The agent job correctly uses:

ref: ${{ github.event_name == 'workflow_call' && github.action_ref || github.ref }}

But the activation job omits ref: entirely, causing actions/checkout to default to main.

This means runtime imports ({{#runtime-import ...}}) fail with "Runtime import file not found" if the .md workflow file only exists on the feature branch referenced in the uses: clause.

Root Cause

GenerateGitHubFolderCheckoutStep in pkg/workflow/checkout_manager.go (L312–L329) only accepts a repository parameter and never emits a ref: line:

func (cm *CheckoutManager) GenerateGitHubFolderCheckoutStep(repository string, getActionPin func(string) string) []string {
    // ...
    if repository != "" {
        fmt.Fprintf(&sb, "          repository: %s\n", repository)
    }
    // ← no ref: is ever emitted
    sb.WriteString("          sparse-checkout: |\n")
    // ...
}

The caller in pkg/workflow/compiler_activation_job.go (L447–L452) passes the cross-repo repository expression but has no way to pass a ref:

return cm.GenerateGitHubFolderCheckoutStep(
    "${{ github.event_name == 'workflow_call' && github.action_repository || github.repository }}",
    GetActionPin,
)

Comparison: Activation vs Agent Job

Parameter	Activation Job	Agent Job
repository:	${{ github.event_name == 'workflow_call' && github.action_repository || github.repository }} ✅	✅
ref:	(omitted — defaults to default branch) ❌	${{ github.event_name == 'workflow_call' && github.action_ref || github.ref }} ✅

Symptoms

• Cross-repo CI runs fail in the activation job with errors like Runtime import file not found: .../.github/workflows/<file>.md
• Only reproducible when using a non-default branch for the uses: reference (e.g. @feature-branch)
• Works if changes are already merged to main (since that's what the activation job checks out)
• The inlined-imports: true workaround avoids the issue but shouldn't be required

Documentation Gap

The Central Repo Ops docs describe the cross-repo-aware checkout but only mention the repository: expression. The ref: omission is not documented.

Implementation Plan

1. Update GenerateGitHubFolderCheckoutStep (pkg/workflow/checkout_manager.go)

• Add a ref string parameter to the function signature
• When ref is non-empty, emit ref: <value> in the checkout step YAML
• Keep backward compatibility: empty ref means omit the line (current behavior)

2. Update generateCheckoutGitHubFolderForActivation (pkg/workflow/compiler_activation_job.go)

• When workflow_call is detected and inlined-imports is false, pass the ref expression:

  ${{ github.event_name == 'workflow_call' && github.action_ref || github.ref }}
  

• This makes the activation checkout consistent with the agent job's checkout

3. Update Tests (pkg/workflow/compiler_activation_job_test.go)

• Add test case: workflow_call trigger - cross-repo checkout includes ref expression
  • Verify the generated YAML contains both repository: and ref: with the correct expressions
• Add test case: non-workflow_call trigger - no ref in checkout
  • Verify ref: is not emitted for standard triggers
• Add test case: workflow_call with inlined-imports - no ref needed
  • Verify ref: is omitted when inlined-imports is enabled
• Update existing GenerateGitHubFolderCheckoutStep tests in checkout_manager_test.go for the new parameter

4. Update Documentation (docs/src/content/docs/patterns/central-repo-ops.mdx)

• In the "How It Works" section, update the example to show both repository: and ref: expressions
• Add a note explaining that both are required for non-default branch references to work

5. Follow Guidelines

• Use error message format: [what's wrong]. [what's expected]. [example]
• Run make agent-finish before completing