Repository navigation
Setup guide for use with Gitlab #666
Description
Please describe your problem. Include links to any relevant pages or files.
E.g. #659
Docs are heavily oriented towards use with GitHub - should have a dedicated page for help setting up with Gitlab (what configuration needs to be set etc).
A nice-to-have would be a "how to use in Gitlab CI" page with similar content to the advice provided for use in GitHub Actions but this can be a separate issue
Activity
BastLast commentedon Sep 21, 2023
Just finished a complete setup on a self-managed instance of gitlab anc I can confirm that working with the current documentation has been a challenge. Most of the answer are available deep in github issues comments but it would be awesome to have a better support.
rdbisme commentedon Sep 29, 2023
@BastLast is your changelog complete? When I run on the pipeline, I get only few commits (while locally it runs for long time). I tried setting
GIT_DEPTH: 0orGIT_STRATEGY: clonebut I still get partial results.BastLast commentedon Sep 29, 2023
Mine was complete after changing those settings
rdbisme commentedon Sep 29, 2023
@BastLast any chance I could get a snippet of the steps you're doing in the
script? I want to check if I'm missing something.BastLast commentedon Sep 29, 2023
semantic-release:
stage: release
image:
name: python:3.10.0
entrypoint: [""]
variables:
GIT_STRATEGY: clone
tags:
- docker
script:
- git config --global user.email $GIT_mail
- git config --global user.name $GIT_username
- git remote set-url origin https://$GIT_username:$GL_TOKEN@repourl
- git checkout main
- python -m pip --no-cache-dir install poetry twine
- poetry config (artifactory authentication)
- poetry install
- poetry run semantic-release version
- poetry run poetry build
- twine upload
rdbisme commentedon Sep 29, 2023
Thanks this worked. I'll try to see if I can PR some documentation!
codejedi365 commentedon Dec 9, 2023
I have a working example in GitLab now, I'll start working on a PR
jeffcpullen commentedon Dec 21, 2024
@codejedi365 I know this was a really old comment, but curious if you still use/have that example for Gitlab.
codejedi365 commentedon Dec 21, 2024
Recommend reviewing the comments and examples I had on #1046. I've been meaning to get this to resolution but was working a lot of other resolutions after becoming the primary maintainer. Every time I look into this, there is just a lot of nuance to set up GitLab with the token permissions system being different than GitHub.
Hopefully can knock this out over the holidays.
jeffcpullen commentedon Dec 21, 2024
Much appreciated. I feel you on the nuance with Gitlab. FWIW, if you take a first pass I can help test, refine and document.
10 remaining items
kolumdium commentedon Jun 7, 2025
I made a minimal working example on gitlab ci.
https://gitlab.com/kolumdium/python-semantic-release-gitlab-example
Feel free to use that for the official documentation as needed.
github-actions commentedon Sep 7, 2025
It has been 90 days since the last update on this confirmed issue. @python-semantic-release/team can you provide an update on the status of this issue?
codejedi365 commentedon Sep 8, 2025
Will be published with #1098.
Ferdinanddb commentedon Nov 14, 2025
Hi there,
Any news on this please?
Thank you for your work!
UnoYakshi commentedon Dec 9, 2025
@jeffcpullen, have you managed to auto-deploy by release/tag? The ones PSR creates via git commits.
jeffcpullen commentedon Dec 9, 2025
Not sure I understand the question. I handle all the deployment steps separately from releasing and tagging using standard Gitlab CI workflow rules.
For example, the sample code I included above was used for generating a container image. So PSR runs on updates to the main branch to parse the commits, generate a changelog and store the new version number as a variable for follow up jobs. These follow up jobs are my "deployment" where the containers are built, tagged with the new version and pushed to a registry.
It might be possible to bundle that logic into some build script that PSR calls, I don't know. In my opinion it would be harder to maintain and troubleshoot going that way. Instead I went with Gitlab CI jobs for the "deployment" steps that handle all the deployment steps separately when PSR succeeds. That lets me reuse the PSR Gitlab Ci job across multiple projects that have very different deployment strategies.
UnoYakshi commentedon Dec 10, 2025
@jeffcpullen, yeah, you got the question just right. And thanks for the quick reply! Allow me to elaborate the context a little bit.
Context / Situation
Notes:
As you said, generating a tag and a release should be a separate job from deployment. True. However, we can't deploy our application in the very same pipeline, because a git commit with an updated version (
pyproject.tomlor wherever) is not associated with the current pipeline's execution. Hence, we need to create a separate pipeline. Say, tag-only deployment pipeline. All's good so far. However, we now come across another problem: what if our new build is not assigned a new tag (and a new release is not created), but we still want to deploy it? For example, it's aperforchore(dependencies?) update, and notfeat,fix, or breaking.I'd like to know others' experience on this matter.
Solutions?
I came to several "solutions":
perf,chore, etc. to SemVer as bumping a patch (the 3-rd number) version?0.3.0=>0.3.1. Simple, but something doesn't feel quite right. More of a ductape solution, really.semantic-release versionstep, then we can safely deploy in the same pipeline in one of the next jobs. If a new tag IS created, however, we deploy it in a separate, tag-pipeline. [This is the solution I'm leaning to as of right now.]In the end, it does come to whatever your project needs. But I'd like to know common/accepted practices on GitLab CD matter.
jeffcpullen commentedon Dec 10, 2025
I can't claim any authority in what is the "best" solution, and it always depends on the situation. I have had the same questions / concerns.
Having a guarantee of some version bump simplifies the pipeline code and logic. I opened an issue here #1293 because the default bump level functionality is broken. I personally think there are use cases where this simple solution makes sense, but not everyone agrees.
This style of solution is where I tend to land. The type and location of a commit determine the deployment / tagging strategy. The specific criteria will depend on your team organization, business needs, etc.
Example for one of the projects I setup. Here we were using a trunk based development workflow where devs would fork and open a merge request back to the Main branch. Every update to their fork would run the pipeline to deploy and test a version of their code. Once their MR was accepted and merged into Main, a larger pipeline would kick in to update the higher environments. When we were ready to ship a release we'd manually create it in Gitlab to kick off the production deployment pipeline.
UnoYakshi commentedon Dec 11, 2025
It does simplify, indeed. However, I don't think it's how regular versions (w/o release candidates, alphas, etc.) in SemVer work. In fact, I didn't even expected to have
default_level_bumpin SemVer-related library. Until yesterday, I didn't even knew it exists in PSR. Don't get me wrong, I'm no way a guru of versioning, not at all. But I think it'd be misleading to bump even a patch number/version because of somestyleorchorecommit. Even more, what if there are multiple of those? Should we raise the version several times? I'm leaning to reply "Nope".P.S. I don't really like SemVer myself for a bunch of reasons (and that's another topic), but it's widely spread, and it is better than nothing (or plain git commit hashes). And going against the current in the so called "standard" is not something I'd gladly sent maintainers to get with to. It'd probably be more healthy to just drink tea than to have a debate on this matter.
P.P.S. If you are up to a debate, I'm all for it, TBH.
Wait, don't you tag your code for dev-environment anyhow? My main use case with PSR was to relieve me from the burden of making regular tags altogether. And to have a correct version of my module in OpenAPI specification. Otherwise, I could simply forget where we are at.
This is how I interpreted your example. My current pipeline is somewhat similar, to be frank. Except for I definitely want to utilize PSR for dev-deployment w/o
--noop. Not sure if that's the right way to do it, but it certainly helps me during development cycle AND my brain likes the "number goes up" game (helps motivation, I guess).--- title: jeffcpullen's glorious meta-pipeline --- flowchart TD main["fork `main`"] --> feature[" `feat` branch"] feature --> MR["open WIP MR back to `main`"] feature --> update["update `feature` branch"] update --> dev-pipeline["run pipeline to dev-deploy + test (unit/E2E?)"] MR --> merge[" merge `feat` to `main`"] merge --> preprod-pipeline["pre-production pipeline kicks in"] preprod-pipeline --> time["some time passes, e.g., code freeze"] time --> release["add release via PSR or GitLab directly"] release --> release-pipeline["tag/release-only pipeline deploys on production"]github-actions commentedon Mar 12, 2026
It has been 90 days since the last update on this confirmed issue. @python-semantic-release/team can you provide an update on the status of this issue?