diff options
Diffstat (limited to 'doc/user/packages')
-rw-r--r-- | doc/user/packages/conan_repository/index.md | 9 | ||||
-rw-r--r-- | doc/user/packages/container_registry/index.md | 8 | ||||
-rw-r--r-- | doc/user/packages/dependency_proxy/index.md | 32 | ||||
-rw-r--r-- | doc/user/packages/generic_packages/index.md | 22 | ||||
-rw-r--r-- | doc/user/packages/go_proxy/index.md | 2 | ||||
-rw-r--r-- | doc/user/packages/index.md | 5 | ||||
-rw-r--r-- | doc/user/packages/npm_registry/index.md | 26 | ||||
-rw-r--r-- | doc/user/packages/nuget_repository/index.md | 2 | ||||
-rw-r--r-- | doc/user/packages/package_registry/index.md | 4 | ||||
-rw-r--r-- | doc/user/packages/pypi_repository/index.md | 18 | ||||
-rw-r--r-- | doc/user/packages/workflows/monorepo.md | 9 | ||||
-rw-r--r-- | doc/user/packages/workflows/project_registry.md | 5 |
12 files changed, 91 insertions, 51 deletions
diff --git a/doc/user/packages/conan_repository/index.md b/doc/user/packages/conan_repository/index.md index c115f94b964..3b8be68cff6 100644 --- a/doc/user/packages/conan_repository/index.md +++ b/doc/user/packages/conan_repository/index.md @@ -171,6 +171,10 @@ convention. ## Authenticate to the Package Registry +GitLab requires authentication to upload packages, and to install packages +from private and internal projects. (You can, however, install packages +from public projects without authentication.) + To authenticate to the Package Registry, you need one of the following: - A [personal access token](../../../user/profile/personal_access_tokens.md) @@ -302,8 +306,9 @@ file. Prerequisites: - The Conan remote [must be configured](#add-the-package-registry-as-a-conan-remote). -- [Authentication](#authenticate-to-the-package-registry) with the - Package Registry must be configured. +- For private and internal projects, you must configure + [Authentication](#authenticate-to-the-package-registry) + with the Package Registry. 1. In the project where you want to install the package as a dependency, open `conanfile.txt`. Or, in the root of your project, create a file called diff --git a/doc/user/packages/container_registry/index.md b/doc/user/packages/container_registry/index.md index e3a469c4b6c..18c4edd61c7 100644 --- a/doc/user/packages/container_registry/index.md +++ b/doc/user/packages/container_registry/index.md @@ -577,7 +577,7 @@ Here are examples of regex patterns you may want to use: (?:v.+|master|release.*) ``` -### Set cleanup limits to conserve resources +### Set cleanup limits to conserve resources > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/288812) in GitLab 13.9. > - It's [deployed behind a feature flag](../../feature_flags.md), disabled by default. @@ -595,7 +595,7 @@ To prevent server resource starvation, the following application settings are av - `container_registry_delete_tags_service_timeout`. The maximum time, in seconds, that the cleanup process can take to delete a batch of tags. - `container_registry_cleanup_tags_service_max_list_size`. The maximum number of tags that can be deleted in a single execution. Additional tags must be deleted in another execution. We recommend starting with a low number, like `100`, and increasing it after monitoring that container images are properly deleted. - + For self-managed instances, those settings can be updated in the [Rails console](../../../administration/operations/rails_console.md#starting-a-rails-console-session): ```ruby @@ -699,7 +699,7 @@ project or branch name. Special characters can include: - Leading underscore - Trailing hyphen/dash -To get around this, you can [change the group path](../../group/index.md#changing-a-groups-path), +To get around this, you can [change the group path](../../group/index.md#change-a-groups-path), [change the project path](../../project/settings/index.md#renaming-a-repository) or change the branch name. @@ -712,7 +712,7 @@ For information on how to update your images, see the [Docker help](https://docs ### `Blob unknown to registry` error when pushing a manifest list -When [pushing a Docker manifest list](https://docs.docker.com/engine/reference/commandline/manifest/#create-and-push-a-manifest-list) to the GitLab Container Registry, you may receive the error `manifest blob unknown: blob unknown to registry`. This issue occurs when the individual child manifests referenced in the manifest list were not pushed to the same repository. +When [pushing a Docker manifest list](https://docs.docker.com/engine/reference/commandline/manifest/#create-and-push-a-manifest-list) to the GitLab Container Registry, you may receive the error `manifest blob unknown: blob unknown to registry`. [This issue](https://gitlab.com/gitlab-org/gitlab/-/issues/209008) occurs when the individual child manifests referenced in the manifest list were not pushed to the same repository. For example, you may have two individual images, one for `amd64` and another for `arm64v8`, and you want to build a multi-arch image with them. The `amd64` and `arm64v8` images must be pushed to the same repository where you want to push the multi-arch image. diff --git a/doc/user/packages/dependency_proxy/index.md b/doc/user/packages/dependency_proxy/index.md index fdf0caba090..ad2d2ac2a8e 100644 --- a/doc/user/packages/dependency_proxy/index.md +++ b/doc/user/packages/dependency_proxy/index.md @@ -4,12 +4,13 @@ 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 --- -# Dependency Proxy +# Dependency Proxy **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7934) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.11. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/273655) to [GitLab Core](https://about.gitlab.com/pricing/) in GitLab 13.6. -> - [Support for private groups](https://gitlab.com/gitlab-org/gitlab/-/issues/11582) in [GitLab Core](https://about.gitlab.com/pricing/) 13.7. -> - Anonymous access to images in public groups is no longer available starting in [GitLab Core](https://about.gitlab.com/pricing/) 13.7. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/273655) to GitLab Free in GitLab 13.6. +> - [Support for private groups](https://gitlab.com/gitlab-org/gitlab/-/issues/11582) in GitLab Free 13.7. +> - Anonymous access to images in public groups is no longer available starting in GitLab Free 13.7. +> - [Support for pull-by-digest and Docker version 20.x](https://gitlab.com/gitlab-org/gitlab/-/issues/290944) in GitLab Free 13.10. The GitLab Dependency Proxy is a local proxy you can use for your frequently-accessed upstream images. @@ -17,11 +18,6 @@ upstream images. In the case of CI/CD, the Dependency Proxy receives a request and returns the upstream image from a registry, acting as a pull-through cache. -NOTE: -The Dependency Proxy is not compatible with Docker version 20.x and later. -If you are using the Dependency Proxy, Docker version 19.x.x is recommended until -[issue #290944](https://gitlab.com/gitlab-org/gitlab/-/issues/290944) is resolved. - ## Prerequisites The Dependency Proxy must be [enabled by an administrator](../../../administration/packages/dependency_proxy.md). @@ -60,7 +56,7 @@ Prerequisites: ### Authenticate with the Dependency Proxy -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11582) in [GitLab Core](https://about.gitlab.com/pricing/) 13.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11582) in GitLab Free 13.7. > - It's [deployed behind a feature flag](../../feature_flags.md), enabled by default. > - It's enabled on GitLab.com. > - It's recommended for production use. @@ -93,14 +89,17 @@ You can authenticate using: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/280582) in GitLab 13.7. > - Automatic runner authentication [added](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/27302) in GitLab 13.9. +> - The prefix for group names containing uppercase letters was [fixed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/54559) in GitLab 13.10. Runners log in to the Dependency Proxy automatically. To pull through the Dependency Proxy, use the `CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX` [predefined CI/CD variable](../../../ci/variables/predefined_variables.md): +Example pulling the latest alpine image: + ```yaml # .gitlab-ci.yml -image: ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/node:latest +image: ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/alpine:latest ``` There are other additional predefined CI/CD variables you can also use: @@ -128,13 +127,20 @@ To store a Docker image in Dependency Proxy storage: 1. Go to your group's **Packages & Registries > Dependency Proxy**. 1. Copy the **Dependency Proxy URL**. 1. Use one of these commands. In these examples, the image is `alpine:latest`. +1. You can also pull images by digest to specify exactly which version of an image to pull. - - Add the URL to your [`.gitlab-ci.yml`](../../../ci/yaml/README.md#image) file: + - Pull an image by tag by adding the image to your [`.gitlab-ci.yml`](../../../ci/yaml/README.md#image) file: ```shell image: gitlab.example.com/groupname/dependency_proxy/containers/alpine:latest ``` + - Pull an image by digest by adding the image to your [`.gitlab-ci.yml`](../../../ci/yaml/README.md#image) file: + + ```shell + image: ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/alpine@sha256:c9375e662992791e3f39e919b26f510e5254b42792519c180aad254e6b38f4dc + ``` + - Manually pull the Docker image: ```shell @@ -162,7 +168,7 @@ the [Dependency Proxy API](../../../api/dependency_proxy.md). ## Docker Hub rate limits and the Dependency Proxy -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241639) in [GitLab Core](https://about.gitlab.com/pricing/) 13.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241639) in GitLab Free 13.7. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch how to [use the Dependency Proxy to help avoid Docker Hub rate limits](https://youtu.be/Nc4nUo7Pq08). diff --git a/doc/user/packages/generic_packages/index.md b/doc/user/packages/generic_packages/index.md index 73b84c04b6d..b9186e99357 100644 --- a/doc/user/packages/generic_packages/index.md +++ b/doc/user/packages/generic_packages/index.md @@ -40,7 +40,7 @@ Prerequisites: - 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 +PUT /projects/:id/packages/generic/:package_name/:package_version/:file_name?status=:status ``` | Attribute | Type | Required | Description | @@ -53,12 +53,28 @@ PUT /projects/:id/packages/generic/:package_name/:package_version/:file_name Provide the file context in the request body. -Example request: +Example request using a personal access token: ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" \ --upload-file path/to/file.txt \ - "https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/0.0.1/file.txt" + "https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/0.0.1/file.txt?status=hidden" +``` + +Example response: + +```json +{ + "message":"201 Created" +} +``` + +Example request using a deploy token: + +```shell +curl --header "DEPLOY-TOKEN: <deploy_token>" \ + --upload-file path/to/file.txt \ + "https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/0.0.1/file.txt?status=hidden" ``` Example response: diff --git a/doc/user/packages/go_proxy/index.md b/doc/user/packages/go_proxy/index.md index c9397f8d9f6..1fdc34e820e 100644 --- a/doc/user/packages/go_proxy/index.md +++ b/doc/user/packages/go_proxy/index.md @@ -96,7 +96,7 @@ following steps work only if GitLab is configured for HTTPS: Create a [personal access token](../../profile/personal_access_tokens.md) with the scope set to `api` or `read_api`. -Open your [`~/.netrc`](https://ec.haxx.se/usingcurl/usingcurl-netrc) file +Open your [`~/.netrc`](https://everything.curl.dev/usingcurl/netrc) file and add the following text. Replace the variables in `< >` with your values. ```plaintext diff --git a/doc/user/packages/index.md b/doc/user/packages/index.md index d2bd9ef5646..b35015d0b67 100644 --- a/doc/user/packages/index.md +++ b/doc/user/packages/index.md @@ -43,14 +43,15 @@ guides you through the process. | CocoaPods | [#36890](https://gitlab.com/gitlab-org/gitlab/-/issues/36890) | | Conda | [#36891](https://gitlab.com/gitlab-org/gitlab/-/issues/36891) | | CRAN | [#36892](https://gitlab.com/gitlab-org/gitlab/-/issues/36892) | -| Debian | [WIP: Merge Request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/44746) | +| Debian | [Draft: Merge Request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/50438) | +| Helm | [#18997](https://gitlab.com/gitlab-org/gitlab/-/issues/18997) | | Opkg | [#36894](https://gitlab.com/gitlab-org/gitlab/-/issues/36894) | | P2 | [#36895](https://gitlab.com/gitlab-org/gitlab/-/issues/36895) | | Puppet | [#36897](https://gitlab.com/gitlab-org/gitlab/-/issues/36897) | | RPM | [#5932](https://gitlab.com/gitlab-org/gitlab/-/issues/5932) | | RubyGems | [#803](https://gitlab.com/gitlab-org/gitlab/-/issues/803) | | SBT | [#36898](https://gitlab.com/gitlab-org/gitlab/-/issues/36898) | -| Terraform | [WIP: Merge Request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/18834) | +| Terraform | [Draft: Merge Request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/18834) | | Vagrant | [#36899](https://gitlab.com/gitlab-org/gitlab/-/issues/36899) | <!-- vale gitlab.Spelling = YES --> diff --git a/doc/user/packages/npm_registry/index.md b/doc/user/packages/npm_registry/index.md index b1075e19b7b..f048440e383 100644 --- a/doc/user/packages/npm_registry/index.md +++ b/doc/user/packages/npm_registry/index.md @@ -86,7 +86,9 @@ A `package.json` file is created. To use the GitLab endpoint for npm packages, choose an option: - **Project-level**: Use when you have few npm packages and they are not in - the same GitLab group. + the same GitLab group. The [package naming convention](#package-naming-convention) is not enforced at this level. + Instead, you should use a [scope](https://docs.npmjs.com/cli/v6/using-npm/scope) for your package. + When you use a scope, the registry URL is [updated](#authenticate-to-the-package-registry) only for that scope. - **Instance-level**: Use when you have many npm packages in different GitLab groups or in their own namespace. Be sure to comply with the [package naming convention](#package-naming-convention). @@ -151,7 +153,7 @@ npm config set '//gitlab.example.com/api/v4/packages/npm/:_authToken' "<your_tok - `<your_token>` is your personal access token or deploy token. - Replace `gitlab.example.com` with your domain name. -You should now be able to publish and install npm packages in your project. +You should now be able to install npm packages in your project. If you encounter an error with [Yarn](https://classic.yarnpkg.com/en/), view [troubleshooting steps](#troubleshooting). @@ -204,9 +206,14 @@ 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`. +When you use the [instance-level endpoint](#use-the-gitlab-endpoint-for-npm-packages), only the packages with names in the format of `@scope/package-name` are available. -- The `@scope` is the root namespace of the GitLab project. It must match exactly, including the case. +- The `@scope` is the root namespace of the GitLab project. To follow npm's convention, it should be + lowercase. However, the GitLab package registry allows for uppercase. Before GitLab 13.10, the + `@scope` had to be a case-sensitive match of the GitLab project's root namespace. This was + problematic because the npm public registry does not allow uppercase letters. GitLab 13.10 relaxes + this requirement and translates uppercase in the GitLab `@scope` to lowercase for npm. For + example, a package `@MyScope/package-name` in GitLab becomes `@myscope/package-name` for npm. - The `package-name` can be whatever you want. For example, if your project is `https://gitlab.example.com/my-org/engineering-group/team-amazing/analytics`, @@ -216,7 +223,8 @@ the root namespace is `my-org`. When you publish a package, it must have `my-org | ---------------------- | ----------------------- | --------- | | `my-org/bar` | `@my-org/bar` | Yes | | `my-org/bar/baz` | `@my-org/baz` | Yes | -| `My-org/Bar/baz` | `@My-org/Baz` | Yes | +| `My-Org/Bar/baz` | `@my-org/Baz` | Yes | +| `My-Org/Bar/baz` | `@My-Org/Baz` | Yes | | `my-org/bar/buz` | `@my-org/anything` | Yes | | `gitlab-org/gitlab` | `@gitlab-org/gitlab` | Yes | | `gitlab-org/gitlab` | `@foo/bar` | No | @@ -229,8 +237,7 @@ In GitLab, this regex validates all package names from all package managers: This regex allows almost all of the characters that npm allows, with a few exceptions (for example, `~` is not allowed). -The regex also allows for capital letters, while npm does not. Capital letters are needed because the scope must be -identical to the root namespace of the project. +The regex also allows for capital letters, while npm does not. WARNING: When you update the path of a user or group, or transfer a subgroup or project, @@ -302,8 +309,9 @@ the same version more than once, even if it has been deleted. ## Install a package npm packages are commonly-installed by using the `npm` or `yarn` commands -in a JavaScript project. You can install a package from the scope of a project, group, -or instance. +in a JavaScript project. You can install a package from the scope of a project or instance. + +If multiple packages have the same name and version, when you install a package, the most recently-published package is retrieved. 1. Set the URL for scoped packages by running: diff --git a/doc/user/packages/nuget_repository/index.md b/doc/user/packages/nuget_repository/index.md index 101bb810a0e..e1b61f28818 100644 --- a/doc/user/packages/nuget_repository/index.md +++ b/doc/user/packages/nuget_repository/index.md @@ -219,7 +219,7 @@ To use the [project-level](#use-the-gitlab-endpoint-for-nuget-packages) Package <configuration> <packageSources> <clear /> - <add key="gitlab" value="https://gitlab.example.com/api/v4/project/<your_project_id>/packages/nuget/index.json" /> + <add key="gitlab" value="https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/nuget/index.json" /> </packageSources> <packageSourceCredentials> <gitlab> diff --git a/doc/user/packages/package_registry/index.md b/doc/user/packages/package_registry/index.md index 19796de0f51..0e83843f3e8 100644 --- a/doc/user/packages/package_registry/index.md +++ b/doc/user/packages/package_registry/index.md @@ -4,7 +4,7 @@ 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 --- -# Package Registry +# Package Registry **(FREE)** > [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. @@ -21,6 +21,8 @@ You can view packages for your project or group. You can search, sort, and filter packages on this page. +You can also find helpful code snippets for configuring your package manager or installing a given package. + When you view packages in a group: - All projects published to the group and its projects are displayed. diff --git a/doc/user/packages/pypi_repository/index.md b/doc/user/packages/pypi_repository/index.md index 763dbee3a82..a6cc5cf1f07 100644 --- a/doc/user/packages/pypi_repository/index.md +++ b/doc/user/packages/pypi_repository/index.md @@ -174,11 +174,10 @@ index-servers = [gitlab] repository = https://gitlab.example.com/api/v4/projects/<project_id>/packages/pypi -username = __token__ -password = <your personal access token> +username = <your_personal_access_token_name> +password = <your_personal_access_token> ``` -- `username` must be `__token__` exactly. - Your project ID is on your project's home page. ### Authenticate with a deploy token @@ -317,24 +316,31 @@ more than once, a `404 Bad Request` error occurs. To install the latest version of a package, use the following command: ```shell -pip install --extra-index-url https://__token__:<personal_access_token>@gitlab.example.com/api/v4/projects/<project_id>/packages/pypi/simple --no-deps <package_name> +pip install --index-url https://<personal_access_token_name>:<personal_access_token>@gitlab.example.com/api/v4/projects/<project_id>/packages/pypi/simple --no-deps <package_name> ``` - `<package_name>` is the package name. +- `<personal_access_token_name>` is a personal access token name with the `read_api` scope. - `<personal_access_token>` is a personal access token with the `read_api` scope. - `<project_id>` is the project ID. +In these commands, you can use `--extra-index-url` instead of `--index-url`. However, using +`--extra-index-url` makes you vulnerable to dependency confusion attacks because it checks the PyPi +repository for the package before it checks the custom repository. `--extra-index-url` adds the +provided URL as an additional registry which the client checks if the package is present. +`--index-url` tells the client to check for the package on the provided URL only. + If you were following the guide and want to install the `MyPyPiPackage` package, you can run: ```shell -pip install mypypipackage --no-deps --extra-index-url https://__token__:<personal_access_token>@gitlab.example.com/api/v4/projects/<your_project_id>/packages/pypi/simple +pip install mypypipackage --no-deps --index-url https://<personal_access_token_name>:<personal_access_token>@gitlab.example.com/api/v4/projects/<your_project_id>/packages/pypi/simple ``` This message indicates that the package was installed successfully: ```plaintext -Looking in indexes: https://__token__:****@gitlab.example.com/api/v4/projects/<your_project_id>/packages/pypi/simple +Looking in indexes: https://<personal_access_token_name>:****@gitlab.example.com/api/v4/projects/<your_project_id>/packages/pypi/simple Collecting mypypipackage Downloading https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/pypi/files/d53334205552a355fee8ca35a164512ef7334f33d309e60240d57073ee4386e6/mypypipackage-0.0.1-py3-none-any.whl (1.6 kB) Installing collected packages: mypypipackage diff --git a/doc/user/packages/workflows/monorepo.md b/doc/user/packages/workflows/monorepo.md deleted file mode 100644 index abba9df6ec2..00000000000 --- a/doc/user/packages/workflows/monorepo.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -redirect_to: '../npm_registry/index.md' -disqus_identifier: 'https://docs.gitlab.com/ee/user/packages/workflows/monorepo.html' ---- - -This document was moved to [another location](../npm_registry/index.md). - -<!-- This redirect file can be deleted after <2021-02-14>. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/packages/workflows/project_registry.md b/doc/user/packages/workflows/project_registry.md index 9b99b126996..c63c2cc9989 100644 --- a/doc/user/packages/workflows/project_registry.md +++ b/doc/user/packages/workflows/project_registry.md @@ -77,6 +77,11 @@ depending on your final package recipe. For example: CONAN_LOGIN_USERNAME=<gitlab-username> CONAN_PASSWORD=<personal_access_token> conan upload MyPackage/1.0.0@foo+bar+my-proj/channel --all --remote=gitlab ``` +### Composer + +You can't publish a Composer package outside of its project. An [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/250633) +exists to implement functionality that allows you to publish such packages to other projects. + ### All other package types [All package types supported by GitLab](../index.md) can be published in |