Cookiecutter PyPackage GitLab

Cookiecutter template for a Python package in the GitLab CI/CD ecosystem.

Project links

• PyPI: https://pypi.org/project/cookiecutter-pypackage-gitlab/
• Documentation: https://sck.gitlab.io/cookiecutter-pypackage-gitlab/
• Source & issues: https://gitlab.com/sck/cookiecutter-pypackage-gitlab

Features

• Dependency management with uv
• Task running with make
• Testing with pytest under GitLab CI
• Auto-publish to a package registry when you push a v* tag. (For PyPI no API tokens are needed by using Trusted Publishers.)
• Hardened GitLab CI workflows: version-pinned Docker images
• Documentation site built with Zensical and auto-deployed to GitLab Pages.
• Linting with ruff, type checking with mypy and ty
• Command line interface using argparse

Quickstart

Generate a new Python package by creating a temporary venv, installing the package, and running the command.

python -m venv venv
source venv/bin/activate
pip install cookiecutter-pypackage-gitlab
cookiecutter-pypackage-gitlab

If you have uvx installed, you can also use it to run cookiecutter-pypackage-gitlab without explicitly creating a temporary venv, installing the package, running the package, and then removing the temporary venv:

uvx cookiecutter-pypackage-gitlab

You'll be prompted for your project's values (name, description, author details, GitLab repository URL, publish registry, and so on). See docs/prompts.md for the full list and what each value controls.

Then:

• Review src/ and tests/; see tutorial Step 7 for what to adapt or delete.
• Create a GitLab repo and push your code
• Enable GitLab Pages: Settings > Pages > Source: GitLab CI
• Set up your selected package registry (see Registry setup -- covers GitLab Package Registry, PyPI Trusted Publishing, and TestPyPI for dry runs).
• Release your package: see Release checklist for the workflow.

See the full documentation for the tutorial, CI/CD reference, design notes, and more.

Development

To set up for local development:

git clone git@gitlab.com:sck/cookiecutter-pypackage-gitlab.git
cd cookiecutter-pypackage-gitlab
make venv
source venv/bin/activate
make init
make sync-devci

Run quality checks (format, lint, type check, test):

make qa

Watch the template for changes and auto-regenerate python-boilerplate/ in the repo root (useful when iterating on template files):

make template-watch

Release cycle

1. Edit code and add change notes to the Next release (TBD) entry in HISTORY.md as you go.

2. When ready to release, upgrade all dependencies and refresh the environment:

   make update
   make sync-devci
   

3. Run the full quality check suite:

   make qa
   

4. In HISTORY.md, replace the Next release (TBD) heading with the release version and today's date, and verify the change notes are complete.

5. Sync the version to pyproject.toml and uv.lock:

   make set-version
   

6. Commit the release:

   git commit -am "Release X.Y.Z"
   

7. Tag and push. make tag validates version consistency across HISTORY.md, pyproject.toml, and uv.lock; creates an annotated tag; pushes it to origin; and adds a new Next release (TBD) entry to HISTORY.md:

   make tag
   

   Pushing the tag triggers the GitLab CI/CD publish job, which uploads the package to your selected registry.

8. Commit to open the next development cycle:

   git commit -am "Start next development cycle"
   

9. Go back to step 1.

See also Release checklist for registry-specific publishing notes and troubleshooting.

Not exactly what you want?

Don't worry, you have options:

Fork this / Create your own

If you have differences in your preferred setup, I encourage you to fork this to create your own version. Or create your own; it doesn't strictly have to be a fork.

Similar Cookiecutter templates

This cookiecutter template was based on the v0.4.0 (2026-02-16) release of Cookiecutter PyPackage (a GitHub-centric template). That package lists other forks you can explore to get ideas at network and family tree.

Or submit a merge request

I also accept merge requests on this, if they're small, atomic, follow my design decisions, and if they make my own packaging experience better.

License

MIT.