summaryrefslogtreecommitdiff
path: root/doc/user/packages
diff options
context:
space:
mode:
Diffstat (limited to 'doc/user/packages')
-rw-r--r--doc/user/packages/composer_repository/index.md18
-rw-r--r--doc/user/packages/conan_repository/index.md18
-rw-r--r--doc/user/packages/container_registry/index.md19
-rw-r--r--doc/user/packages/dependency_proxy/index.md3
-rw-r--r--doc/user/packages/generic_packages/index.md27
-rw-r--r--doc/user/packages/npm_registry/index.md36
-rw-r--r--doc/user/packages/nuget_repository/index.md109
-rw-r--r--doc/user/packages/pypi_repository/index.md17
-rw-r--r--doc/user/packages/workflows/project_registry.md2
9 files changed, 221 insertions, 28 deletions
diff --git a/doc/user/packages/composer_repository/index.md b/doc/user/packages/composer_repository/index.md
index 751915f84a0..6159ea395fa 100644
--- a/doc/user/packages/composer_repository/index.md
+++ b/doc/user/packages/composer_repository/index.md
@@ -21,6 +21,11 @@ If you do not have a Composer package, create one and check it in to
a repository. This example shows a GitLab repository, but the repository
can be any public or private repository.
+WARNING:
+If you are using a GitLab repository, the project must have been created from
+a group's namespace, rather than a user's namespace. Composer packages
+[can't be published to projects created from a user's namespace](https://gitlab.com/gitlab-org/gitlab/-/issues/235467).
+
1. Create a directory called `my-composer-package` and change to that directory:
```shell
@@ -72,8 +77,8 @@ Prerequisites:
- A package in a GitLab repository. Composer packages should be versioned based on
the [Composer specification](https://getcomposer.org/doc/04-schema.md#version).
- If the version is not valid, for example, it has three dots (`1.0.0.0`), an
- error (`Validation failed: Version is invalid`) occurs when you publish.
+ If the version is not valid, for example, it has three dots (`1.0.0.0`), an
+ error (`Validation failed: Version is invalid`) occurs when you publish.
- A valid `composer.json` file.
- The Packages feature is enabled in a GitLab repository.
- The project ID, which is on the project's home page.
@@ -132,6 +137,13 @@ A more detailed Composer CI/CD file is also available as a `.gitlab-ci.yml` temp
WARNING:
Do not save unless you want to overwrite the existing CI/CD file.
+## Publishing packages with the same name or version
+
+When you publish:
+
+- The same package with different data, it overwrites the existing package.
+- The same package with the same data, a `404 Bad request` error occurs.
+
## Install a Composer package
Install a package from the Package Registry so you can use it as a dependency.
@@ -260,6 +272,6 @@ Output indicates that the package has been successfully installed.
WARNING:
Never commit the `auth.json` file to your repository. To install packages from a CI/CD job,
-consider using the [`composer config`](https://getcomposer.org/doc/articles/handling-private-packages-with-satis.md#authentication) tool with your personal access token
+consider using the [`composer config`](https://getcomposer.org/doc/articles/handling-private-packages.md#satis) tool with your personal access token
stored in a [GitLab CI/CD environment variable](../../../ci/variables/README.md) or in
[HashiCorp Vault](../../../ci/secrets/index.md).
diff --git a/doc/user/packages/conan_repository/index.md b/doc/user/packages/conan_repository/index.md
index 73798d363af..f90c220a622 100644
--- a/doc/user/packages/conan_repository/index.md
+++ b/doc/user/packages/conan_repository/index.md
@@ -47,7 +47,7 @@ Conan version 1.20.5
### Install CMake
When you develop with C++ and Conan, you can select from many available
-compilers. This example uses the CMake compiler.
+compilers. This example uses the CMake build system generator.
To install CMake:
@@ -283,6 +283,9 @@ Additional Conan images to use as the basis of your CI file are available in the
Install a Conan package from the Package Registry so you can use it as a
dependency.
+WARNING:
+Project-level packages [cannot be downloaded currently](https://gitlab.com/gitlab-org/gitlab/-/issues/270129).
+
Conan packages are often installed as dependencies by using the `conanfile.txt`
file.
@@ -384,3 +387,16 @@ The GitLab Conan repository supports the following Conan CLI commands:
packages you have permission to view.
- `conan info`: View the information on a given package from the Package Registry.
- `conan remove`: Delete the package from the Package Registry.
+
+## Troubleshooting Conan packages
+
+### `ERROR: <package> was not found in remote <remote>`
+
+When you attempt to install a Conan package, you might receive a `404` error
+like `ERROR: <package> was not found in remote <remote>`.
+
+This issue occurs when you request a download from the project-level Conan API.
+The resulting URL is missing is project's `/<id>` and Conan commands, like
+`conan install`, fail.
+
+For more information, see [issue 270129](https://gitlab.com/gitlab-org/gitlab/-/issues/270129).
diff --git a/doc/user/packages/container_registry/index.md b/doc/user/packages/container_registry/index.md
index 4e8d105adfa..8c284ccb9a3 100644
--- a/doc/user/packages/container_registry/index.md
+++ b/doc/user/packages/container_registry/index.md
@@ -305,7 +305,7 @@ is set to `always`.
To use your own Docker images for Docker-in-Docker, follow these steps
in addition to the steps in the
-[Docker-in-Docker](../../../ci/docker/using_docker_build.md#use-docker-in-docker-workflow-with-docker-executor) section:
+[Docker-in-Docker](../../../ci/docker/using_docker_build.md#use-the-docker-executor-with-the-docker-image-docker-in-docker) section:
1. Update the `image` and `service` to point to your registry.
1. Add a service [alias](../../../ci/yaml/README.md#servicesalias).
@@ -666,6 +666,23 @@ For example, you may have two individual images, one for `amd64` and another for
As a workaround, you should include the architecture in the tag name of individual images. For example, use `mygroup/myapp:1.0.0-amd64` instead of using sub repositories, like `mygroup/myapp/amd64:1.0.0`. You can then tag the manifest list with `mygroup/myapp:1.0.0`.
+### The cleanup policy doesn't delete any tags
+
+In GitLab 13.6 and earlier, when you run the cleanup policy,
+you may expect it to delete tags and it does not.
+
+This issue occurs when the cleanup policy was saved without
+editing the value in the **Remove tags matching** field.
+
+This field had a grayed out `.*` value as a placeholder.
+Unless `.*` (or other regex pattern) was entered explicitly into the
+field, a `nil` value was submitted. This value prevents the
+saved cleanup policy from matching any tags.
+
+As a workaround, edit the cleanup policy. In the **Remove tags matching**
+field, enter `.*` and save. This value indicates that all tags should
+be removed.
+
### Troubleshoot as a GitLab server admin
Troubleshooting the GitLab Container Registry, most of the times, requires
diff --git a/doc/user/packages/dependency_proxy/index.md b/doc/user/packages/dependency_proxy/index.md
index fbede6d13b7..5e5aadfae2b 100644
--- a/doc/user/packages/dependency_proxy/index.md
+++ b/doc/user/packages/dependency_proxy/index.md
@@ -141,11 +141,10 @@ You can use the Dependency Proxy to pull your base image.
bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ=
```
- This can also be other credentials such as:
+ This can also be a [personal access token](../../../user/profile/personal_access_tokens.md) such as:
```shell
echo -n "my_username:personal_access_token" | base64
- echo -n "deploy_token_username:deploy_token" | base64
```
1. Create a [custom environment variables](../../../ci/variables/README.md#custom-environment-variables)
diff --git a/doc/user/packages/generic_packages/index.md b/doc/user/packages/generic_packages/index.md
index c9859840c9c..82c72481984 100644
--- a/doc/user/packages/generic_packages/index.md
+++ b/doc/user/packages/generic_packages/index.md
@@ -20,16 +20,24 @@ Publish generic files, like release binaries, in your project’s Package Regist
## Authenticate to the Package Registry
-To authenticate to the Package Registry, you need either a [personal access token](../../../api/README.md#personalproject-access-tokens)
-or [CI job token](../../../api/README.md#gitlab-ci-job-token).
+To authenticate to the Package Registry, you need either a [personal access token](../../../api/README.md#personalproject-access-tokens),
+[CI job token](../../../api/README.md#gitlab-ci-job-token), or [deploy token](../../project/deploy_tokens/index.md).
+
+In addition to the standard API authentication mechanisms, the generic package
+API allows authentication with HTTP Basic authentication for use with tools that
+do not support the other available mechanisms. The `user-id` is not checked and
+may be any value, and the `password` must be either a [personal access token](../../../api/README.md#personalproject-access-tokens),
+a [CI job token](../../../api/README.md#gitlab-ci-job-token), or a [deploy token](../../project/deploy_tokens/index.md).
## Publish a package file
When you publish a package file, if the package does not exist, it is created.
+If a package with the same name, version, and filename already exists, it is also created. It does not overwrite the existing package.
+
Prerequisites:
-- You need to [authenticate with the API](../../../api/README.md#authentication).
+- You need to [authenticate with the API](../../../api/README.md#authentication). If authenticating with a deploy token, it must be configured with the `write_package_registry` scope.
```plaintext
PUT /projects/:id/packages/generic/:package_name/:package_version/:file_name
@@ -62,11 +70,13 @@ Example response:
## Download package file
-Install a package file.
+Download a package file.
+
+If multiple packages have the same name, version, and filename, then the most recent one is retrieved.
Prerequisites:
-- You need to [authenticate with the API](../../../api/README.md#authentication).
+- You need to [authenticate with the API](../../../api/README.md#authentication). If authenticating with a deploy token, it must be configured with the `read_package_registry` and/or `write_package_registry` scope.
```plaintext
GET /projects/:id/packages/generic/:package_name/:package_version/:file_name
@@ -88,6 +98,13 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" \
"https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/0.0.1/file.txt"
```
+Example request that uses HTTP Basic authentication:
+
+```shell
+curl --user "user:<your_access_token>" \
+ https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/0.0.1/file.txt
+```
+
## Publish a generic package by using CI/CD
To work with generic packages in [GitLab CI/CD](../../../ci/README.md), you can use
diff --git a/doc/user/packages/npm_registry/index.md b/doc/user/packages/npm_registry/index.md
index 51b41b842fa..c16fea1d00a 100644
--- a/doc/user/packages/npm_registry/index.md
+++ b/doc/user/packages/npm_registry/index.md
@@ -94,7 +94,10 @@ Some features such as [publishing](#publish-an-npm-package) a package is only av
## Authenticate to the Package Registry
-To authenticate to the Package Registry, you must use one of the following:
+You must authenticate with the Package Registry when the project
+is private. Public projects do not require authentication.
+
+To authenticate, use one of the following:
- A [personal access token](../../../user/profile/personal_access_tokens.md)
(required for two-factor authentication (2FA)), with the scope set to `api`.
@@ -102,7 +105,7 @@ To authenticate to the Package Registry, you must use one of the following:
- It's not recommended, but you can use [OAuth tokens](../../../api/oauth2.md#resource-owner-password-credentials-flow).
Standard OAuth tokens cannot authenticate to the GitLab NPM Registry. You must use a personal access token with OAuth headers.
- A [CI job token](#authenticate-with-a-ci-job-token).
-- Your NPM package name must be in the format of [@scope:package-name](#package-naming-convention). It must match exactly, including the case.
+- Your NPM package name must be in the format of [@scope/package-name](#package-naming-convention). It must match exactly, including the case.
### Authenticate with a personal access token or deploy token
@@ -201,7 +204,7 @@ Then, you can run `npm publish` either locally or by using GitLab CI/CD.
## Package naming convention
-Your NPM package name must be in the format of `@scope:package-name`.
+Your NPM package name must be in the format of `@scope/package-name`.
- The `@scope` is the root namespace of the GitLab project. It must match exactly, including the case.
- The `package-name` can be whatever you want.
@@ -241,7 +244,7 @@ Prerequisites:
- [Authenticate](#authenticate-to-the-package-registry) to the Package Registry.
- Set a [project-level NPM endpoint](#use-the-gitlab-endpoint-for-npm-packages).
-- Your NPM package name must be in the format of [@scope:package-name](#package-naming-convention). It must match exactly, including the case.
+- Your NPM package name must be in the format of [@scope/package-name](#package-naming-convention). It must match exactly, including the case.
To upload an NPM package to your project, run this command:
@@ -461,7 +464,30 @@ If you get this error, ensure that:
### `npm publish` returns `npm ERR! 400 Bad Request`
If you get this error, your package name may not meet the
-[@scope:package-name package naming convention](#package-naming-convention).
+[@scope/package-name package naming convention](#package-naming-convention).
Ensure the name meets the convention exactly, including the case.
Then try to publish again.
+
+### `npm publish` returns `npm ERR! 500 Internal Server Error - PUT`
+
+This is a [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/238950) in GitLab
+13.3.x and later. The error in the logs will appear as:
+
+```plaintext
+>NoMethodError - undefined method `preferred_language' for #<Rack::Response
+```
+
+This might be accompanied by another error:
+
+```plaintext
+>Errno::EACCES","exception.message":"Permission denied
+```
+
+This is usually a permissions issue with either:
+
+- `'packages_storage_path'` default `/var/opt/gitlab/gitlab-rails/shared/packages/`.
+- The remote bucket if [object storage](../../../administration/packages/#using-object-storage)
+ is used.
+
+In the latter case, ensure the bucket exists and the GitLab has write access to it.
diff --git a/doc/user/packages/nuget_repository/index.md b/doc/user/packages/nuget_repository/index.md
index bdf50ecef0b..35172663cc1 100644
--- a/doc/user/packages/nuget_repository/index.md
+++ b/doc/user/packages/nuget_repository/index.md
@@ -60,6 +60,21 @@ NuGet CLI.
mono nuget.exe
```
+## Use the GitLab endpoint for NuGet Packages
+
+To use the GitLab endpoint for NuGet Packages, choose an option:
+
+- **Project-level**: Use when you have few NuGet packages and they are not in
+ the same GitLab group.
+- **Group-level**: Use when you have many NuGet packages in different within the
+ same GitLab group.
+
+Some features such as [publishing](#publish-a-nuget-package) a package are only available on the project-level endpoint.
+
+WARNING:
+Because of how NuGet handles credentials, the Package Registry rejects anonymous requests on the group-level endpoint.
+To work around this limitation, set up [authentication](#add-the-package-registry-as-a-source-for-nuget-packages).
+
## Add the Package Registry as a source for NuGet packages
To publish and install packages to the Package Registry, you must add the
@@ -75,7 +90,9 @@ Prerequisites:
with the scope set to `read_package_registry`, `write_package_registry`, or
both.
- A name for your source.
-- Your project ID, which is found on your project's home page.
+- Depending on the [endpoint level](#use-the-gitlab-endpoint-for-nuget-packages) you use, either:
+ - Your project ID, which is found on your project's home page.
+ - Your group ID, which is found on your group's home page.
You can now add a new source to NuGet with:
@@ -85,7 +102,9 @@ You can now add a new source to NuGet with:
### Add a source with the NuGet CLI
-To add the Package Registry as a source with `nuget`:
+#### Project-level endpoint
+
+To use the [project-level](#use-the-gitlab-endpoint-for-nuget-packages) NuGet endpoint, add the Package Registry as a source with `nuget`:
```shell
nuget source Add -Name <source_name> -Source "https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/nuget/index.json" -UserName <gitlab_username or deploy_token_username> -Password <gitlab_personal_access_token or deploy_token>
@@ -99,9 +118,27 @@ For example:
nuget source Add -Name "GitLab" -Source "https://gitlab.example.com/api/v4/projects/10/packages/nuget/index.json" -UserName carol -Password 12345678asdf
```
+#### Group-level endpoint
+
+To use the [group-level](#use-the-gitlab-endpoint-for-nuget-packages) NuGet endpoint, add the Package Registry as a source with `nuget`:
+
+```shell
+nuget source Add -Name <source_name> -Source "https://gitlab.example.com/api/v4/groups/<your_group_id>/-/packages/nuget/index.json" -UserName <gitlab_username or deploy_token_username> -Password <gitlab_personal_access_token or deploy_token>
+```
+
+- `<source_name>` is the desired source name.
+
+For example:
+
+```shell
+nuget source Add -Name "GitLab" -Source "https://gitlab.example.com/api/v4/groups/23/-/packages/nuget/index.json" -UserName carol -Password 12345678asdf
+```
+
### Add a source with Visual Studio
-To add the Package Registry as a source with Visual Studio:
+#### Project-level endpoint
+
+To use the [project-level](#use-the-gitlab-endpoint-for-nuget-packages) NuGet endpoint, add the Package Registry as a source with Visual Studio:
1. Open [Visual Studio](https://visualstudio.microsoft.com/vs/).
1. In Windows, select **File > Options**. On macOS, select **Visual Studio > Preferences**.
@@ -126,9 +163,38 @@ The source is displayed in your list.
If you get a warning, ensure that the **Location**, **Username**, and
**Password** are correct.
+#### Group-level endpoint
+
+To use the [group-level](#use-the-gitlab-endpoint-for-nuget-packages) NuGet endpoint, add the Package Registry as a source with Visual Studio:
+
+1. Open [Visual Studio](https://visualstudio.microsoft.com/vs/).
+1. In Windows, select **File > Options**. On macOS, select **Visual Studio > Preferences**.
+1. In the **NuGet** section, select **Sources** to view a list of all your NuGet sources.
+1. Select **Add**.
+1. Complete the following fields:
+ - **Name**: Name for the source.
+ - **Location**: `https://gitlab.example.com/api/v4/groups/<your_group_id>/-/packages/nuget/index.json`,
+ where `<your_group_id>` is your group ID, and `gitlab.example.com` is
+ your domain name.
+ - **Username**: Your GitLab username or deploy token username.
+ - **Password**: Your personal access token or deploy token.
+
+ ![Visual Studio Adding a NuGet source](img/visual_studio_adding_nuget_source.png)
+
+1. Click **Save**.
+
+The source is displayed in your list.
+
+![Visual Studio NuGet source added](img/visual_studio_nuget_source_added.png)
+
+If you get a warning, ensure that the **Location**, **Username**, and
+**Password** are correct.
+
### Add a source with the .NET CLI
-To add the Package Registry as a source for .NET:
+#### Project-level endpoint
+
+To use the [project-level](#use-the-gitlab-endpoint-for-nuget-packages) Package Registry as a source for .NET:
1. In the root of your project, create a file named `nuget.config`.
1. Add this content:
@@ -138,7 +204,30 @@ To add the Package Registry as a source for .NET:
<configuration>
<packageSources>
<clear />
- <add key="gitlab" value="https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/nuget/index.json" />
+ <add key="gitlab" value="https://gitlab.example.com/api/v4/project/<your_project_id>/packages/nuget/index.json" />
+ </packageSources>
+ <packageSourceCredentials>
+ <gitlab>
+ <add key="Username" value="<gitlab_username or deploy_token_username>" />
+ <add key="ClearTextPassword" value="<gitlab_personal_access_token or deploy_token>" />
+ </gitlab>
+ </packageSourceCredentials>
+ </configuration>
+ ```
+
+#### Group-level endpoint
+
+To use the [group-level](#use-the-gitlab-endpoint-for-nuget-packages) Package Registry as a source for .NET:
+
+1. In the root of your project, create a file named `nuget.config`.
+1. Add this content:
+
+ ```xml
+ <?xml version="1.0" encoding="utf-8"?>
+ <configuration>
+ <packageSources>
+ <clear />
+ <add key="gitlab" value="https://gitlab.example.com/api/v4/groups/<your_group_id>/-/packages/nuget/index.json" />
</packageSources>
<packageSourceCredentials>
<gitlab>
@@ -151,6 +240,10 @@ To add the Package Registry as a source for .NET:
## Publish a NuGet package
+Prerequisite:
+
+- Set up the [source](#https://docs.gitlab.com/ee/user/packages/nuget_repository/#add-the-package-registry-as-a-source-for-nuget-packages) with a [project-level endpoint](#use-the-gitlab-endpoint-for-nuget-packages).
+
When publishing packages:
- The Package Registry on GitLab.com can store up to 500 MB of content.
@@ -164,9 +257,10 @@ When publishing packages:
### Publish a package with the NuGet CLI
-Prerequisite:
+Prerequisites:
- [A NuGet package created with NuGet CLI](https://docs.microsoft.com/en-us/nuget/create-packages/creating-a-package).
+- Set a [project-level endpoint](#use-the-gitlab-endpoint-for-nuget-packages).
Publish a package by running this command:
@@ -179,9 +273,10 @@ nuget push <package_file> -Source <source_name>
### Publish a package with the .NET CLI
-Prerequisite:
+Prerequisites:
- [A NuGet package created with .NET CLI](https://docs.microsoft.com/en-us/nuget/create-packages/creating-a-package-dotnet-cli).
+- Set a [project-level endpoint](#use-the-gitlab-endpoint-for-nuget-packages).
Publish a package by running this command:
diff --git a/doc/user/packages/pypi_repository/index.md b/doc/user/packages/pypi_repository/index.md
index e78224f89d1..376c0439f32 100644
--- a/doc/user/packages/pypi_repository/index.md
+++ b/doc/user/packages/pypi_repository/index.md
@@ -233,11 +233,16 @@ password = ${env.CI_JOB_TOKEN}
## Publish a PyPI package
-When publishing packages, note that:
+Prerequisites:
-- The maximum allowed size is 50 MB.
+- You must [authenticate with the Package Registry](#authenticate-with-the-package-registry).
+- Your [version string must be valid](#ensure-your-version-string-is-valid).
+- The maximum allowed package size is 5 GB.
- You can't upload the same version of a package multiple times. If you try,
- you receive the error `Validation failed: File name has already been taken`.
+ you receive the error `400 Bad Request`.
+- You cannot publish PyPI packages to a group, only to a project.
+
+You can then [publish a package by using twine](#publish-a-pypi-package-by-using-twine).
### Ensure your version string is valid
@@ -301,6 +306,12 @@ python -m twine upload --repository <source_name> dist/<package_file>
- `<package_file>` is your package filename, ending in `.tar.gz` or `.whl`.
- `<source_name>` is the [source name used during setup](#authenticate-with-the-package-registry).
+### Publishing packages with the same name or version
+
+You cannot publish a package if a package of the same name and version already exists.
+You must delete the existing package first. If you attempt to publish the same package
+more than once, a `404 Bad Request` error occurs.
+
## Install a PyPI package
To install the latest version of a package, use the following command:
diff --git a/doc/user/packages/workflows/project_registry.md b/doc/user/packages/workflows/project_registry.md
index aea1238b9da..d20c75e2d7a 100644
--- a/doc/user/packages/workflows/project_registry.md
+++ b/doc/user/packages/workflows/project_registry.md
@@ -68,7 +68,7 @@ For Conan, you need to add GitLab as a Conan registry remote. Follow the instruc
Then, create your package using the plus-separated (`+`) project path as your Conan user. For example,
if your project is located at `https://gitlab.com/foo/bar/my-proj`,
[create your Conan package](../conan_repository/index.md) using `conan create . foo+bar+my-proj/channel`.
-`channel` is your package channel (such as `stable` or `beta`).
+`channel` is your package channel (such as `stable` or `beta`).
After you create your package, you're ready to [publish your package](../conan_repository/index.md#publish-a-conan-package),
depending on your final package recipe. For example: