diff options
Diffstat (limited to 'doc/user/packages')
| -rw-r--r-- | doc/user/packages/composer_repository/index.md | 2 | ||||
| -rw-r--r-- | doc/user/packages/conan_repository/index.md | 2 | ||||
| -rw-r--r-- | doc/user/packages/container_registry/index.md | 42 | ||||
| -rw-r--r-- | doc/user/packages/debian_repository/index.md | 111 | ||||
| -rw-r--r-- | doc/user/packages/dependency_proxy/index.md | 27 | ||||
| -rw-r--r-- | doc/user/packages/generic_packages/index.md | 18 | ||||
| -rw-r--r-- | doc/user/packages/go_proxy/index.md | 2 | ||||
| -rw-r--r-- | doc/user/packages/helm_repository/index.md | 89 | ||||
| -rw-r--r-- | doc/user/packages/index.md | 2 | ||||
| -rw-r--r-- | doc/user/packages/infrastructure_registry/index.md | 2 | ||||
| -rw-r--r-- | doc/user/packages/maven_repository/index.md | 21 | ||||
| -rw-r--r-- | doc/user/packages/npm_registry/index.md | 33 | ||||
| -rw-r--r-- | doc/user/packages/nuget_repository/index.md | 32 | ||||
| -rw-r--r-- | doc/user/packages/package_registry/index.md | 6 | ||||
| -rw-r--r-- | doc/user/packages/pypi_repository/index.md | 4 | ||||
| -rw-r--r-- | doc/user/packages/rubygems_registry/index.md | 2 | ||||
| -rw-r--r-- | doc/user/packages/terraform_module_registry/index.md | 12 |
17 files changed, 358 insertions, 49 deletions
diff --git a/doc/user/packages/composer_repository/index.md b/doc/user/packages/composer_repository/index.md index b5170dfa55b..b6eb2975374 100644 --- a/doc/user/packages/composer_repository/index.md +++ b/doc/user/packages/composer_repository/index.md @@ -293,7 +293,7 @@ To install a package: 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.md#satis) tool with your personal access token -stored in a [GitLab CI/CD variable](../../../ci/variables/README.md) or in +stored in a [GitLab CI/CD variable](../../../ci/variables/index.md) or in [HashiCorp Vault](../../../ci/secrets/index.md). ## Supported CLI commands diff --git a/doc/user/packages/conan_repository/index.md b/doc/user/packages/conan_repository/index.md index a429e746cf2..c6cc7e7905a 100644 --- a/doc/user/packages/conan_repository/index.md +++ b/doc/user/packages/conan_repository/index.md @@ -269,7 +269,7 @@ conan upload Hello/0.1@mycompany/beta --all > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11678) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.7. -To work with Conan commands in [GitLab CI/CD](../../../ci/README.md), you can +To work with Conan commands in [GitLab CI/CD](../../../ci/index.md), you can use `CI_JOB_TOKEN` in place of the personal access token in your commands. You can provide the `CONAN_LOGIN_USERNAME` and `CONAN_PASSWORD` with each Conan diff --git a/doc/user/packages/container_registry/index.md b/doc/user/packages/container_registry/index.md index d6e86e64e78..eecc17fd60d 100644 --- a/doc/user/packages/container_registry/index.md +++ b/doc/user/packages/container_registry/index.md @@ -135,7 +135,7 @@ To view these commands, go to your project's **Packages & Registries > Container ## Build and push by using GitLab CI/CD -Use [GitLab CI/CD](../../../ci/yaml/README.md) to build and push images to the +Use [GitLab CI/CD](../../../ci/yaml/index.md) to build and push images to the Container Registry. Use it to test, build, and deploy your project from the Docker image you created. @@ -154,7 +154,7 @@ To use CI/CD to authenticate, you can use: docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY ``` -- A [CI job token](../../../ci/triggers/README.md#ci-job-token). +- A [CI job token](../../../ci/triggers/index.md#ci-job-token). ```shell docker login -u $CI_JOB_USER -p $CI_JOB_TOKEN $CI_REGISTRY @@ -210,7 +210,7 @@ build: - docker push $CI_REGISTRY/group/project/image:latest ``` -You can also make use of [other CI/CD variables](../../../ci/variables/README.md) to avoid hard-coding: +You can also make use of [other CI/CD variables](../../../ci/variables/index.md) to avoid hard-coding: ```yaml build: @@ -309,7 +309,7 @@ in addition to the steps in the [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). +1. Add a service [alias](../../../ci/yaml/index.md#servicesalias). Below is an example of what your `.gitlab-ci.yml` should look like: @@ -332,6 +332,36 @@ If you forget to set the service alias, the `docker:19.03.12` image is unable to error during connect: Get http://docker:2376/v1.39/info: dial tcp: lookup docker on 192.168.0.1:53: no such host ``` +### Using a Docker-in-Docker image with Dependency Proxy + +To use your own Docker images with Dependency Proxy, follow these steps +in addition to the steps in the +[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/index.md#servicesalias). + +Below is an example of what your `.gitlab-ci.yml` should look like: + +```yaml +build: + image: ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/docker:19.03.12 + services: + - name: ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/docker:18.09.7-dind + alias: docker + stage: build + script: + - docker build -t my-docker-image . + - docker run my-docker-image /script/to/run/tests +``` + +If you forget to set the service alias, the `docker:19.03.12` image is unable to find the +`dind` service, and an error like the following is thrown: + +```plaintext +error during connect: Get http://docker:2376/v1.39/info: dial tcp: lookup docker on 192.168.0.1:53: no such host +``` + ## Delete images You can delete images from your Container Registry in multiple ways. @@ -533,7 +563,7 @@ You can create a cleanup policy in [the API](#use-the-cleanup-policy-api) or the To create a cleanup policy in the UI: -1. For your project, go to **Settings > CI/CD**. +1. For your project, go to **Settings > Packages & Registries**. 1. Expand the **Clean up image tags** section. 1. Complete the fields. @@ -788,7 +818,7 @@ these steps: the tags' names will be in the `list_o_tags.out` file: ```shell - # Get a list of all tags in a certain container repository while considering [pagination](../../../api/README.md#pagination) + # Get a list of all tags in a certain container repository while considering [pagination](../../../api/index.md#pagination) echo -n "" > list_o_tags.out; for i in {1..N}; do curl --header 'PRIVATE-TOKEN: <PAT>' "https://gitlab.example.com/api/v4/projects/<Project_id>/registry/repositories/<container_repo_id>/tags?per_page=100&page=${i}" | jq '.[].name' | sed 's:^.\(.*\).$:\1:' >> list_o_tags.out; done ``` diff --git a/doc/user/packages/debian_repository/index.md b/doc/user/packages/debian_repository/index.md new file mode 100644 index 00000000000..59213ccb1a0 --- /dev/null +++ b/doc/user/packages/debian_repository/index.md @@ -0,0 +1,111 @@ +--- +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)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5835) in GitLab 14.1. + +WARNING: +The Debian package registry for GitLab is under development and isn't ready for production use due to +limited functionality. + +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). + +## Enable Debian repository feature + +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) +``` + +## Build a Debian package + +Creating a Debian package is documented [on the Debian Wiki](https://wiki.debian.org/Packaging). + +## 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 +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/<project_id>/debian_distributions?codename=unstable +``` + +Example response: + +```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 +fqdn = <login>:<your_access_token>@gitlab.example.com +incoming = /api/v4/projects/<project_id>/packages/debian +EOF + +dput --config=dput.cf --unchecked --no-upload-log gitlab <your_package>.changes +``` + +## Install a package + +The Debian package registry for GitLab is under development, and isn't ready for production use. You +cannot install packages from the registry. However, you can download files directly from the UI. diff --git a/doc/user/packages/dependency_proxy/index.md b/doc/user/packages/dependency_proxy/index.md index 3dd900d2cbe..e2957aff756 100644 --- a/doc/user/packages/dependency_proxy/index.md +++ b/doc/user/packages/dependency_proxy/index.md @@ -123,7 +123,7 @@ Proxy manually without including the port: docker pull gitlab.example.com:443/my-group/dependency_proxy/containers/alpine:latest ``` -You can also use [custom CI/CD variables](../../../ci/variables/README.md#custom-cicd-variables) to store and access your personal access token or other valid credentials. +You can also use [custom CI/CD variables](../../../ci/variables/index.md#custom-cicd-variables) to store and access your personal access token or other valid credentials. ### Store a Docker image in Dependency Proxy cache @@ -134,13 +134,13 @@ To store a Docker image in Dependency Proxy storage: 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. - - Pull an image by tag by adding the image 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/index.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: + - Pull an image by digest by adding the image to your [`.gitlab-ci.yml`](../../../ci/yaml/index.md#image) file: ```shell image: ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/alpine@sha256:c9375e662992791e3f39e919b26f510e5254b42792519c180aad254e6b38f4dc @@ -180,7 +180,7 @@ Watch how to [use the Dependency Proxy to help avoid Docker Hub rate limits](htt In November 2020, Docker introduced [rate limits on pull requests from Docker Hub](https://docs.docker.com/docker-hub/download-rate-limit/). -If your GitLab [CI/CD configuration](../../../ci/README.md) uses +If your GitLab [CI/CD configuration](../../../ci/index.md) uses an image from Docker Hub, each time a job runs, it may count as a pull request. To help get around this limit, you can pull your image from the Dependency Proxy cache instead. @@ -252,3 +252,22 @@ hub_docker_quota_check: - | TOKEN=$(curl "https://auth.docker.io/token?service=registry.docker.io&scope=repository:ratelimitpreview/test:pull" | jq --raw-output .token) && curl --head --header "Authorization: Bearer $TOKEN" "https://registry-1.docker.io/v2/ratelimitpreview/test/manifests/latest" 2>&1 ``` + +## Troubleshooting + +### Dependency Proxy Connection Failure + +If a service alias is not set the `docker:19.03.12` image is unable to find the +`dind` service, and an error like the following is thrown: + +```plaintext +error during connect: Get http://docker:2376/v1.39/info: dial tcp: lookup docker on 192.168.0.1:53: no such host +``` + +This can be resolved by setting a service alias for the Docker service: + +```yaml +services: + - name: ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/docker:18.09.7-dind + alias: docker +``` diff --git a/doc/user/packages/generic_packages/index.md b/doc/user/packages/generic_packages/index.md index e20ac57e64f..cb5258981be 100644 --- a/doc/user/packages/generic_packages/index.md +++ b/doc/user/packages/generic_packages/index.md @@ -20,14 +20,14 @@ Publish generic files, like release binaries, in your project's Package Registry ## Authenticate to the Package Registry -To authenticate to the Package Registry, you need either a [personal access token](../../../api/README.md#personalproject-access-tokens), -[CI/CD job token](../../../api/README.md#gitlab-cicd-job-token), or [deploy token](../../project/deploy_tokens/index.md). +To authenticate to the Package Registry, you need either a [personal access token](../../../api/index.md#personalproject-access-tokens), +[CI/CD job token](../../../api/index.md#gitlab-cicd-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/CD job token](../../../api/README.md#gitlab-cicd-job-token), or a [deploy token](../../project/deploy_tokens/index.md). +may be any value, and the `password` must be either a [personal access token](../../../api/index.md#personalproject-access-tokens), +a [CI/CD job token](../../../api/index.md#gitlab-cicd-job-token), or a [deploy token](../../project/deploy_tokens/index.md). ## Publish a package file @@ -37,7 +37,7 @@ If a package with the same name, version, and filename already exists, it is als 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. +- You need to [authenticate with the API](../../../api/index.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?status=:status @@ -45,7 +45,7 @@ PUT /projects/:id/packages/generic/:package_name/:package_version/:file_name?sta | Attribute | Type | Required | Description | | -------------------| --------------- | ---------| -------------------------------------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../../../api/README.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../../../api/index.md#namespaced-path-encoding). | | `package_name` | string | yes | The package name. It can contain only lowercase letters (`a-z`), uppercase letter (`A-Z`), numbers (`0-9`), dots (`.`), hyphens (`-`), or underscores (`_`). | `package_version` | string | yes | The package version. The following regex validates this: `\A(\.?[\w\+-]+\.?)+\z`. You can test your version strings on [Rubular](https://rubular.com/r/aNCV0wG5K14uq8). | `file_name` | string | yes | The filename. It can contain only lowercase letters (`a-z`), uppercase letter (`A-Z`), numbers (`0-9`), dots (`.`), hyphens (`-`), or underscores (`_`). @@ -77,7 +77,7 @@ If multiple packages have the same name, version, and filename, then the most re Prerequisites: -- 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. +- You need to [authenticate with the API](../../../api/index.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 @@ -85,7 +85,7 @@ GET /projects/:id/packages/generic/:package_name/:package_version/:file_name | Attribute | Type | Required | Description | | -------------------| --------------- | ---------| ------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../../../api/README.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../../../api/index.md#namespaced-path-encoding). | | `package_name` | string | yes | The package name. | | `package_version` | string | yes | The package version. | | `file_name` | string | yes | The filename. | @@ -108,7 +108,7 @@ curl --user "user:<your_access_token>" \ ## Publish a generic package by using CI/CD -To work with generic packages in [GitLab CI/CD](../../../ci/README.md), you can use +To work with generic packages in [GitLab CI/CD](../../../ci/index.md), you can use `CI_JOB_TOKEN` in place of the personal access token in your commands. For example: diff --git a/doc/user/packages/go_proxy/index.md b/doc/user/packages/go_proxy/index.md index 36348fcde18..0c04c4a23d0 100644 --- a/doc/user/packages/go_proxy/index.md +++ b/doc/user/packages/go_proxy/index.md @@ -142,7 +142,7 @@ the following documentation: - [Dependency Management in Go](../../../development/go_guide/dependencies.md) - [Go Modules Reference](https://golang.org/ref/mod) - [Documentation (`golang.org`)](https://golang.org/doc/) -- [Learn (`learn.go.dev`)](https://learn.go.dev/) +- [Learn (`go.dev/learn`)](https://go.dev/learn/) ### Set environment variables diff --git a/doc/user/packages/helm_repository/index.md b/doc/user/packages/helm_repository/index.md new file mode 100644 index 00000000000..26d8bf76cd6 --- /dev/null +++ b/doc/user/packages/helm_repository/index.md @@ -0,0 +1,89 @@ +--- +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 +--- + +# Helm charts in the Package Registry **(FREE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18997) in GitLab 14.1. + +WARNING: +The Helm package registry for GitLab is under development and isn't ready for production use due to +limited functionality. + +Publish Helm packages in your project's Package Registry. Then install the +packages whenever you need to use them as a dependency. + +For documentation of the specific API endpoints that Helm package manager +clients use, see the [Helm API documentation](../../../api/packages/helm.md). + +## Build a Helm package + +Creating a Helm package is documented [in the Helm documentation](https://helm.sh/docs/intro/using_helm/#creating-your-own-charts). + +## Authenticate to the Helm repository + +To authenticate to the Helm repository, you need either: + +- A [personal access token](../../../api/index.md#personalproject-access-tokens). +- A [deploy token](../../project/deploy_tokens/index.md). +- A [CI/CD job token](../../../api/index.md#gitlab-cicd-job-token). + +## Publish a package + +Once built, a chart can be uploaded to the `stable` channel with `curl` or `helm-push`: + +- With `curl`: + + ```shell + curl --request POST \ + --form 'chart=@mychart-0.1.0.tgz' \ + --user <username>:<personal_access_token> \ + https://gitlab.example.com/api/v4/projects/1/packages/helm/api/stable/charts + ``` + +- With the [`helm-push`](https://github.com/chartmuseum/helm-push/#readme) plugin: + + ```shell + helm repo add --username <username> --password <personal_access_token> project-1 https://gitlab.example.com/api/v4/projects/1/packages/helm/stable + helm push mychart-0.1.0.tgz project-1 + ``` + +## Use CI/CD to publish a Helm package + +To publish a Helm package automated through [GitLab CI/CD](../../../ci/index.md), you can use +`CI_JOB_TOKEN` in place of the personal access token in your commands. + +For example: + +```yaml +image: curlimages/curl:latest + +stages: + - upload + +upload: + stage: upload + script: + - 'curl --request POST --user gitlab-ci-token:$CI_JOB_TOKEN --form "chart=@mychart-0.1.0.tgz" "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/helm/api/stable/charts"' +``` + +## Install a package + +To install the latest version of a chart, use the following command: + +```shell +helm repo add --username <username> --password <personal_access_token> project-1 https://gitlab.example.com/api/v4/projects/1/packages/helm/stable +helm install my-release project-1/mychart +``` + +If the repo has previously been added, you may need to run: + +```shell +helm repo update +``` + +To update the Helm client with the most currently available charts. + +See [Using Helm](https://helm.sh/docs/intro/using_helm/) for more information. diff --git a/doc/user/packages/index.md b/doc/user/packages/index.md index f0bf2fc3363..9158b5cc674 100644 --- a/doc/user/packages/index.md +++ b/doc/user/packages/index.md @@ -17,6 +17,7 @@ The Package Registry supports the following formats: | [Composer](composer_repository/index.md) | 13.2+ | | [Conan](conan_repository/index.md) | 12.6+ | | [Go](go_proxy/index.md) | 13.1+ | +| [Helm](helm_repository/index.md) | 14.1+ | | [Maven](maven_repository/index.md) | 11.3+ | | [npm](npm_registry/index.md) | 11.7+ | | [NuGet](nuget_repository/index.md) | 12.8+ | @@ -40,7 +41,6 @@ guides you through the process. | Conda | [#36891](https://gitlab.com/gitlab-org/gitlab/-/issues/36891) | | CRAN | [#36892](https://gitlab.com/gitlab-org/gitlab/-/issues/36892) | | 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) | diff --git a/doc/user/packages/infrastructure_registry/index.md b/doc/user/packages/infrastructure_registry/index.md index 00370bd2f48..86b85d0c9f5 100644 --- a/doc/user/packages/infrastructure_registry/index.md +++ b/doc/user/packages/infrastructure_registry/index.md @@ -35,7 +35,7 @@ documentation for your package type: ## Use GitLab CI/CD to build packages -To use [GitLab CI/CD](../../../ci/README.md) to build packages, you can +To use [GitLab CI/CD](../../../ci/index.md) to build packages, you can authenticate with the [`CI_JOB_TOKEN` predefined variable](../../../ci/variables/predefined_variables.md). CI/CD templates, which you can use to get started, are in [this repository](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates). diff --git a/doc/user/packages/maven_repository/index.md b/doc/user/packages/maven_repository/index.md index 2567cc3b828..70b9c28da76 100644 --- a/doc/user/packages/maven_repository/index.md +++ b/doc/user/packages/maven_repository/index.md @@ -412,7 +412,7 @@ repositories { - The `PROJECT_ID` is your project ID, which you can view on your project's home page. - Replace `gitlab.example.com` with your domain name. - For retrieving artifacts, use either the - [URL-encoded](../../../api/README.md#namespaced-path-encoding) path of the project + [URL-encoded](../../../api/index.md#namespaced-path-encoding) path of the project (like `group%2Fproject`) or the project's ID (like `42`). However, only the project's ID can be used for publishing. @@ -471,7 +471,7 @@ repositories { - For `PROJECT_ID`, use your project ID, which you can view on your project's home page. - Replace `gitlab.example.com` with your domain name. - For retrieving artifacts, use either the - [URL-encoded](../../../api/README.md#namespaced-path-encoding) path of the group + [URL-encoded](../../../api/index.md#namespaced-path-encoding) path of the group (like `group%2Fsubgroup`) or the group's ID (like `12`). ### Instance-level Maven endpoint @@ -530,7 +530,7 @@ repositories { - The `PROJECT_ID` is your project ID, which you can view on your project's home page. - Replace `gitlab.example.com` with your domain name. - For retrieving artifacts, use either the - [URL-encoded](../../../api/README.md#namespaced-path-encoding) path of the project + [URL-encoded](../../../api/index.md#namespaced-path-encoding) path of the project (like `group%2Fproject`) or the project's ID (like `42`). However, only the project's ID can be used for publishing. @@ -745,7 +745,7 @@ You can create a new package each time the `master` branch is updated. <repositories> <repository> <id>gitlab-maven</id> - <url>$env{CI_API_V4_URL}/projects/${env.CI_PROJECT_ID}/packages/maven</url> + <url>${env.CI_API_V4_URL}/projects/${env.CI_PROJECT_ID}/packages/maven</url> </repository> </repositories> <distributionManagement> @@ -813,6 +813,19 @@ You can play around with the regex and try your version strings on [this regular ## Troubleshooting +To improve performance, Maven caches files related to a package. If you encounter issues, clear +the cache with these commands: + +```shell +rm -rf ~/.m2/repository +``` + +If you're using Gradle, run this command to clear the cache: + +```shell +rm -rf ~/.gradle/caches +``` + ### Review network trace logs If you are having issues with the Maven Repository, you may want to review network trace logs. diff --git a/doc/user/packages/npm_registry/index.md b/doc/user/packages/npm_registry/index.md index 735873be237..1e5c294689b 100644 --- a/doc/user/packages/npm_registry/index.md +++ b/doc/user/packages/npm_registry/index.md @@ -90,7 +90,7 @@ 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 [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. + 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). @@ -205,7 +205,7 @@ Then, you can run `npm publish` either locally or by using GitLab CI/CD. NPM_TOKEN=<your_token> npm publish ``` -- **GitLab CI/CD:** Set an `NPM_TOKEN` [CI/CD variable](../../../ci/variables/README.md) +- **GitLab CI/CD:** Set an `NPM_TOKEN` [CI/CD variable](../../../ci/variables/index.md) under your project's **Settings > CI/CD > Variables**. ## Package naming convention @@ -287,7 +287,7 @@ Prerequisites: It must match exactly, including the case. This is different than the npm naming convention, but it is required to work with the GitLab Package Registry. -To work with npm commands within [GitLab CI/CD](../../../ci/README.md), you can use +To work with npm commands within [GitLab CI/CD](../../../ci/index.md), you can use `CI_JOB_TOKEN` in place of the personal access token or deploy token in your commands. An example `.gitlab-ci.yml` file for publishing npm packages: @@ -311,8 +311,7 @@ step-by-step guide and demo project for a complete example. ## Configure the GitLab npm registry with Yarn 2 -You can get started with Yarn 2 by following the documentation at -[https://yarnpkg.com/getting-started/install](https://yarnpkg.com/getting-started/install). +You can get started with Yarn 2 by following the [Yarn documentation](https://yarnpkg.com/getting-started/install/). To publish and install with the project-level npm endpoint, set the following configuration in `.yarnrc.yml`: @@ -456,6 +455,14 @@ Due to a bug in npm 6.9.0, deleting distribution tags fails. Make sure your npm When troubleshooting npm issues, first run the same command with the `--verbose` flag to confirm what registry you are hitting. +To improve performance, npm caches files related to a package. Note that npm doesn't remove data by +itself. The cache grows as new packages are installed. If you encounter issues, clear the cache with +this command: + +```shell +npm cache clean --force +``` + ### Error running Yarn with the Package Registry for npm registry If you are using [Yarn](https://classic.yarnpkg.com/en/) with the npm registry, you may get @@ -512,7 +519,7 @@ And the `.npmrc` file should look like: ### `npm install` returns `Error: Failed to replace env in config: ${npm_TOKEN}` -You do not need a token to run `npm install` unless your project is private. The token is only required to publish. If the `.npmrc` file was checked in with a reference to `$npm_TOKEN`, you can remove it. If you prefer to leave the reference in, you must set a value prior to running `npm install` or set the value by using [GitLab CI/CD variables](../../../ci/variables/README.md): +You do not need a token to run `npm install` unless your project is private. The token is only required to publish. If the `.npmrc` file was checked in with a reference to `$npm_TOKEN`, you can remove it. If you prefer to leave the reference in, you must set a value prior to running `npm install` or set the value by using [GitLab CI/CD variables](../../../ci/variables/index.md): ```shell NPM_TOKEN=<your_token> npm install @@ -532,12 +539,24 @@ 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 +If you get this error, one of the following problems could be causing it. + +#### Package name does not meet the naming convention + +Your package name may not meet the [`@scope/package-name` package naming convention](#package-naming-convention). Ensure the name meets the convention exactly, including the case. Then try to publish again. +#### Package already exists + +Your package has already been published to another project in the same +root namespace and therefore cannot be published again using the same name. + +This is also true even if the prior published package shares the same name, +but not the version. + ### `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 diff --git a/doc/user/packages/nuget_repository/index.md b/doc/user/packages/nuget_repository/index.md index f19d565ef36..46cfd763668 100644 --- a/doc/user/packages/nuget_repository/index.md +++ b/doc/user/packages/nuget_repository/index.md @@ -8,6 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20050) in GitLab Premium 12.8. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. +> - Symbol package support [added](https://gitlab.com/gitlab-org/gitlab/-/issues/262081) in GitLab 14.1. Publish NuGet packages in your project's Package Registry. Then, install the packages whenever you need to use them as a dependency. @@ -28,7 +29,7 @@ The required minimum versions are: - [NuGet CLI 5.1 or later](https://www.nuget.org/downloads). If you have [Visual Studio](https://visualstudio.microsoft.com/vs/), the NuGet CLI is probably already installed. -- Alternatively, you can use [.NET SDK 3.0 or later](https://dotnet.microsoft.com/download/dotnet-core/3.0), +- Alternatively, you can use [.NET SDK 3.0 or later](https://dotnet.microsoft.com/download/dotnet/3.0), which installs the NuGet CLI. - NuGet protocol version 3 or later. @@ -336,7 +337,7 @@ updated: stage: deploy script: - dotnet pack -c Release - - dotnet nuget add source "${CI_API_V4_URL}/${CI_PROJECT_ID}/packages/nuget/index.json" --name gitlab --username gitlab-ci-token --password $CI_JOB_TOKEN --store-password-in-clear-text + - dotnet nuget add source "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/nuget/index.json" --name gitlab --username gitlab-ci-token --password $CI_JOB_TOKEN --store-password-in-clear-text - dotnet nuget push "bin/Release/*.nupkg" --source gitlab only: - master @@ -394,6 +395,24 @@ dotnet add package <package_id> \ - `<package_id>` is the package ID. - `<package_version>` is the package version. Optional. +## Symbol packages + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/262081) in GitLab 14.1. + +If you push a `.nupkg`, symbol package files in the `.snupkg` format are uploaded automatically. You +can also push them manually: + +```shell +nuget push My.Package.snupkg -Source <source_name> +``` + +Consuming symbol packages is not yet guaranteed using clients such as Visual Studio or +dotnet-symbol. The `.snupkg` files are available for download through the UI or the +[API](../../../api/packages/nuget.md#download-a-package-file). + +Follow the [NuGet symbol package issue](https://gitlab.com/gitlab-org/gitlab/-/issues/262081) +for further updates. + ## Supported CLI commands The GitLab NuGet repository supports the following commands for the NuGet CLI (`nuget`) and the .NET @@ -403,3 +422,12 @@ CLI (`dotnet`): - `dotnet nuget push`: Upload a package to the registry. - `nuget install`: Install a package from the registry. - `dotnet add`: Install a package from the registry. + +## Troubleshooting + +To improve performance, NuGet caches files related to a package. If you encounter issues, clear the +cache with this command: + +```shell +nuget locals all -clear +``` diff --git a/doc/user/packages/package_registry/index.md b/doc/user/packages/package_registry/index.md index 52ce7d62940..cb4e677687e 100644 --- a/doc/user/packages/package_registry/index.md +++ b/doc/user/packages/package_registry/index.md @@ -34,8 +34,8 @@ For information on how to create and upload a package, view the GitLab documenta ## Use GitLab CI/CD to build packages -You can use [GitLab CI/CD](../../../ci/README.md) to build packages. -For Maven, NuGet, npm, Conan, and PyPI packages, and Composer dependencies, you can +You can use [GitLab CI/CD](../../../ci/index.md) to build packages. +For Maven, NuGet, npm, Conan, Helm, and PyPI packages, and Composer dependencies, you can authenticate with GitLab by using the `CI_JOB_TOKEN`. CI/CD templates, which you can use to get started, are in [this repository](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates). @@ -94,7 +94,7 @@ To delete package files in the UI, from your group or project: 1. Go to **Packages & Registries > Package Registry**. 1. Find the name of the package you want to delete. 1. Select the package to view additional details. -1. Find the name of the file you would like to delete. +1. Find the name of the file you would like to delete. 1. Expand the ellipsis and select **Delete file**. The package files are permanently deleted. diff --git a/doc/user/packages/pypi_repository/index.md b/doc/user/packages/pypi_repository/index.md index 2dd00fdc273..30d61770094 100644 --- a/doc/user/packages/pypi_repository/index.md +++ b/doc/user/packages/pypi_repository/index.md @@ -204,7 +204,7 @@ Your project ID is on your project's home page. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/202012) in GitLab 13.4. -To work with PyPI commands within [GitLab CI/CD](../../../ci/README.md), you +To work with PyPI commands within [GitLab CI/CD](../../../ci/index.md), you can use `CI_JOB_TOKEN` instead of a personal access token or deploy token. For example: @@ -320,7 +320,7 @@ python -m twine upload --repository <source_name> dist/<package_file> 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. +more than once, a `400 Bad Request` error occurs. ## Install a PyPI package diff --git a/doc/user/packages/rubygems_registry/index.md b/doc/user/packages/rubygems_registry/index.md index 743bc229e11..2a0fea6e0ef 100644 --- a/doc/user/packages/rubygems_registry/index.md +++ b/doc/user/packages/rubygems_registry/index.md @@ -74,7 +74,7 @@ https://gitlab.example.com/api/v4/projects/<project_id>/packages/rubygems: '<you ### Authenticate with a CI job token -To work with RubyGems commands within [GitLab CI/CD](../../../ci/README.md), +To work with RubyGems commands within [GitLab CI/CD](../../../ci/index.md), you can use `CI_JOB_TOKEN` instead of a personal access token or deploy token. For example: diff --git a/doc/user/packages/terraform_module_registry/index.md b/doc/user/packages/terraform_module_registry/index.md index efb2b8ddf8e..1365f401506 100644 --- a/doc/user/packages/terraform_module_registry/index.md +++ b/doc/user/packages/terraform_module_registry/index.md @@ -15,8 +15,8 @@ as a Terraform module registry. To authenticate to the Terraform module registry, you need either: -- A [personal access token](../../../api/README.md#personalproject-access-tokens) with at least `read_api` rights. -- A [CI/CD job token](../../../api/README.md#gitlab-cicd-job-token). +- A [personal access token](../../../api/index.md#personalproject-access-tokens) with at least `read_api` rights. +- A [CI/CD job token](../../../api/index.md#gitlab-cicd-job-token). ## Publish a Terraform Module @@ -26,7 +26,7 @@ If a package with the same name and version already exists, it will not be creat 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. +- You need to [authenticate with the API](../../../api/index.md#authentication). If authenticating with a deploy token, it must be configured with the `write_package_registry` scope. ```plaintext PUT /projects/:id/packages/terraform/modules/:module_name/:module_system/:module_version/file @@ -34,7 +34,7 @@ PUT /projects/:id/packages/terraform/modules/:module_name/:module_system/:module | Attribute | Type | Required | Description | | -------------------| --------------- | ---------| -------------------------------------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../../../api/README.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../../../api/index.md#namespaced-path-encoding). | | `module_name` | string | yes | The package name. It can contain only lowercase letters (`a-z`), uppercase letter (`A-Z`), numbers (`0-9`), or hyphens (`-`). | `module_system` | string | yes | The package name. It can contain only lowercase letters (`a-z`), uppercase letter (`A-Z`), numbers (`0-9`), or hyphens (`-`). | `module_version` | string | yes | The package version. It must be valid according to the [Semantic Versioning Specification](https://semver.org/). @@ -77,7 +77,7 @@ Example response: Prerequisites: -- You need to [authenticate with the API](../../../api/README.md#authentication). If authenticating with a personal access token, it must be configured with the `read_api` scope. +- You need to [authenticate with the API](../../../api/index.md#authentication). If authenticating with a personal access token, it must be configured with the `read_api` scope. Authentication tokens (Job Token or Personal Access Token) can be provided for `terraform` in your `~/.terraformrc` file: @@ -99,7 +99,7 @@ module "<module>" { ## Publish a Terraform module by using CI/CD -To work with Terraform modules in [GitLab CI/CD](../../../ci/README.md), you can use +To work with Terraform modules in [GitLab CI/CD](../../../ci/index.md), you can use `CI_JOB_TOKEN` in place of the personal access token in your commands. For example: |