Incompatibility with GitHub IP allow lists

[Pierrci]

When using gh-aw in a GitHub organization with an IP allow list, workflows fail because the helper jobs (activation, safe_outputs, conclusion) are hardcoded to run on ubuntu-slim, which is a GitHub-hosted runner outside the org's allowed IP range.

The runs-on frontmatter field only applies to the main agent job, so there's no way to route the helper jobs to self-hosted runners that are within the allow list.

Steps to Reproduce

1. Create a repository in a GitHub org that has an IP allow list configured
2. Configure self-hosted runners (e.g., runner group cpu-low) that are within the allowed IP range
3. Create a workflow with runs-on: { group: cpu-low } in the frontmatter
4. Run gh aw compile and trigger the workflow

Expected Behavior

All jobs in the compiled workflow should respect the runs-on configuration, or there should be a frontmatter option to configure the runner for helper jobs (e.g., runs-on-helper: or similar).

Actual Behavior

The main agent job correctly uses the custom runner group, but the activation, safe_outputs, and conclusion jobs are hardcoded to ubuntu-slim:

# In the compiled .lock.yml:
activation:
  runs-on: ubuntu-slim   # ← cannot be changed via frontmatter

agent:
  runs-on:
    group: cpu-low        # ← respects frontmatter

safe_outputs:
  runs-on: ubuntu-slim   # ← cannot be changed

conclusion:
  runs-on: ubuntu-slim   # ← cannot be changed

This causes a 403 error when the helper jobs try to access the repository:

fatal: unable to access 'https://github.com/<org>/<repo>/': The requested URL returned error: 403

Workaround

Manually patching the compiled .lock.yml to replace runs-on: ubuntu-slim with the custom runner group works, but is fragile since gh aw compile overwrites the lock file.

A secondary issue arises: the gh-aw/actions/setup action assumes write access to /opt/gh-aw/, which GitHub-hosted runners allow but self-hosted runners typically don't. This requires runner admins to pre-create the directory (sudo mkdir -p /opt/gh-aw && sudo chmod 777 /opt/gh-aw).

Environment

• gh-aw version: v0.50.4
• GitHub org with IP allow list enabled

[pelikhan]

/scout answer this question. Look for safe-outputs.runs-on

[github-actions]

🔍 Scout Research Report

Triggered by @pelikhan

Executive Summary

safe-outputs.runs-on already exists in gh-aw. Setting it in the frontmatter configures the runner for all helper jobs (activation, safe_outputs, conclusion, unlock), directly addressing the issue.

Solution

Add runs-on: inside the safe-outputs: block in your workflow frontmatter:

---
on:
  issues:
    types: [opened]
runs-on:
  group: cpu-low          # ← main agent job runner
safe-outputs:
  add-comment:
  runs-on: self-hosted    # ← helper jobs runner (activation, safe_outputs, conclusion, unlock)
---

Implementation Details

How It Works

The safe-outputs.runs-on field is parsed in pkg/workflow/safe_outputs_config.go and applied via formatSafeOutputsRunsOn() in safe_outputs_config_helpers.go. Every helper job calls this function:

Job	File
activation	compiler_activation_jobs.go:747
safe_outputs	compiler_safe_outputs_job.go:355
conclusion	notify_comment.go:385
unlock	compiler_unlock_job.go:97
Custom jobs	safe_outputs_jobs.go:136

Default runner is ubuntu-slim when safe-outputs.runs-on is not set.

Important Limitation

The current parser only accepts a plain string for safe-outputs.runs-on:

if runsOnStr, ok := runsOn.(string); ok {
    config.RunsOn = runsOnStr
}

This means complex runner group syntax ({ group: cpu-low }) is not supported for helper jobs — only simple string labels like self-hosted, ubuntu-22.04, or a custom label registered to your self-hosted runner work here.

Recommendations

1. Use a runner label on your self-hosted runners (e.g. ip-allowed) and set safe-outputs: runs-on: ip-allowed in your workflow frontmatter.
2. If your runners are configured via a runner group, assign a custom label to them so they can be targeted by string value.
3. Docs gap: The Safe Outputs reference page mentions "Custom Runner Image" only as an inline snippet (runs-on: ubuntu-22.04) without a full YAML example — a clearer code block showing the complete pattern would help future users.

References:

• §22467401932

🔭 Intelligence gathered by Scout

[Pierrci]

Thanks, but unfortunately, the secondary issue is still there:

the gh-aw/actions/setup action assumes write access to /opt/gh-aw/, which GitHub-hosted runners allow but self-hosted runners typically don't. This requires runner admins to pre-create the directory (sudo mkdir -p /opt/gh-aw && sudo chmod 777 /opt/gh-aw).

Do you have any plans to write the data in another directory, by any chance? (not sure if writing in /opt/ is common or not for actions, but I have never encountered this issue before with custom runners)

[pelikhan]

@Mossaka @lpcox I need a protected folder to drop the javascrit files, not writeable by the agent.