feature: support `if:` conditionals on `imports:` entries
- 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
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