github / github/gh-aw

feature: support `if:` conditionals on `imports:` entries

Open
#58,221 0 comments 0 reactions 0 assignees View on GitHub
ai-inspected community
Dominant language
Go
Stars
5.1k
Forks
541
Avg merge
5h 46m
Merged PRs (30d)
760

Description

## Summary

Extend the `imports:` frontmatter (documented at [Sharing Workflows](https://github.github.com/gh-aw/practices/sharing-workflows/) and [Imports Reference](https://github.github.com/gh-aw/reference/imports/)) to support an `if:` conditional per import entry, so an imported shared fragment (and any parameters passed via `with:`) can be enabled/disabled based on an expression, similar to `if:` on GitHub Actions steps/jobs.

## Motivation

Shared fragments such as `shared/otlp.md` often depend on secrets or vars that may not be configured in every consuming repository (e.g. `GH_AW_OTEL_SENTRY_AUTHORIZATION`). Today there's no way to conditionally skip an import at compile/runtime if the required secret/var is empty, forcing consumers to either always define the secret or fork/omit the import manually.

This was raised concretely in #57960, which asks for OpenTelemetry setup to be disabled automatically when the Sentry/OTLP auth secret is empty. Adding conditional imports would let the shared fragment itself express this, e.g.:

```yaml
---
on:
schedule: daily
engine: copilot
imports:
- uses: shared/otlp.md
with:
Authentication: ${{ secrets.GH_AW_OTEL_SENTRY_AUTHORIZATION }}
if: ${{ secrets.GH_AW_OTEL_SENTRY_AUTHORIZATION != '' }}
---
```

## Proposed behavior

- Each entry under `imports:` (both the shorthand string form and the `uses:`/`with:` parameterized form) can optionally include an `if:` expression.
- When `if:` evaluates to falsy, the import is skipped entirely at compile time (or resolved to a no-op) — no merged frontmatter/content/tools/MCP config from that fragment is applied, and no error is raised for missing secrets/vars referenced only inside the skipped fragment.
- Expression syntax and evaluation context should be consistent with existing `${{ }}` expression support elsewhere in the frontmatter (e.g. `secrets.*`, `vars.*`), reusing the existing expression evaluator rather than introducing a new one.
- Compilation should clearly report (e.g. in `gh aw compile` output or lock file comments) which imports were skipped due to a falsy `if:`, to aid debugging.
- Should work for both local and remote imports, and interact sensibly with parameterized templates (`with:` schema validation should still apply to the values that would be substituted if the import were active).

## Related

- #57960 — the immediate use case this would resolve
- [Sharing Workflows guide](https://github.github.com/gh-aw/practices/sharing-workflows/)
- [Imports Reference](https://github.github.com/gh-aw/reference/imports/)

Contributor guide

Open the contributing guide

Research direction

Start at the imports processing path used by `gh aw compile` and trace how the existing `${{ }}` expression evaluator handles `secrets.*` and `vars.*`. Verify behavior for shorthand, parameterized, local, and remote imports, including `with:` validation and skipped-import reporting; done means falsy imports contribute no configuration and active imports retain existing behavior.

Written by the indexing model from the issue text.

Assessment

Tech stack
github-actions, go
Domain
build-system, devtools
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.