ADR Suggestion Modify Composite Actions Location for ADR #42

[AndrewSazonov]

Associated ADR: #42 Using Composite Actions for Repeated GitHub Workflow Tasks

As part of the ongoing transition to Copier-based templates for EasyScience projects, I propose a small adjustment to ADR #42 regarding where composite GitHub Actions are stored.

Proposed Change

Instead of keeping composite actions in a separate repository (easyscience/github, later agreed to be renamed to easyscience/actions), all composite actions should live inside the Copier templates repository, specifically under easyscience/templates/.github/actions/ along with the full workflow templates in easyscience/templates/.github/workflows/. In practice, this is already how things are being implemented.

Motivation

Storing composite actions directly inside the shared templates brings several benefits:

• Explicit updates via Copier
  Updates to composite actions (e.g. action changes, version bumps, bug fixes) are applied by running copier update (or the associated Pixi task). This avoids silent updates and gives each project explicit control over when CI changes are adopted.
• Simpler dependency model
  No need to maintain or version a separate easyscience/actions repository, reducing organizational and maintenance overhead.
• Better alignment with template-driven workflows
  Since workflows themselves are defined via Copier templates, keeping the composite actions alongside them ensures consistency.

[rozyczko]

Is this a real improvement over a separate repo with composite actions, though? I do not think so.

With a centralized easyscience/actions repo at a pinned version (@v1), we get:

• Instant security patches across all repos (just update the tag)
• Clear separation of concerns (CI infrastructure vs project templates)
• Ability to test action changes independently before rolling out

With embedded-in-templates approach, you get:

• Every repo must run copier update to get fixes
• If there's a critical CI bug or security issue, you need to coordinate updates across all the repos
• Actions and templates become coupled — changing an action requires a template release. This is probably the most important issue, since we are going to be changing the action versioning often.

[AndrewSazonov]

For me, the main concern is the lack of transparency. With a centralized easyscience/actions updates can be rolled out silently across many repositories at once. That’s powerful, but it can also be confusing when CI suddenly breaks in projects that haven’t changed. With the template approach, updates are explicit: you run copier update, see the diff, and consciously accept the CI changes. This feels safer while our CI setup is still actively evolving.

Also, since we already rely on Copier as the main mechanism for managing workflows and project structure, keeping composite actions together with the templates feels natural. In practice, CI logic, Pixi setup, docs build, and repo layout are tightly coupled anyway, so separating them into another repo doesn’t fully remove that coupling - it just hides it.

Yes, this means every repo must run copier update to get fixes, but that’s already true for any workflow or template change. In return, we avoid silent rollouts and give maintainers clear control over when CI behavior changes.

By the way, with the centralized approach, would updating the workflows still be required when moving from @v1 to @v2? How is this expected to work in practice? Does it mean that we would need to change
- uses: easyscience/actions/setup-pixi@v1
to
- uses: easyscience/actions/setup-pixi@v2
in every workflow that uses this action?

[rozyczko]

By the way, with the centralized approach, would updating the workflows still be required when moving from @v1 to @v2?
Why would we version changes? The whole point of having them in a separate repo is to keep the abstraction layer and avoid updates at every time you change the underlying dependency.

easyscience/actions/setup-pixi would always be v1. Do we really need to advertise that our internal setup-pixi changed because underlying refix-dev/setup-pixi bumped its version?

[AndrewSazonov]

What I mainly wanted to clarify, since you mentioned a pinned version (@v1) earlier, is how version changes are expected to work in practice.

If easyscience/actions/setup-pixi is always meant to stay at v1, then why mention the version at all? In that case, it’s effectively the same as always using uses: easyscience/actions/setup-pixi and only bumping the version of the underlying third-party action (e.g. prefix-dev/setup-pixi) inside our composite action.

If that’s the idea, then this point is clear to me, and I believe that versioning our own composite actions doesn’t add much value and only adds extra complexity.

That said, my other concerns still remain - mainly around transparency and explicit updates versus silent changes.

[rozyczko]

How do you test changes to composite actions before they propagate to all projects?
With a separate repo, we can test against a branch.
With templates, we need a "test project" that runs copier update from a branch, so the process is more complex.

[AndrewSazonov]

We don’t necessarily need a special “test project”. Updating templates in a real project already follows the same safe workflow: create a branch, run copier update, check CI results, and then open a PR to develop. This gives a clear place to test and review the changes.

In addition, I already have a dedicated test repository where all templates are validated before release — not only the composite actions, but the full generated workflows that use them. New template changes can be tested there against feature, develop, or master branches using Copier itself.

So in practice, composite action changes are tested both in isolation (via the test repo) and in real projects before they are merged, without needing silent propagation.

[rozyczko]

Good.

Testing in a branch → run copier update → check CI → PR to develop

sounds like a legitimate testing strategy.

However, the test repo should be documented in the ADR.
If the testing strategy depends on this repo existing, that's part of the decision's context.
The ADR should reference easyscience\peasy explicitly so future maintainers know the expected workflow.

[AndrewSazonov]

I can definitely add a reference to the test repo in the ADR - no problem. I just want to clarify that it’s an additional safety layer, not a strict requirement for the workflow to work.

In practice, composite-action changes can already be tested safely without a dedicated test repo. For example: after updating actions in the templates repository (say in a bump-pixi-version branch), one can go to a real project, create a feature branch (e.g. update-templates), apply the updated templates using

pixi run copier-copy --vcs-ref=bump-pixi-version,

and let CI run. If everything looks good, the templates change can then be merged and released. After that, projects only need a normal pixi run copier-copy without specifying --vcs-ref.

That said, having dedicated test repositories (e.g. peasy, peasy-lib, peasy-app) is very useful for more realistic end-to-end testing - especially for workflows that only trigger on master or on tag creation. If something breaks there, I prefer to catch and fix it in a test repo rather than in a real production project.

So the test repositories are helpful regardless of whether composite actions live in a separate repo or inside the templates.