Simplify your DevOps life using GitLab Components
What is a component?
So, your team started using GitLab, be it self-managed, dedicated, or even on gitlab.com. You started writing CI/CD for all your repositories, and as a lot of places suggest, created a dedicated repository for it, referenced by other repositories as a template. However, you’re starting to encounter some issues. Documenting the whole repository is a hassle, as well as discovery. You have to maintain proper wiki pages for it, and someone needs to own them and update them. The task is tedious, and not handled the best.
GitLab components simplify all of this. Generally introduced in GitLab 17.0, components allow you to have a catalog of CI/CD components readily and easily available for use in any repository of your organization.
“But wait!” you tell me, “We already wrote all of those CI/CD pipelines, why would we bother rewriting everything to a new system? This takes time, effort, and we will need to document everything again”.
That’s where the magic of GitLab Components comes in: The modifications of your existing CI/CD pipelines is minimal.
Your first component
Let’s consider the following CI/CD template: Let’s say you want to build a .NET 9 application, then publish the binaries to the internal GitLab NuGET repository:
.nuget:publish:
stage: publish
image: mcr.microsoft.com/dotnet/sdk:9.0
only:
- tags
- $FORCE_PUBLISH == "true"
script:
- dotnet pack -c release
- dotnet nuget add source
"${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/nuget/index.json" --name gitlab --username gitlab-ci-token --password $CI_JOB_TOKEN --store-password-in-clear-text
- dotnet nuget push "**/bin/Release/*.nupkg" --source gitlab
To be quick about it, if a tag is published or the FORCE_PUBLISH variable is set to “true”, the pipeline will pack the project, add the GitLab NuGET repository, and push the packed data to it.
Now, converting this pipeline to a component is really easy. A component needs only a few things:
- A repository in which it will live.
- A CI/CD configuration file that will publish the component.
- A README file containing a basic description of what the component is doing.
- A basic project description (on the repository).
- Lastly, the “CI/CD Catalog project” in the repository settings turned on.
With all of this in mind, let’s create our first component! Let’s start with the easiest: The CI/CD script publishing our component.
stages:
- release
release:
stage: release
rules:
- if: $CI_COMMIT_TAG
image: registry.gitlab.com/gitlab-org/release-cli:v0.18.0
script:
- echo "Creating release"
release:
tag_name: $CI_COMMIT_TAG
description: './README.md'
This pipeline configuration just looks for tags, then if one is published, it creates a release with the README as a description. Really, that’s all you need. When we get at that, GitLab will handle generating more documentation and publishing on its own.
Now, in the README.md file, we can just add a simple description such as:
“Component that publishes a .NET 9 project to the NuGET registry.”
Now that we have most of our pre-requisites done, let’s convert the actual pipeline. For this, we’ll need to create a “templates” directory in the repository, in which we can create a new file called “publish.yml.”This is where the real magic happens. Components allow you to specify a specification before the template itself, allowing you to set descriptions and what inputs the template expects. GitLab will use those inputs and their descriptions to generate basic documentation of the template in question.
For instance, in our case, it will look fairly simple, with only two inputs: Do we want to force publishing or override the stage of the pipeline? This would look a bit like this:
spec:
inputs:
stage:
default: publish
description: 'Defines which build stage will be used.'
force-publish:
default: false
description: 'Do you want to force the publishing of the NuGET package.'
After this, our last step is to modify our template to use those inputs instead of environment variables. This is also really trivial and will look something like this:
"publish-nuget-package":
stage: $[[ inputs.stage ]]
image: mcr.microsoft.com/dotnet/sdk:9.0
only:
- tags
- $[[ inputs.force-publish ]] == "true"
script:
- dotnet pack -c release
- dotnet nuget add source
"${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/nuget/index.json" --name gitlab --username gitlab-ci-token --password $CI_JOB_TOKEN --store-password-in-clear-text
- dotnet nuget push "**/bin/Release/*.nupkg" --source gitlab
Notice how instead of using $FORCE_PUBLISH, we instead use $[[ input.force-publish ]].
We can then combine the two to give us our full template, which contains the spec and the pipeline itself:
spec:
inputs:
stage:
default: publish
description: 'Defines which build stage will be used.'
force-publish:
default: false
description: 'Do you want to force the publishing of the NuGET package.'
---
"publish-nuget-package":
stage: $[[ inputs.stage ]]
image: mcr.microsoft.com/dotnet/sdk:9.0
only:
- tags
- $[[ inputs.force-publish ]] == "true"
script:
- dotnet pack -c release
- dotnet nuget add source
"${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/nuget/index.json" --name gitlab --username gitlab-ci-token --password $CI_JOB_TOKEN --store-password-in-clear-text
- dotnet nuget push "**/bin/Release/*.nupkg" --source gitlab
Voilà! You now have a working GitLab Component. Remember to tag it at least once to create a usable version, such as 1.1.0.
Once the workflow of the tag pipeline is finished, you can now click on the blue CI/CD Catalog pill on top of the repository to see its Catalog page. There, you will see a way to include the specific version workflow and some generated documentation of its options.
For instance, to use this component, all you need to do is include it in your CI file:
include:
- component: $CI_SERVER_FQDN/components/example-comp/publish@1.0.0
inputs:
stage: deploy
force-publish: false
Note: Notice how the variables are passed through the “input” property.
Closing thoughts
In the end, GitLab Components are an easy way to have discoverable and documented CI/CD templates on your GitLab instance. Not only are they easy to create from scratch, but they can also be based on existing pipelines.
You can find all published components on your GitLab instance in the “Explore”, then “CI/CD Catalog” view.
Published:
