Debian packages in the package registry All tiers Self-managed Experiment
- Debian API introduced in GitLab 13.5.
- Debian group API introduced in GitLab 14.2.
- Deployed behind a feature flag, disabled by default.
Publish Debian packages in your project’s package registry. Then install the packages whenever you need to use them as a dependency.
Project and Group packages are supported.
For documentation of the specific API endpoints that Debian package manager clients use, see the Debian API documentation.
Prerequisites:
- The
dpkg-deb
binary must be installed on the GitLab instance. This binary is usually provided by thedpkg
package, installed by default on Debian and derivatives. - Support for compression algorithm ZStandard requires version
dpkg >= 1.21.18
from Debian 12 Bookworm ordpkg >= 1.19.0.5ubuntu2
from Ubuntu 18.04 Bionic Beaver.
Enable the Debian API
Debian repository support is still a work in progress. It’s gated behind a feature flag that’s disabled by default. GitLab administrators with access to the GitLab Rails console can opt to enable it.
To enable it:
Feature.enable(:debian_packages)
To disable it:
Feature.disable(:debian_packages)
Enable the Debian group API
The Debian group repository is also behind a second feature flag that is disabled by default.
To enable it:
Feature.enable(:debian_group_packages)
To disable it:
Feature.disable(:debian_group_packages)
Build a Debian package
Creating a Debian package is documented on the Debian Wiki.
Authenticate to the Debian endpoints
Authentication methods differs between distributions APIs and package repositories.
Authenticate to the Debian distributions APIs
To create, read, update, or delete a distribution, you need one of the following:
-
Personal access token,
using
--header "PRIVATE-TOKEN: <personal_access_token>"
-
Deploy token
using
--header "Deploy-Token: <deploy_token>"
-
CI/CD job token
using
--header "Job-Token: <job_token>"
Authenticate to the Debian Package Repositories
To publish a package, or install a private package, you need to use basic authentication, with one of the following:
-
Personal access token,
using
<username>:<personal_access_token>
-
Deploy token
using
<deploy_token_name>:<deploy_token>
-
CI/CD job token
using
gitlab-ci-token:<job_token>
Create a Distribution
At the project level, Debian packages are published with Debian distributions. At the group level, Debian packages are aggregated from the projects in the group provided that:
- The project visibility is set to
public
. - The Debian
codename
for the group matches the Debiancodename
for the project.
To create a project-level distribution using a personal access token:
curl --request POST --header "PRIVATE-TOKEN: <personal_access_token>" \
"https://gitlab.example.com/api/v4/projects/<project_id>/debian_distributions?codename=<codename>"
Example response with codename=sid
:
{
"id": 1,
"codename": "sid",
"suite": null,
"origin": null,
"label": null,
"version": null,
"description": null,
"valid_time_duration_seconds": null,
"components": [
"main"
],
"architectures": [
"all",
"amd64"
]
}
More information on Debian distribution APIs:
Publish a package
Once built, several files are created:
-
.deb
files: the binary packages -
.udeb
files: lightened .deb files, used for Debian-Installer (if needed) -
.ddeb
files: Ubuntu debug .deb files (if needed) -
.tar.{gz,bz2,xz,...}
files: Source files -
.dsc
file: Source metadata, and list of source files (with hashes) -
.buildinfo
file: Used for Reproducible builds (optional) -
.changes
file: Upload metadata, and list of uploaded files (all the above)
To upload these files, you can use dput-ng >= 1.32
(Debian bullseye).
<username>
and <password>
are defined
as above:
cat <<EOF > dput.cf
[gitlab]
method = https
fqdn = <username>:<password>@gitlab.example.com
incoming = /api/v4/projects/<project_id>/packages/debian
EOF
dput --config=dput.cf --unchecked --no-upload-log gitlab <your_package>.changes
Upload a package with explicit distribution and component
Upload with explicit distribution and component introduced in GitLab 15.9.
When you don’t have access to .changes
file, you can directly upload a .deb
by passing
distribution codename
and target component
as parameters with
your credentials.
For example, to upload to component main
of distribution sid
using a personal access token:
curl --request PUT --user "<username>:<personal_access_token>" \
--get --data "distribution=sid" --data "component=main" \
"https://gitlab.example.com/api/v4/projects/<project_id>/packages/debian/" \
--upload-file /path/to/your.deb
Install a package
To install a package:
-
Configure the repository:
If you are using a private project, add your credentials to your apt configuration:
echo 'machine gitlab.example.com login <username> password <password>' \ | sudo tee /etc/apt/auth.conf.d/gitlab_project.conf
Download your distribution key using your credentials:
sudo mkdir -p /usr/local/share/keyrings curl --header "PRIVATE-TOKEN: <your_access_token>" \ "https://gitlab.example.com/api/v4/projects/<project_id>/debian_distributions/<codename>/key.asc" \ | \ gpg --dearmor \ | \ sudo tee /usr/local/share/keyrings/<codename>-archive-keyring.gpg \ > /dev/null
Add your project as a source:
echo 'deb [ signed-by=/usr/local/share/keyrings/<codename>-archive-keyring.gpg ] https://gitlab.example.com/api/v4/projects/<project_id>/packages/debian <codename> <component1> <component2>' \ | sudo tee /etc/apt/sources.list.d/gitlab_project.list sudo apt-get update
-
Install the package:
sudo apt-get -y install -t <codename> <package-name>
Download a source package
To download a source package:
-
Configure the repository:
If you are using a private project, add your credentials to your apt configuration:
echo 'machine gitlab.example.com login <username> password <password>' \ | sudo tee /etc/apt/auth.conf.d/gitlab_project.conf
Download your distribution key using your credentials:
sudo mkdir -p /usr/local/share/keyrings curl --header "PRIVATE-TOKEN: <your_access_token>" \ "https://gitlab.example.com/api/v4/projects/<project_id>/debian_distributions/<codename>/key.asc" \ | \ gpg --dearmor \ | \ sudo tee /usr/local/share/keyrings/<codename>-archive-keyring.gpg \ > /dev/null
Add your project as a source:
echo 'deb-src [ signed-by=/usr/local/share/keyrings/<codename>-archive-keyring.gpg ] https://gitlab.example.com/api/v4/projects/<project_id>/packages/debian <codename> <component1> <component2>' \ | sudo tee /etc/apt/sources.list.d/gitlab_project-sources.list sudo apt-get update
-
Download the source package:
sudo apt-get source -t <codename> <package-name>