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:
CI/CD configuration file: debian/salsa-ci.yml
Timeout: 6h (note: this is capped by the Runner’s timeout, current 3h, and SALSA_CI_BUILD_TIMEOUT_ARGS, currently 2.75h)
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