Skip to main content

ITW Python Builder

Standardized Django and Angular deployment pipeline with Docker, testing, SonarQube integration, automatic changelog generation, GitLab issue creation, and code quality enforcement.

Features

  • Automated deployment with semantic versioning
  • Docker/Podman-based build and push pipeline (backend)
  • Angular build, packaging and upload to the GitLab Package Registry (frontend)
  • Angular SSR scaffolding and SSR builds
  • Automated testing with coverage
  • SonarQube static code analysis
  • Pylint linting with SonarQube integration
  • Quality gates - deploy only when tests pass
  • Automatic changelog generation from commit trailers
  • Automatic CHANGELOG.md creation and propagation to staging/develop
  • GitLab issue creation from a markdown file
  • Cached GitLab authentication
  • Support for local and production pipelines
  • Global CLI tool
  • Automatic venv detection per project

Installation

pip install itw-python-builder

Install globally (outside any project venv). The itw command becomes available system-wide.

Check the installed version:

itw --version

Quick Start

  1. Navigate to your project directory (Django projects must have a .venv or venv):

  2. Authenticate with GitLab:

itw login
  1. Initialize versioning — run it on staging first, then on master:
git checkout staging && itw tag-init   # creates v.0.0.1-rc1
git checkout master  && itw tag-init   # promotes the latest staging RC to -release
  1. Run local pipeline:
itw pipelinelocal
  1. Deploy to staging:
itw incrementrc
  1. Deploy to production:
itw incrementpatch

Available Commands

Deployment Commands

  • itw incrementpatch — Increment patch version and deploy
  • itw incrementminor — Increment minor version and deploy
  • itw incrementmajor — Increment major version and deploy
  • itw incrementrc — Increment release candidate (staging)
  • itw release — Promote RC to stable release (master)

Timesheet Reporting for Frontend Releases

Pass -tm to any deployment command to report a merge request to Timesheet after a successful build and publication:

# Find a specific MR number merged today in the current GitLab group
itw incrementpatch -tm 110

# Choose from today's merged MRs in the terminal
itw incrementrc -tm

--tm and --tm=110 are also supported. The option is available on incrementrc, incrementpatch, incrementminor, incrementmajor and release, for frontend projects on their allowed staging/master branches. Backend projects reject it before authentication or release work.

The current group is the full namespace of the origin repository; the search includes its subgroups and all accessible projects, including backend repositories. It uses the existing GitLab login and matches merged_at against today's calendar day in the local timezone. The number is the project-local MR number shown in GitLab, such as !110. If that number matches several repositories, you must choose one. Without a number, you must choose from the listed MRs even when only one is available. An interactive selection requires a terminal; a unique explicit number works without one. No matching MR stops the release with a message naming the number and group.

Configure Timesheet in the builder's root .env:

TIMESHEET_REPORT_URL=https://tm.it-works.io/api/qa-issue-from-merge-request/
QA_ISSUE_API_KEY=<shared-api-key>

Both values are required and are read only from the .env in the builder's root, resolved relative to the package location. The project being released and environment variables do not override this configuration.

The merge request is selected before the build. After all selected frontend builds, package uploads, changelog generation and tag push succeed, itw sends one POST to TIMESHEET_REPORT_URL at the end of the shared build/publish pipeline. The request headers are X-Api-Key (the configured API key), Version (for example 1.2.3, without the tag prefix or RC suffix), Merge-Request-Repo (the selected MR's group/project) and Merge-Request-Id (its MR number).

If a build, upload, changelog generation or tag push fails, no Timesheet request is sent. An HTTP error from Timesheet stops the remaining release steps and displays the response's message (or MESSAGE); non-JSON error responses and connection/timeout failures also stop it with their error details. Completed builds, uploads and pushed tags are not rolled back. Reporting is not automatically retried. --skip-pipeline still reports to Timesheet after the build and upload, and SSR or multiple production environments report once per release. Commands without -tm do not search MRs or report to Timesheet.

Authentication Commands

  • itw login — Capture and cache a GitLab token (backend also logs into the container registry)
  • itw logout — Forget the cached token and log out of the container registry

GitLab Issue Commands

  • itw task-init — Create a TASK.md template in the current directory
  • itw task --file=TASK.md — Create GitLab issues from a markdown file

Local Development Commands

  • itw pipelinelocal — Run full local pipeline (lint → test → analyze → build)
  • itw lintlocal — Run pylint with human-readable output
  • itw lint — Run pylint and generate SonarQube report files
  • itw buildlocal — Build Docker image locally
  • itw test — Run tests with coverage
  • itw analyze — Run SonarQube analysis
  • itw changelog — Generate changelog manually
  • itw tag-init — Initialize version tagging (see below)
  • itw ssr-init — Scaffold Angular SSR (one-time, frontend only)

Version Initialization

itw tag-init is branch-aware and must be run from staging or master:

  • On staging it creates the first release candidate, v.0.0.1-rc1.
  • On master it reads the latest -rc tag reachable from staging (local or origin/staging, after fetching tags) and creates that same version as a release. For example v.0.0.2-rc10 on staging becomes v.0.0.2-release on master.

The VERSION file is written with the tag that was created. The command stops with a clear error when there is no staging branch, no release candidate to promote, or when the tag already exists.

Skip Pipeline

itw incrementpatch --skip-pipeline

Run a Subset of Tests

# Django: an app or a single test module
itw test --target=users
itw test --target=users.test_views

# Angular: a directory or a spec name
itw test --target=core
itw test --target=core.service

SSR Builds

On a production frontend deploy (master), itw looks in src/environments for *.prod.ts files. One file keeps the existing build-master script and uploads frontend/<version>/dist.tar.gz. Several files prompt for which one to deploy, with all as the last choice. Each selected environment is built with the matching angular.json configuration, packaged as dist-<environment>.tar.gz, and uploaded before the next one starts, at frontend/<version>/dist-<environment>.tar.gz. The version commit then includes that name, for example version update to v.1.2.3-release (lenslight). Choosing all lists every name: version update to v.1.2.3-release (greenterrace, lenslight).

Frontend projects scaffolded with itw ssr-init build through the SSR npm scripts when --ssr is passed:

itw incrementrc --ssr
itw incrementpatch --ssr

Static Projects

Repos that ship files as they are, with no build, tests or image (for example Keycloak login themes), declare themselves in pyproject.toml:

[tool.itw]
project_type = "static"

For a static project:

  • incrementrc, incrementpatch|minor|major and release run SonarQube, then tag, update the changelog, push the tags and commit VERSION. There are no tests, no lint and no image or package build. CI deploys the files from the tag.
  • pipelinelocal runs only the SonarQube analysis.
  • test, lint and buildlocal skip with a message.

The marker is explicit on purpose: a repo without manage.py or package.json is never treated as static by accident. project_type only accepts "static"; backend and frontend are still detected from their files.

Virtual Environment Detection

itw is installed globally but automatically detects the project's virtual environment (.venv or venv) in the current directory. Tasks that need Python/Django dependencies (test, lint, analyze) activate the venv automatically — no need to manually activate it.

If no venv is found, those tasks will error with a clear message. Tasks that only use git (like changelog, tag-init, buildlocal) work without a venv.

Linting

The pipeline runs pylint automatically on every deployment and generates report files for SonarQube. The .pylintrc configuration is shipped with the package — no config files needed in your project.

# Review issues with human-readable output
itw lintlocal

# Generate report files for SonarQube
itw lint

# Use a custom pylint configuration
itw lint --pylintrc=.pylintrc

Add this to your sonar-project.properties:

sonar.python.pylint.reportPaths=pylint-report.txt

Changelog Generation

Changelog entries are generated automatically on every deployment based on commit messages. To categorize a commit, add a Changelog: trailer to the commit body:

add user authentication

Changelog: added

Available categories: added, fixed, changed, deprecated, removed, security, performance, tests, docs, refactor

Commits without a trailer appear under Other Changes. The CHANGELOG.md file is committed and pushed automatically with each deployment.

If CHANGELOG.md does not exist in the current directory it is created automatically — including when there are no new commits since the last tag, so the deployment never fails on a missing file.

Changelog Propagation

After a successful deployment the changelog is synced forward through a temporary git worktree:

  • from master → staging and develop
  • from staging → develop

Propagation is skipped when the working tree is not clean or when there is nothing new to sync.

GitLab Issue Creation

Create GitLab issues from a markdown file instead of the web UI.

Generate the template:

itw task-init

Then fill it in and run:

itw task --file=TASK.md

task-init refuses to overwrite an existing TASK.md. Without .git in the current directory, repo and milestone stay empty. With .git, it reads the GitLab remote and finds the namespace's _pm repositories. A single repository is selected automatically; several prompt for a selection. Milestones from the selected project and its parent groups follow the same selection rule, and the chosen milestone's available start/end dates are filled in. When no milestones exist, the milestone stays empty and the date placeholders are kept.

Template

/glab_host 
/glab_username 
/glab_token 
/repo 
/milestone 
/milestone-start YYYY-MM-DD
/milestone-end YYYY-MM-DD
/assignee 
## Comment

## Comment

Add a /title <text> line for each issue before running itw task. The parser also supports the optional directives listed below, including /label, /estimate, /due and custom acceptance criteria. Leaving a key empty is allowed — empty keys are simply not sent to GitLab. The date placeholders use YYYY-MM-DD and are treated as empty until you replace them.

Any text outside the directives becomes the issue description. Create several issues from one file by separating the blocks with a line containing only ===.

Directives

Directive Description
/glab_host GitLab host to authenticate against
/glab_username GitLab username
/glab_token GitLab personal access token
/title Issue title (required)
/repo Target project path
/milestone Milestone title
/milestone-start Milestone start date, used only when the milestone is created
/milestone-end Milestone due date, used only when the milestone is created
/assignee Username to assign the issue to
/label Comma-separated labels
/estimate Time estimate (e.g. 3h)
/due Issue due date

Authentication

Either provide all three of /glab_host, /glab_username and /glab_token, or none of them. Providing only some of them is an error.

When no credentials are given, itw uses the .git directory in the current folder to detect the GitLab host and project, and the token cached by itw login.

Target Repository

The first /repo in the file is the file default. Every later block that leaves /repo empty uses that value. A block that sets its own /repo keeps it and does not change the default for the blocks below. Blocks above the first /repo, and a file with no /repo at all, are resolved once by walking the current repository's namespace upward looking for a _pm project. If several are found you are prompted to pick one, and that choice is reused for the remaining issues that still have no repo.

With /repo, leading and trailing slashes are stripped automatically, and full URLs or SSH remotes are accepted:

/repo /tools/itw_python_builder/          → tools/itw_python_builder
/repo https://git.it-works.io/tools/x.git → tools/x
/repo git@git.it-works.io:tools/x.git     → tools/x

Milestones, Labels and Duplicates

Milestones, labels and issue titles are matched with a shared fuzzy comparison at 95% similarity, so small differences in spacing or casing still count as a match. Digit runs must be identical (java 38 does not match java 37). The threshold is a single constant (SIMILARITY_THRESHOLD in task_utils.py) if you need to tune it.

  • Milestone — an existing project or parent-group milestone with the same title is reused; otherwise it is created (with the start/end dates when both are given).
  • Label — a similar existing label is linked and logged in white; a new one is created and logged in green. An empty /label is never sent to GitLab.
  • Duplicate issues — before creating, the target project is searched by title. A similar title is treated as a duplicate and skipped only when the milestone and assignees also match. An empty milestone or assignee matches only an issue where that field is also empty.

Acceptance Criteria and Comments

The ## Acceptance Criteria section must be opened and closed with the same header. When omitted or left with empty checkboxes, a default checklist is applied.

The ## Comment section, opened and closed the same way, is posted as a note on the issue after it is created.

Requirements

  • Python 3.10+
  • Podman
  • Git
  • SonarQube server
  • Node.js and npm (frontend projects)

Configuration

Environment Variables

Add to your project .env:

SONAR_HOST_URL=https://your-sonar-server
SONAR_TOKEN=your-token
GIT_DEPTH=0

Project Files Required

  • Git repository with develop, staging, and master branches
  • VERSION file in project root (backend, static) or package.json (frontend)
  • Dockerfile (backend)
  • pyproject.toml with [tool.itw] project_type = "static" (static)
  • sonar-project.properties

Test settings (backend)

Tests run with backend.test_settings unless configured otherwise. The first match wins:

  1. --settings on itw test / itw pipelinelocal
  2. ITW_TEST_SETTINGS in the environment or .env
  3. pyproject.toml:
    [tool.itw]
    test_settings = "mysite.settings.test"
    

Release commands (incrementrc, release, …) use the same lookup.

GitLab token in the image build (backend)

itw passes the cached GitLab token to podman build as a build secret, so it never appears on the command line, in build args or in image history. The Dockerfile reads it in the one RUN that needs it:

ARG GITLAB_USERNAME
RUN --mount=type=secret,id=gitlab_token,required=true \
    GITLAB_TOKEN="$(cat /run/secrets/gitlab_token)" && \
    pip install --no-cache-dir \
      --extra-index-url https://${GITLAB_USERNAME}:${GITLAB_TOKEN}@gitlab.it-works.io/api/v4/projects/475/packages/pypi/simple \
      -r requirements.txt gunicorn

Dockerfiles that still declare ARG GITLAB_TOKEN keep working, with a warning, until they are migrated.

License

MIT

Metadata

Release files for itw-python-builder 0.2.19

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for itw-python-builder 0.2.19
File Size Uploaded Provenance Actions
itw_python_builder-0.2.19.tar.gz 56.7 kB Without provenance Details for itw_python_builder-0.2.19.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for itw-python-builder 0.2.19
File Interpreter ABI Platform Actions
itw_python_builder-0.2.19-py3-none-any.whl Python 3 none any Details for itw_python_builder-0.2.19-py3-none-any.whl

Total release size: 112.0 kB

Release files / itw_python_builder-0.2.19.tar.gz

Download URL itw_python_builder-0.2.19.tar.gz
Size 56.7 kB
Tags Source
SHA-256 checksum
How to use checksums
964f4e34e55de1c81b233e24095abf8f666eb63800c4202b4feafa08e6a380f9
BLAKE2b-256 checksum
How to use checksums
0313dbbd8e5e5e79a3e8fef33ba66ca448a78d96a3805cd7c95a62d6c0aa40d7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.16

Release files / itw_python_builder-0.2.19-py3-none-any.whl

Download URL itw_python_builder-0.2.19-py3-none-any.whl
Size 55.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ce74ccaf0d3ae4f090d3bb42e0f71fe37c5c32168dc2b5628abc4e1bb6e1d59e
BLAKE2b-256 checksum
How to use checksums
3368feb381c52586d7e4bd6d3a5c2963daae1fc559a8a0e7e6c6911a9ad40f94
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.16

Security for itw-python-builder 0.2.19

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.19 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page