How to properly version reusable workflows?

[nascit]

One of the big advantages I see on the reusable workflows feature is the ability to centralize them all into a single repository. This enables different teams to collaborate and build workflows that can fit different scenarios. However, versioning plays a big importance in this case as I want to make sure new changes in a reusable workflow won't affect my caller workflow.

In this scenario, what approach are teams taking to version specific workflows that belong to a central reusable workflow repository?

[airtower-luna]

Considering that you call reusable workflows in another repository by ref, using tags seems natural (just like for custom actions). Possibly major version branches, with the same caveats as for actions.

[nascit]

Thanks for you answer!
Tagging seems the obvius answer, but how would you tag/version a single reusable workflow in a centralized repository hosting multiple different reusable workflows?
Basically this is the same question as what's the best approach to tag/version a application in a monorepo.

I was thinking to follow this approach:

reusable-workflow-1/1.0.0
reusable-workflow-1/1.0.1
...
reusable-workflow-2/1.0.0
reusable-workflow-2/1.1.0
...

The only downside I see is a bit of duplication when referencing the reusable workflow:

uses: ORG-NAME/reusable-workflows/.github/workflows/reusable-workflow-1.yml@reusable-workflow-1/1.0.0

[airtower-luna]

That should work, yes. Though I can't help but wonder: Why do you want to have the workflows in one repository if they're independent enough of each other that separate versioning makes sense? 🤔

[nascit]

Different than an action, a reusable workflow is a single YAML file. It seems to me a overkill to create one repo per reusable workflow.

If many dev teams are using the same set of reusable workflows, a central repository hosting all reusable workflows seems to be obvious solution in my mind to avoid code duplication and make it easy to find workflows and collaborate.

As reusable workflows is a relatively recent feature, we might not have a pattern yet. I'm curious if @github-staff has a official recomendation.

[nascit]

Any suggestions from @github-staff ?

[mmelodyRTR]

Hey @github-staff, is there recommended best practices we could follow for versioning reusable workflows?

My use-case is similar to @nascit above - a single repository storing my orgs reusable workflows, but having the ability to version them each individually, which in turn allows me to use Dependabot to trigger updates for consumers of those workflows when they're updated.

Having a repo per workflow seems like overkill. I also like the idea of a central repository so that I can drive at documentation which is generated from its contents.

[Abdullah-Siddique]

Properly versioning reusable workflows is essential for maintaining stability, compatibility, and ease of management in your CI/CD pipelines. Here’s how to do it effectively:

1. Adopt Semantic Versioning

Major Version: Increase for breaking changes or incompatible updates.
Minor Version: Increase for new, backward-compatible features or improvements.
Patch Version: Increase for backward-compatible fixes or minor updates.
Example: v1.2.3 (where 1 is the major version, 2 is the minor version, and 3 is the patch version).

2. Tag Your Releases

Use Git tags to mark specific versions of your workflow files. This creates a clear reference point for each version.

git tag -a v1.0.0 -m "Initial release of reusable workflow"
git push origin v1.0.0

3. Include Version Information in Workflow Files

Document the version directly in the workflow YAML file to ensure clarity. Add a version key or include version information in comments.

name: My Reusable Workflow
version: 1.0.0

4. Maintain a Changelog

Document changes and updates in a changelog to provide transparency about modifications and their impacts.
Example Changelog Entry:
**## [1.0.1] - 2024-09-15

Fixed

• Corrected bug in environment setup**

5. Deprecate Older Versions Thoughtfully

Clearly communicate deprecation of older versions and provide guidance on transitioning to new versions.
Consider adding deprecation notices in your workflow files.

6. Reference Versions Explicitly

When using a reusable workflow, specify the version tag to ensure consistency and avoid unintentional updates.