How to version a GitLab CI template library so that teams are not broken during updates?

For versioning the GitLab CI template library, it is recommended to use tags and semantic versioning (SemVer).

1. Create releases with tags in the template repository, for example, v1.0.0, v1.1.0.
2. In the .gitlab-ci.yml files, specify the exact template version when importing:

include:
  - project: 'group/project-templates'
    ref: 'v1.0.0'
    file: '/templates/.gitlab-ci-template.yml'

3. This ensures that when templates are updated, teams will not receive unexpected changes unless they explicitly update the version.

4. For a smooth transition, patches and minor versions can be released, and teams can gradually update links to new versions.