cookiecutter-pypackage-gitlab 0.1.0

Cookiecutter template for a Python package in the GitLab ecosystem

Cookiecutter PyPackage GitLab

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

• GitLab repo: https://gitlab.com/sck/cookiecutter-pypackage-gitlab/
• Free software: MIT license

Features

• Dependency management with uv
• Task running with make
• Testing with pytest under GitLab CI
• Auto-publish to package repository 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 some values:

[1/14] Project name for documentation (spaces allowed) (Python Boilerplate): My Package
[2/14] Project short description for pyproject.toml and docs (Python Boilerplate contains all the boilerplate you need to create a Python package in the GitLab ecosystem.): A short description of your package.
[3/14] Initial version string for the package (0.0.0):
[4/14] Author full name (Scott Karlin): Your Name
[5/14] Author email ([e-mail]): [e-mail]
[6/14] Author GitLab username (sck): your-gitlab-username
[7/14] Author website (https://gitlab.com/your-gitlab-username):
[8/14] PyPI Package Name for pip install (no spaces; recommend normalized form) (my-package):
[9/14] GitLab repository URL for this project. (https://gitlab.com/your-gitlab-username/my-package):
[10/14] Display name of the project in GitLab (my-package):
[11/14] Python import package name (my_package):
[12/14] Target package registry: "pypi" to publish to PyPI or "gitlab" to publish to your GitLab project's package registry (gitlab):
[13/14] PyPI username (required when publish_registry is "pypi") ():
[14/14] The name of the local repo directory (my-package):

Then:

• Create a GitLab repo and push your code
• Enable GitLab Pages: Settings > Pages > Source: GitLab CI
• Set up PyPI Trusted Publishing for your repo
• 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 [e-mail]:sck/cookiecutter-pypackage-gitlab.git
cd cookiecutter-pypackage-gitlab
make venv
source venv/bin/activate
make init
make uv.lock
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.