DR Preparation: #repos for common workflows

[AlexanderLanin]

Warning

⚠️ Judging from the comments so far, this is not self explanatory. We'll address it in the next infrastructure meeting ⚠️

Alternatives

Option A: One common repository

cicd-workflows

Pros:

• Single, central discovery point for all reusable workflows and composite actions
• Unified versioning of the CI/CD building blocks
• Consistent structure and conventions across all workflows
• Centralized governance and review processes
• Easier to reference in process documentation and audits
• Simplified archiving and lifecycle management
• Clear “known-good” baseline for consumers

Cons:

• Coupled lifecycle: unrelated workflows share the same release cadence
  • A release for workflow A also ships workflow B, even if B is mid-refactoring
• Churn/noise: unrelated changes trigger notifications, PR reviews, and mental overhead for maintainers (even with dependabot)
• Versioning problems: a patch in one workflow, and a major change in another result in a major change overall (bad in itself). Even worse when the person creating the version does not know about the second workflow and creates only a patch release.
• Backwards compatibility: due to frequent version increases, no meaningful info on backwards compatibility via SemVer
• Some github features simply do not work as intended

Option A2: One common repository with multiple independently versioned “topics”

All workflows and actions live in a single repository, but are grouped into independently versioned domains
(e.g. docs-1.0.5, build-2.3.7, compliance-0.9.2).

Intended benefit:

• Preserve SemVer meaning per topic while keeping a single repository
• Reduce some of the lifecycle coupling issues of Option A

Challenges / Risks:

• GitHub does not natively support multiple independently versioned packages within one repository
• Requires custom conventions, tooling, and discipline
• Consumers still reference the same repository, leading to ambiguity and confusion (could simply be familiarity, but this is not a common pattern on GitHub)

Option B: Individual repositories

apt-install, dash-license-scan, …

Pros:

• Aligns with GitHub’s intended usage and documentation model
• Independent versioning per workflow or action
• Better support for extracting logic into scripts or tools, see src
• Reduced coupling between unrelated CI/CD building blocks, lower impact radius for changes and releases
• Naturally supports tool-owned workflows (e.g. a CLI exposing a convenience workflow), e.g. https://github.com/eclipse-score/dash-license-scan/tree/dev
• Scales better as the number of workflows and actions grows

Cons:

• Discoverability problem: without a strong index/catalog, teams reinvent or copy/paste
• Inconsistent conventions: naming, inputs/outputs, docs quality, ... drift over time
• Duplicated overhead: repo bootstrap, settings, branch protection, releases, scanning, templates
• Inter-dependency pain: if workflows/actions build on each other, you can end up with a dependency graph across repos
• Increased number of repositories to manage (although 0 effort due to otterdog)

---

Use-Case discussion

As the above has valid Pros and Cons and no clear winner, let's try to define it based on use cases

Use case	Description	Structuring rule	Notes / Example	Option
JavaScript action	Action implemented in JavaScript using action.yml	Must be a standalone repository	Required by GitHub; cannot be embedded in workflow repos	B (dedicated single repo)
Composite action (internal)	Composite action that exists solely to structure a single workflow	Co-locate with the workflow it belongs to	Implementation detail, not a reusable building block	covered by 'Complex Workflow' row
Composite action (reused)	Composite action reused across multiple workflows or repos	Independent repository with its own lifecycle	Clear SemVer and ownership; avoid implicit coupling	Start with A. See below.
Tool providing CI integration	CLI or tool that exposes a workflow for convenient CI usage	Tool owns the workflow as a thin adapter. Workflow/Action lifecycle/versioning makes sense in-sync with the tool.	Workflow is secondary; versioned with the tool (e.g. dash-license-scan)	B (dedicated tool repo)
Simple reusable workflow	Small, focused workflow reused across multiple repositories	Single logical unit with independent lifecycle. Same as 'Composite action (reused)' row.	Avoid bundling with unrelated workflows	Start with A. See below.
Complex workflow	Workflow decomposed into multiple actions and helper scripts	Keep workflow and all internal actions together	One logical unit, one lifecycle, one owner	B single dedicated repo (together with sub-workflows/actions) - start with A!
Experimental workflow	POC, Early-stage or fast-changing workflow	Isolate to minimize churn and blast radius	Avoid affecting stable consumers	branch in A (shared repo)

---

Conclusion / Summary DRAFT

We use A!

We will split the existing workflows between "official entry points" and "internal steps".

Some exceptions have already been identified:

• JavaScript actions
• Tool-Repo providing its own CI integration
• General purpose reusable actions are a case by case decision, e.g. apt-install

The biggest/only con of A is the shared lifecycle of all workflows. Versioning (SemVer) will be defined by the official entry points. However that only hurts, when the churn becomes too big (see problem statement). Once we reach that point, we will discuss A2 or B.

[MTomBosch]

Another small con for one repo. When one composite action uses another one from the same repo then some special handling must be implemented so that the calling composite action gets exactly the called action based on the commit from the calling actions Git repo checkout.

[AlexanderLanin]

We did not figure out any solution to that in eclipse-score/cicd-workflows#18 (comment)

Only by adding id-token permission everywhere this seems possible.

[MTomBosch]

At least it seems to be a "working" workaround although it is not nice looking (but still acceptable imho).

[FScholPer]

I would also add as con of option B that this would largely increase the amount of repositories

[MTomBosch]

Not really a pro but proven in use: We had one repo that included everything (workflow files and bash scripts).
Wrt to versioning we did not have one tag for the whole repo but "topic" tags based on SemVer. As topics we would be using

• every "public" reusable workflow
• one version for all or multiple composite actions

For every such version tag we guaranteed that the related files can work together.
Although the effort for setting the tags was quite big at the beginning (until we added automation) the reduced maintenance (only one Git repo) and automatic consistency and easier integration testing was really a huge benefit.

[MTomBosch]

And in addition every version tag in Git was available three times. Once only the major version, then major.minor and last major.minor.patch.
This way the reuse via major.minor allows to get patch updates automatically (when replacing the 11.12 tag by the latest 11.12.x commit, e.g. 11.12.5).

In case we consider such an approach then maybe we should split up Option A into A1 (one version tag for whole repo) and A2 (one version tag for dedicated parts of the repo).

[dcalavrezo-qorix]

I'll go for option A ( with all its cons) due to one main reason: conformity

[MaximilianSoerenPollak]

I like option B thematically, as the workflow is in the repository it belongs to.
Though this makes it more difficult to see which workflows are available and how to use them etc.
So I can also see the benefits of A in that regard.

[TimofteBogdan1900]

Option B looks more logical & honest to me

[anmittag]

Why do we need individual workflows?

I assume for "certifiable" we have to stick to same way of working in each and every "Feature-Repos"

How do we deal with Infrastructure, Process, Integration Repos?

So I prefer A) and the MUST for all using the same. Mid-refactoring shall be done on a branch.

Backward-compatibility: not really needed (?), from my point of view we have to link workflows with releases to be able to reproduce.