Git workflow for the (E)LTS packages ¶

Rationale ¶

The (E)LTS team manages several releases and many packages. To preserve the history of all uploads, this Git workflow is mandatory.

All packages have a dedicated repository, referenced in the LTS/ELTS (private) package database deblts-team/debian-lts:packages.yml, using the vcs field (and optionally vcs_elts).

When following these steps, if you are not part of the LTS Team and lack sufficient permissions, please mail the LTS mailing list and request assistance.

New repository ¶

If no repositories are found in packages.yml, by order of preference:

Use the maintainers’ repository ¶

Work directly in the maintainers’ repository, or send merge and tag requests, if they are willing to host LTS/ELTS work, and have a DEP-14 layout (where the branches are named according to the releases, such as debian/bullseye).

Fork an existing repository ¶

When the maintainers’ repo is already at Salsa. Fork the repository under the lts-team/packages namespace.

Note: forking existing repositories (rather than recreating them) reduces resource consumption on Salsa and facilitates analyzing the history of the code.

Create a new repository ¶

Last resort option, manually import the repository at Salsa.

You may also use these instructions to import missing versions in existing repositories.

Go to the main project and press New project > Create blank project.
For the Project name field, enter the source package name.
Uncheck Initialize repository with a README.
Create project.

Clone the project on your computer:

git clone git@salsa.debian.org:lts-team/packages/package.git

Use gbp import-dsc to import the initial version(s) of your package. gbp import-dscs --debsnap can help import multiple versions (but doesn’t know about ELTS).

dget .../<package>_1.2-3.dsc
cd <package>/
gbp import-dsc --debian-branch=debian/bullseye --pristine-tar ../bullseye-new/<package>_1.2-3.dsc
gbp import-dsc --debian-branch=debian/bullseye --pristine-tar ../bullseye-new/<package>_1.2-3+deb11u1.dsc
...

# or
gbp import-dscs --debsnap --pristine-tar <package>
git checkout -b debian/bullseye debian/<last_bullseye_tag>

Initial push:

gbp push --debian-branch=debian/bullseye --pristine-tar
# also push previous tags
git push --tags

Clean-up branches ¶

Settings > Repository > Branch defaults: choose debian/bullseye, Save changes.
Code > Branches: remove main branch if any.

gbp.conf ¶

Clean-up gbp.conf, git-buildpackage’s configuration file, to avoid conflicts with the original configuration:

cat <<'EOF' > debian/gbp.conf
[DEFAULT]
pristine-tar = True
debian-branch = debian/bullseye
EOF
git commit -am 'Replace debian/gbp.conf'

Overlay repositories ¶

Repositories tracking only the debian/ directory (e.g. firmware-free, poppler) are supported by our workflow.

gbp.conf is a bit different:

[DEFAULT]
debian-branch = debian/bullseye
pristine-tar = False
overlay = True
export-dir = ..

The extract-source job will need a little help to find the source tarball (as of 2025-07 it only supports sid):

ensure origtargz works, e.g. uscan --download-current-version

add a pristine-tar branch anyway (at the cost of a heavier Git repo)

Setting up CI ¶

Each package must have a working CI (continuous integration) pipeline. An exception can be granted to some large or difficult packages where the CI is difficult to setup or is impossible for some technical reason. Each exception should be discussed on the LTS mailing list.

Project configuration ¶

Go to Settings > CI/CD. Expand General pipelines:
1. CI/CD configuration file: debian/salsa-ci.yml
2. Timeout: 6h (note: this is capped by the Runner’s timeout, current 3h, and SALSA_CI_BUILD_TIMEOUT_ARGS, currently 2.75h)
3. Save changes.
Expand Runners. Ensure there’s an ARM runner enabled: LTS Team ARM runner and/or salsaci-arm64-runner*.

salsa-ci.yml ¶

Create or modify debian/salsa-ci.yml with:

---
# LTS/ELTS CI

include:
- https://salsa.debian.org/lts-team/pipeline/raw/master/recipes/bullseye.yml

# These didn't work before LTS, not attempting to fix after freeze
#blhc:
#  allow_failure: true

# Or skip some tests entirely:
#variables:
#  SALSA_CI_DISABLE_BLHC: 1

The full documentation for the Debian pipeline may be found in the lts-team/pipeline repository.

Commit and push the file:

git add debian/salsa-ci.yml
git commit -am 'Add debian/salsa-ci.yml'
git push

If all went well, your package is being built at Build > Pipelines.

Prepare an upload of the already existing package ¶

Note: specify options even if we added them to gbp.conf above, in case we’re working on a package with a pre-LTS or missing gbp.conf.

Clone an existing repository:

gbp clone git@salsa.debian.org:lts-team/packages/package.git
# note: grabs and checks-out upstream, pristine-tar, etc. branches

Hack on the package

Try to build locally:

gbp buildpackage --git-debian-branch=debian/bullseye ...

After git push you can check the CI in Build > Pipelines.

If the build was successful, tag the package:

gbp tag --debian-branch=debian/bullseye
gbp push --debian-branch=debian/bullseye --pristine-tar