blaise-blog/releasing: gitlab to pypi

This post contains my notes for how I release a Python project from GitLab to PyPI. I love hosting projects on GitLab since I can use the built-in runners to release automatically.

table of contents

first release

The very first release is necessarily a very manual process. Once the project is on PyPI, subsequent releases can be automated.

test packaging

First, you want to make sure that your source code is correct. There are a lot of little regretable mistakes to be made.

• python setup.py sdist bdist_wheel
• open dist\<package>.tar.gz
• ensure that LICENSE is packaged
• ensure that VERSION is correct
• ensure that CHANGELOG is correct
• ensure that PKG-INFO is correct

tag on GitLab

• New Tag
• Tag name should start with v, e.g. v0.1.0, v2020.05.0
• under release notes: release [version](link-to-changelog)

If you already have gitlab-ci setup to release on tag, it will try and surely fail. That's OK for this initail release. You can cancel it, if you think to.

release on PyPI

Now we actually release to PyPI.

• rm -rf dist
• python setup.py sdist bdist_wheel
• twine upload dist/*

Horray! Don't forget to log into PyPI and make other project maintainers into "owners".

gitlab-ci

In this section we will set up gitlab-ci to automatically release everytime a new tag is made.

add release to ci

In .gitlab-ci.yml:

twine:
  stage: deploy
  script:
    - python setup.py sdist bdist_wheel
    - twine upload dist/*
  artifacts:
    paths:
      - dist/*
  only:
    - tags

protect tags

Within the GitLab repository, we must mark tags that we intend to release as protected. This is intended as a safety feature so that only maintainers are able to release. On GitLab:

• Settings > Repository
• Protected Tags
• Create wildcard v*
• Allowed to create: Maintainers
• Protect

add variables

PyPI allows uploads via tokens. This is how we will authenticate and let PyPI know that we are who we say we are. First, we need to generate the token. On PyPI:

• Account
• API tokens
• Create token gitlab-<project>, scope only for project

On GitLab:

• Settings > CI/CD
• Variables > Add Variable
• (make sure variables are protected)
• key TWINE_PASSWORD value pypi-<TOKEN>
• key TWINE_USERNAME value __token__

subsequent releases

On subsequent releases gitlab should release for you on tag.

• update CHANGELOG
• update VERSION
• tag
• watch ci release for you

built 2025-11-17 08:00:39