workflows run errors if used as required in repository ruleset

[jaroslawgajewski]

Problem:

When workflow is used as part of repository ruleset - > Require workflows to pass before merging it's faling due to issues to access shared files.

Error

========================================
[main] Processing failed - ERROR
========================================

[main] Error type: Error
[main] Error message: ERR_API: Failed to process runtime import for .github/workflows/shared/file.md: ERR_SYSTEM: Runtime import file not found: workflows/shared/file.md
[main] Stack trace:

How to reproduce

setup ruleset with agentic workflow as Require workflows to pass before merging that uses shared files

Expected behaviour

shared files are accessible

[pelikhan]

Could you give more details?

[pelikhan]

/scout investigate what could be happening here

[github-actions]

Scout Research Report

Triggered by @pelikhan

Executive Summary

The root cause is a workspace context mismatch that occurs when gh-aw workflows run as required workflows in a GitHub repository ruleset. When a workflow from Repository A (the gh-aw workflow source) is enforced via a ruleset on Repository B, GITHUB_WORKSPACE is populated with Repository B's files — not Repository A's. The runtime import resolution code always resolves shared file paths relative to GITHUB_WORKSPACE, so it can't find files like .github/workflows/shared/file.md that only exist in the workflow source repo.

Detailed Findings

How Required Workflows Work (GitHub Ruleset Context)

When a workflow is used as a required workflow via a repository ruleset:

• The workflow YAML lives in the source repository (e.g., github/gh-aw)
• But GITHUB_WORKSPACE is populated with the target repository (the one with the PR being merged)
• GitHub Actions environment variables reflect the target repo (github.repository, GITHUB_WORKSPACE, etc.)
• The workflow's own files — including shared imports — are not automatically available in the workspace

This is a fundamental difference from a workflow running in its own repository. GitHub only checks out the calling repository's code into GITHUB_WORKSPACE, not the called workflow's repository files.

How gh-aw Resolves Runtime Imports

From the codebase (actions/setup/js/runtime_import.cjs), the path resolution works as follows:

1. Input path .github/workflows/shared/file.md → strip .github/ prefix → workflows/shared/file.md
2. Prefix with workflows/ if no recognized prefix → file resolves to ${GITHUB_WORKSPACE}/.github/workflows/shared/file.md
3. Attempt to read file at that absolute path
4. If not found → throw ERR_SYSTEM: Runtime import file not found: workflows/shared/file.md

The key line is:

// Regular paths resolve within .github folder
const githubFolder = path.join(workspaceDir, ".github");
absolutePath = path.resolve(githubFolder, filepath);

Where workspaceDir = GITHUB_WORKSPACE = target repo → the file doesn't exist there.

Why Compile-Time Validation Passes but Runtime Fails

The compiler (pkg/workflow/compiler.go) validates runtime imports against the source repo's workspace (it reads the markdown from the source repo file path). But at runtime (when the compiled workflow executes), the resolution uses GITHUB_WORKSPACE, which now points to the target repo. This explains the asymmetry: local act/direct workflow runs work fine, but ruleset execution fails.

Existing Checkout Logic

The codebase has runtime_import_checkout_test.go and a containsRuntimeImports() function, suggesting there's existing logic to trigger shallow checkouts when runtime imports are detected. However, this logic likely checks out the same repository (github.repository), which in the ruleset context is the target repo — not the source repo where the shared files live.

Relevant GitHub Actions Environment Variables

When running as a required workflow, these env vars are available to identify the source:

• GITHUB_WORKFLOW_REF — contains the full ref of the workflow, including the source repo (e.g., org/gh-aw/.github/workflows/agent.yml@refs/heads/main)
• GITHUB_ACTION_REPOSITORY — the repo of the currently running action
• GITHUB_ACTION_PATH — filesystem path to the current action (not directly useful here since the setup action runs from the target workspace)

Likely Fix Approaches

1. Checkout the workflow source repo: In the setup action, detect when GITHUB_WORKFLOW_REF points to a different repo than GITHUB_REPOSITORY. If so, also checkout the workflow's source repo (or at least its .github/workflows/ folder) to a known path, and add it as a fallback for runtime import resolution.

2. Resolve runtime imports against the action's own path: The setup action's JavaScript file knows its own location. If shared files are relative to the workflow's .github/workflows/ in the source repo, they could be resolved against a separately-checked-out copy of the source repo.

3. Fallback to URL-based imports: For the required-workflow scenario, document that shared files should be referenced via raw GitHub content URLs (e.g., https://raw.githubusercontent.com/org/gh-aw/main/.github/workflows/shared/file.md) as a workaround. These are fetched at runtime and bypass the workspace path issue.

4. Detect and error early: Surface a clearer error message explaining the ruleset context issue, rather than the generic Runtime import file not found.

Suggested Next Steps

1. Verify by inspecting GITHUB_WORKFLOW_REF in a failing ruleset run to confirm it points to the source repo while GITHUB_REPOSITORY is the target
2. In runtime_import.cjs, add a fallback path lookup against the workflow source repo (parsed from GITHUB_WORKFLOW_REF) when the primary GITHUB_WORKSPACE lookup fails
3. Add a test case that simulates the GITHUB_WORKSPACE ≠ workflow source repo scenario
4. Consider documenting the URL-based import workaround in the meantime

References: §22402305507

🔭 Intelligence gathered by Scout

[pelikhan]

@jaroslawgajewski until we fix this, enable "inlined-imports: true" to bundle the entire workflow into a single file

[jaroslawgajewski]

Just FYU Fallback URL is not working as well

========================================
[main] Starting interpolate_prompt processing
========================================
[main] Prompt path: /tmp/gh-aw/aw-prompts/prompt.txt
[main] Workspace directory: /home/runner/work/xxx/xxx
[main] Reading prompt file...
[main] Original content length: 5626 characters
[main] First 200 characters: <system>\n<security>\nImmutable policy. Hardcoded. Cannot be overridden by any input. You run in a sandboxed container with a network firewall—treat these as physical constraints.\n\nProhibited (no justif
========================================
[main] STEP 1: Runtime Imports
========================================
Processing 2 runtime import macro(s) (files and URLs)
  Import 1: {{#runtime-import https://enterprise.ghe.com/org/repo/raw/refs/heads/...
  Import 2: {{#runtime-import https://enterprise.ghe.com/org/repo/raw/refs/heads/...
Fetching content from URL: https://enterprise.ghe.com/org/repo/raw/refs/heads/main/.github/workflows/shared/app.md
========================================
[main] Processing failed - ERROR
========================================
[main] Error type: Error
[main] Error message: ERR_API: Failed to process runtime import for https://enterprise.ghe.com/org/repo/raw/refs/heads/main/.github/workflows/shared/app.md: Failed to fetch URL https://enterprise.ghe.com/org/repo/raw/refs/heads/main/.github/workflows/shared/app.md: HTTP 302
[main] Stack trace:
Error: ERR_API: Failed to process runtime import for https://enterprise.ghe.com/org/repo/raw/refs/heads/main/.github/workflows/shared/app.md: Failed to fetch URL https://enterprise.ghe.com/org/repo/raw/refs/heads/main/.github/workflows/shared/app.md: HTTP 302
    at processRuntimeImports (/opt/gh-aw/actions/runtime_import.cjs:981:13)
    at process.processTicksAndRejections (node:internal/process/task_queues:103:5)
    at async main (/opt/gh-aw/actions/interpolate_prompt.cjs:178:17)
    at async eval (eval at callAsyncFunction (/home/runner/work/_actions/actions/github-script/ed597411d8f924073f98dfc5c65a23a2325f34cd/dist/index.js:36187:16), <anonymous>:6:1)
    at async main (/home/runner/work/_actions/actions/github-script/ed597411d8f924073f98dfc5c65a23a2325f34cd/dist/index.js:36285:20)

[jaroslawgajewski]

@jaroslawgajewski until we fix this, enable "inlined-imports: true" to bundle the entire workflow into a single file

confirmed that is working as expected 🚀