debian-mirror-gitlab/doc/user/packages/debian_repository/index.md

175 lines
5.2 KiB
Markdown
Raw Normal View History

2021-09-30 23:02:18 +05:30
---
stage: Package
group: Package
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
---
# Debian packages in the Package Registry **(FREE)**
2021-10-27 15:23:28 +05:30
> - Debian API [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/42670) in GitLab 13.5.
> - Debian group API [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/66188) in GitLab 14.2.
> - [Deployed behind a feature flag](../../feature_flags.md), disabled by default.
2021-09-30 23:02:18 +05:30
WARNING:
The Debian package registry for GitLab is under development and isn't ready for production use due to
2021-11-18 22:05:49 +05:30
limited functionality. This [epic](https://gitlab.com/groups/gitlab-org/-/epics/6057) details the remaining
work and timelines to make it production ready.
2021-09-30 23:02:18 +05:30
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](../../../api/packages/debian.md).
2021-10-27 15:23:28 +05:30
## Enable the Debian API **(FREE SELF)**
2021-09-30 23:02:18 +05:30
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](../../../administration/feature_flags.md)
can opt to enable it.
To enable it:
```ruby
Feature.enable(:debian_packages)
```
To disable it:
```ruby
Feature.disable(:debian_packages)
```
2021-10-27 15:23:28 +05:30
## Enable the Debian group API **(FREE SELF)**
The Debian group repository is also behind a second feature flag that is disabled by default.
To enable it:
```ruby
Feature.enable(:debian_group_packages)
```
To disable it:
```ruby
Feature.disable(:debian_group_packages)
```
2021-09-30 23:02:18 +05:30
## Build a Debian package
Creating a Debian package is documented [on the Debian Wiki](https://wiki.debian.org/Packaging).
2021-10-27 15:23:28 +05:30
## Authenticate to the Package Registry
To create a distribution, publish a package, or install a private package, you need one of the
following:
2022-03-02 08:16:31 +05:30
- [Personal access token](../../../api/index.md#personalprojectgroup-access-tokens)
2021-11-11 11:23:49 +05:30
- [CI/CD job token](../../../ci/jobs/ci_job_token.md)
2021-10-27 15:23:28 +05:30
- [Deploy token](../../project/deploy_tokens/index.md)
2021-09-30 23:02:18 +05:30
## Create a Distribution
On the project-level, Debian packages are published using *Debian Distributions*. To publish
packages on the group level, create a distribution with the same `codename`.
To create a project-level distribution:
```shell
2021-12-11 22:18:48 +05:30
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/<project_id>/debian_distributions?codename=<codename>"
2021-09-30 23:02:18 +05:30
```
2021-12-11 22:18:48 +05:30
Example response with `codename=unstable`:
2021-09-30 23:02:18 +05:30
```json
{
"id": 1,
"codename": "unstable",
"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:
- [Debian project distributions API](../../../api/packages/debian_project_distributions.md)
- [Debian group distributions API](../../../api/packages/debian_group_distributions.md)
## 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)
- `.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):
```shell
cat <<EOF > dput.cf
[gitlab]
method = https
2021-10-27 15:23:28 +05:30
fqdn = <username>:<your_access_token>@gitlab.example.com
2021-09-30 23:02:18 +05:30
incoming = /api/v4/projects/<project_id>/packages/debian
EOF
dput --config=dput.cf --unchecked --no-upload-log gitlab <your_package>.changes
```
## Install a package
2021-10-27 15:23:28 +05:30
To install a package:
1. Configure the repository:
2021-11-18 22:05:49 +05:30
If you are using a private project, add your [credentials](#authenticate-to-the-package-registry) to your apt configuration:
2021-10-27 15:23:28 +05:30
```shell
echo 'machine gitlab.example.com login <username> password <your_access_token>' \
| sudo tee /etc/apt/auth.conf.d/gitlab_project.conf
```
2021-12-11 22:18:48 +05:30
Download your distribution key:
```shell
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
```
2021-10-27 15:23:28 +05:30
Add your project as a source:
```shell
2021-12-11 22:18:48 +05:30
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>' \
2021-10-27 15:23:28 +05:30
| sudo tee /etc/apt/sources.list.d/gitlab_project.list
sudo apt-get update
```
1. Install the package:
```shell
sudo apt-get -y install -t <codename> <package-name>
```