Support `deploy_token` URL parameter especially for Generic Packages Repository mainly for Swift packages's binaryTarget
Release notes
Support deploy_token
URL parameter especially for Generic Packages Repository mainly for Swift packages's binaryTarget
Problem to solve
GitLab Generic Packages Repository is a great feature and it could be used for Swift package's binaryTarget to distribute XCFrameworks. However, we cannot actually reliably use it since it does not support deploy token supplied via URL parameter.
According to Generic Packages Repository: Download package file, we can use a deploy token with read_package_registry
scope to download a package file from GitLab Generic Packages Repository.
When it's fine to make package files globally (or internally in a single company) readable, using a deploy token with read_package_registry
is really useful since deploy tokens can be configured to never expire.
Project access tokens will expire in 1 year. The assumption here is that deploy tokens are meant to be stored somewhere permanently, or even exposed in public when it is really fine to expose package files in public.
In this way, we can use GitLab Generic Packages Repository as a replacement of something like Nexus.
Using GitLab as an generic artifact repository has many benefits:
- We can rely on GitLab's existing mechanism to manage permissions
- We can use GitLab APIs to interact with packages
- Everything is self-service. We can associate packages with a specific projects and when it is no longer needed, we can just destroy a whole git project. When using external solutions such as Nexus, everything need to be managed separately.
However, we cannot construct an URL for a package file without using "HTTP Basic authentication" since there is no way to pass a deploy token via an URL parameter.
We can construct URL for HTTP basic authentication by using @
like https://user:<deploy-token-here>@gitlab.example.com/api/v4/projects/24/packages/generic/my_package/0.0.1/file.txt
but URL with this form is problematic for some use cases.
One case I encountered is with Swift packages. I observed that when using URLs with @
for HTTP basic authentication, macOS's keychain tries to remember the password for the host and it opens keychain GUI for the next run.
When running macOS on CI, this results in "completely frozen state without logs" since we cannot interact with keychain GUI in CI. Similar issue was reported in here as well.
Since Apple's platform especially around Xcode is opaque, it's hard to debug what is actually happening. However, if we can just stop using HTTP basic auth, no issue will happen for this and we can just use Generic Packages Repository as a replacement of Nexus raw artifacts.
Proposal
Currently deploy-token
HTTP header is already supported (see #323907 (comment 533729196) but I think this is not yet documened?).
For example, curl --header "deploy-token: <deploy_token>" "https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/0.0.1/file.txt"
works fine.
However, in many contexts (e.g. Swift package's binaryTarget URL), we cannot pass headers.
I propose to support deploy_token
URL param to support these use cases.
- Current behavior:
curl "https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/0.0.1/file.txt?deploy_token=<deploy_token>"
does not work - Expected behavior:
curl "https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/0.0.1/file.txt?deploy_token=<deploy_token>"
should just work
Considerations
I think it should be fine to support deploy_token
URL parameter for all the endpoints with "deploy-token" HTTP header support. Do we have any concerns?
Note that the naming is mirroring the existing URL parameter (private_token
)
Intended users
Feature Usage Metrics
Does this feature require an audit event?
No.