diff options
Diffstat (limited to 'doc/user/packages')
| -rw-r--r-- | doc/user/packages/composer_repository/index.md | 25 | ||||
| -rw-r--r-- | doc/user/packages/conan_repository/index.md | 59 | ||||
| -rw-r--r-- | doc/user/packages/container_registry/index.md | 226 | ||||
| -rw-r--r-- | doc/user/packages/dependency_proxy/index.md | 14 | ||||
| -rw-r--r-- | doc/user/packages/go_proxy/index.md | 7 | ||||
| -rw-r--r-- | doc/user/packages/index.md | 125 | ||||
| -rw-r--r-- | doc/user/packages/maven_repository/index.md | 41 | ||||
| -rw-r--r-- | doc/user/packages/npm_registry/index.md | 39 | ||||
| -rw-r--r-- | doc/user/packages/nuget_repository/index.md | 58 | ||||
| -rw-r--r-- | doc/user/packages/package_registry/img/package_activity_v12_10.png (renamed from doc/user/packages/img/package_activity_v12_10.png) | bin | 14515 -> 14515 bytes | |||
| -rw-r--r-- | doc/user/packages/package_registry/index.md | 93 | ||||
| -rw-r--r-- | doc/user/packages/pypi_repository/index.md | 23 | ||||
| -rw-r--r-- | doc/user/packages/workflows/monorepo.md | 51 | ||||
| -rw-r--r-- | doc/user/packages/workflows/project_registry.md | 6 |
14 files changed, 438 insertions, 329 deletions
diff --git a/doc/user/packages/composer_repository/index.md b/doc/user/packages/composer_repository/index.md index 542efba1fae..9b1f23f6d59 100644 --- a/doc/user/packages/composer_repository/index.md +++ b/doc/user/packages/composer_repository/index.md @@ -4,9 +4,10 @@ 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/#designated-technical-writers --- -# GitLab Composer Repository **(PREMIUM)** +# GitLab Composer Repository -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15886) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15886) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. With the GitLab Composer Repository, every project can have its own space to store [Composer](https://getcomposer.org/) packages. @@ -14,9 +15,9 @@ With the GitLab Composer Repository, every project can have its own space to sto NOTE: **Note:** This option is available only if your GitLab administrator has -[enabled support for the Package Registry](../../../administration/packages/index.md). **(PREMIUM ONLY)** +[enabled support for the Package Registry](../../../administration/packages/index.md). -After the Composer Repository is enabled, it will be available for all new projects +When the Composer Repository is enabled, it is available for all new projects by default. To enable it for existing projects, or if you want to disable it: 1. Navigate to your project's **Settings > General > Visibility, project features, permissions**. @@ -27,10 +28,10 @@ You should then be able to see the **Packages & Registries** section on the left ## Getting started -This section will cover creating a new example Composer package to publish. This is a +This section covers creating a new example Composer package to publish. This is a quickstart to test out the **GitLab Composer Registry**. -You will need a recent version of [Composer](https://getcomposer.org/). +To complete this section, you need a recent version of [Composer](https://getcomposer.org/). ### Creating a package project @@ -68,19 +69,21 @@ git init git add composer.json git commit -m 'Composer package test' git tag v1.0.0 -git add origin git@gitlab.com:<namespace>/<project-name>.git +git remote add origin git@gitlab.com:<namespace>/<project-name>.git +git push --set-upstream origin master git push origin v1.0.0 ``` ### Publishing the package Now that the basics of our project is completed, we can publish the package. -For accomplishing this you will need the following: +To publish the package, you need: - A personal access token. You can generate a [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to `api` for repository authentication. - Your project ID which can be found on the home page of your project. -To publish the package hosted on GitLab we'll need to make a `POST` to the GitLab package API using a tool like `curl`: +To publish the package hosted on GitLab, make a `POST` request to the GitLab package API. +A tool like `curl` can be used to make this request: ```shell curl --data tag=<tag> 'https://__token__:<personal-access-token>@gitlab.com/api/v4/projects/<project_id>/packages/composer' @@ -96,7 +99,7 @@ If the above command succeeds, you now should be able to see the package under t ### Installing a package -To install your package you will need: +To install your package, you need: - A personal access token. You can generate a [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to `api` for repository authentication. - Your group ID which can be found on the home page of your project's group. @@ -123,7 +126,7 @@ Where: - `<package_name>` is your package name as defined in your package's `composer.json` file. - `<version>` is your package version (`1.0.0` in this example). -You will also need to create a `auth.json` file with your GitLab credentials: +You also need to create a `auth.json` file with your GitLab credentials: ```json { diff --git a/doc/user/packages/conan_repository/index.md b/doc/user/packages/conan_repository/index.md index 41b420ce7f6..e8014ad2b84 100644 --- a/doc/user/packages/conan_repository/index.md +++ b/doc/user/packages/conan_repository/index.md @@ -4,9 +4,10 @@ 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/#designated-technical-writers --- -# GitLab Conan Repository **(PREMIUM)** +# GitLab Conan Repository -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8248) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.6. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8248) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.6. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. With the GitLab Conan Repository, every project can have its own space to store Conan packages. @@ -17,9 +18,9 @@ project can have its own space to store Conan packages. NOTE: **Note:** This option is available only if your GitLab administrator has -[enabled support for the Conan Repository](../../../administration/packages/index.md).**(PREMIUM ONLY)** +[enabled support for the Conan Repository](../../../administration/packages/index.md). -After the Conan Repository is enabled, it will be available for all new projects +After the Conan Repository is enabled, it's available for all new projects by default. To enable it for existing projects, or if you want to disable it: 1. Navigate to your project's **Settings > General > Visibility, project features, permissions**. @@ -30,7 +31,7 @@ You should then be able to see the **Packages & Registries** section on the left ## Getting started -This section will cover installing Conan and building a package for your C/C++ project. This is a quickstart if you are new +This section covers installing Conan and building a package for your C/C++ project. This is a quickstart if you're new to Conan. If you already are using Conan and understand how to build your own packages, move on to the [next section](#adding-the-gitlab-package-registry-as-a-conan-remote). ### Installing Conan @@ -65,10 +66,10 @@ instructions at [cmake.org](https://cmake.org/install/) for your operating syste ### Creating a project -Understanding what is needed to create a valid and compilable C++ project is out of the scope of this guide, but if you are new to C++ and want to try out the GitLab +Understanding what is needed to create a valid and compilable C++ project is out of the scope of this guide, but if you're new to C++ and want to try out the GitLab package registry, Conan.io has a great [hello world starter project](https://github.com/conan-io/hello) that you can clone to get started. -Clone the repo and it can be used for the rest of the tutorial if you don't have your own C++ project. +Clone the repository and it can be used for the rest of the tutorial if you don't have your own C++ project. ### Building a package @@ -79,7 +80,7 @@ package name and version: conan new Hello/0.1 -t ``` -Next, you will create a package for that recipe by running `conan create` providing the Conan user and channel: +Next, create a package for that recipe by running `conan create` providing the Conan user and channel: ```shell conan create . my-org+my-group+my-project/beta @@ -90,11 +91,11 @@ Current [naming restrictions](#package-recipe-naming-convention) require you to The example above would create a package belonging to this project: `https://gitlab.com/my-org/my-group/my-project` with a channel of `beta`. -These two example commands will generate a final package with the recipe `Hello/0.1@my-org+my-group+my-project/beta`. +These two example commands generate a final package with the recipe `Hello/0.1@my-org+my-group+my-project/beta`. For more advanced details on creating and managing your packages, refer to the [Conan docs](https://docs.conan.io/en/latest/creating_packages.html). -You are now ready to upload your package to the GitLab registry. To get started, first you will need to set GitLab as a remote, then you will need to add a Conan user for that remote to authenticate your requests. +You are now ready to upload your package to the GitLab registry. To get started, first you need to set GitLab as a remote. Then you need to add a Conan user for that remote to authenticate your requests. ## Adding the GitLab Package Registry as a Conan remote @@ -114,7 +115,7 @@ conan search Hello* --all --remote=gitlab ## Authenticating to the GitLab Conan Repository -You will need a personal access token or deploy token. +You need a personal access token or deploy token. For repository authentication: @@ -123,7 +124,7 @@ For repository authentication: ### Adding a Conan user to the GitLab remote -Once you have a personal access token and have [set your Conan remote](#adding-the-gitlab-package-registry-as-a-conan-remote), you can associate the token with the remote so you do not have to explicitly add them to each Conan command you run: +Once you have a personal access token and have [set your Conan remote](#adding-the-gitlab-package-registry-as-a-conan-remote), you can associate the token with the remote so you don't have to explicitly add them to each Conan command you run: ```shell conan user <gitlab_username or deploy_token_username> -r gitlab -p <personal_access_token or deploy_token> @@ -132,10 +133,10 @@ conan user <gitlab_username or deploy_token_username> -r gitlab -p <personal_acc NOTE: **Note:** If you named your remote something other than `gitlab`, your remote name should be used in this command instead of `gitlab`. -From now on, when you run commands using `--remote=gitlab`, your username and password will automatically be included in the requests. +From now on, when you run commands using `--remote=gitlab`, your username and password is automatically included in the requests. NOTE: **Note:** -The personal access token is not stored locally at any moment. Conan uses JWT, so when you run this command, Conan will request an expirable token from GitLab using your token. The JWT does expire on a regular basis, so you will need to re-enter your personal access token when that happens. +The personal access token is not stored locally at any moment. Conan uses JSON Web Tokens (JWT), so when you run this command, Conan requests an expirable token from GitLab using your token. The JWT does expire on a regular basis, so you need to re-enter your personal access token when that happens. Alternatively, you could explicitly include your credentials in any given command. For example: @@ -156,7 +157,7 @@ NOTE: **Note:** The package recipe does include the version, so setting the default remote for `Hello/0.1@user/channel` will not work for `Hello/0.2@user/channel`. This functionality is best suited for when you want to consume or install packages from the GitLab registry without having to specify a remote. -The rest of the example commands in this documentation assume that you have added a Conan user with your credentials to the `gitlab` remote and will not include the explicit credentials or remote option, but be aware that any of the commands could be run without having added a user or default remote: +The rest of the example commands in this documentation assume that you've added a Conan user with your credentials to the `gitlab` remote and will not include the explicit credentials or remote option. With that said, be aware that any of the commands could be run without having added a user or default remote: ```shell `CONAN_LOGIN_USERNAME=<gitlab_username or deploy_token_username> CONAN_PASSWORD=<personal_access_token or deploy_token> <conan command> --remote=gitlab @@ -166,7 +167,7 @@ The rest of the example commands in this documentation assume that you have adde First you need to [create your Conan package locally](https://docs.conan.io/en/latest/creating_packages/getting_started.html). In order to work with the GitLab Package Registry, a specific [naming convention](#package-recipe-naming-convention) must be followed. -Ensure you have a project created on GitLab and that the personal access token you are using has the correct permissions for write access to the container registry by selecting the `api` [scope](../../../user/profile/personal_access_tokens.md#limiting-scopes-of-a-personal-access-token). +Ensure you have a project created on GitLab and that the personal access token you're using has the correct permissions for write access to the container registry by selecting the `api` [scope](../../../user/profile/personal_access_tokens.md#limiting-scopes-of-a-personal-access-token). You can upload your package to the GitLab Package Registry using the `conan upload` command: @@ -180,7 +181,7 @@ Standard Conan recipe convention looks like `package_name/version@user/channel`. **The recipe user must be the `+` separated project path**. The package name may be anything, but it is preferred that the project name be used unless -it is not possible due to a naming collision. For example: +it's not possible due to a naming collision. For example: | Project | Package | Supported | | ---------------------------------- | ----------------------------------------------- | --------- | @@ -190,7 +191,7 @@ it is not possible due to a naming collision. For example: | `gitlab-org/gitlab-ce` | `my-package/1.0.0@foo/stable` | No | NOTE: **Note:** -A future iteration will extend support to [project and group level](https://gitlab.com/gitlab-org/gitlab/-/issues/11679) remotes which will allow for more flexible naming conventions. +A future iteration will extend support to [project and group level](https://gitlab.com/gitlab-org/gitlab/-/issues/11679) remotes which allows for more flexible naming conventions. ## Installing a package @@ -222,7 +223,7 @@ conan install .. ``` NOTE: **Note:** -If you are trying to install the package you just created in this tutorial, not much will happen since that package +If you're trying to install the package you just created in this tutorial, not much will happen since that package already exists on your local machine. ## Removing a package @@ -235,11 +236,11 @@ There are two ways to remove a Conan package from the GitLab Package Registry. conan remove Hello/0.2@user/channel --remote=gitlab ``` - You need to explicitly include the remote in this command, otherwise the package will only be removed from your + You need to explicitly include the remote in this command, otherwise the package is only removed from your local system cache. NOTE: **Note:** - This command will remove all recipe and binary package files from the Package Registry. + This command removes all recipe and binary package files from the Package Registry. - **GitLab project interface**: in the packages view of your project page, you can delete packages by clicking the red trash icons. @@ -247,7 +248,7 @@ There are two ways to remove a Conan package from the GitLab Package Registry. The `conan search` command can be run searching by full or partial package name, or by exact recipe. -To search using a partial name, use the wildcard symbol `*`, which should be placed at the end of your search (e.g., `my-packa*`): +To search using a partial name, use the wildcard symbol `*`, which should be placed at the end of your search (for example, `my-packa*`): ```shell conan search Hello --all --remote=gitlab @@ -255,11 +256,11 @@ conan search He* --all --remote=gitlab conan search Hello/0.1@my-group+my-project/beta --all --remote=gitlab ``` -The scope of your search will include all projects you have permission to access, this includes your private projects as well as all public projects. +The scope of your search includes all projects you have permission to access, this includes your private projects as well as all public projects. ## Fetching Conan package information from the GitLab Package Registry -The `conan info` command will return information about a given package: +The `conan info` command returns information about a given package: ```shell conan info Hello/0.1@my-group+my-project/beta @@ -282,8 +283,8 @@ The GitLab Conan repository supports the following Conan CLI commands: To work with Conan commands within [GitLab CI/CD](./../../../ci/README.md), you can use `CI_JOB_TOKEN` in place of the personal access token in your commands. -It is easiest to provide the `CONAN_LOGIN_USERNAME` and `CONAN_PASSWORD` with each -Conan command in your `.gitlab-ci.yml` file: +It's easiest to provide the `CONAN_LOGIN_USERNAME` and `CONAN_PASSWORD` with each +Conan command in your `.gitlab-ci.yml` file. For example: ```yaml image: conanio/gcc7 @@ -292,8 +293,10 @@ create_package: stage: deploy script: - conan remote add gitlab https://gitlab.example.com/api/v4/packages/conan - - conan create . my-group+my-project/beta - - CONAN_LOGIN_USERNAME=ci_user CONAN_PASSWORD=${CI_JOB_TOKEN} conan upload Hello/0.1@root+ci-conan/beta1 --all --remote=gitlab + - conan new <package-name>/0.1 -t + - conan create . <group-name>+<project-name>/stable + - CONAN_LOGIN_USERNAME=ci_user CONAN_PASSWORD=${CI_JOB_TOKEN} conan upload <package-name>/0.1@<group-name>+<project-name>/stable --all --remote=gitlab + ``` You can find additional Conan images to use as the base of your CI file diff --git a/doc/user/packages/container_registry/index.md b/doc/user/packages/container_registry/index.md index 429d29b7677..f46ad99e573 100644 --- a/doc/user/packages/container_registry/index.md +++ b/doc/user/packages/container_registry/index.md @@ -49,7 +49,7 @@ project: 1. Expand the **Visibility, project features, permissions** section and enable the **Container Registry** feature on your project. For new projects this might be enabled by default. For existing projects - (prior GitLab 8.8), you will have to explicitly enable it. + (prior GitLab 8.8), enable it explicitly. 1. Press **Save changes** for the changes to take effect. You should now be able to see the **Packages & Registries > Container Registry** link in the sidebar. @@ -64,14 +64,14 @@ Navigate to your project's **{package}** **Packages & Registries > Container Reg  -This view will: +This view allows you to: - Show all the image repositories that belong to the project. -- Allow you to filter image repositories by their name. -- Allow you to [delete](#delete-images-from-within-gitlab) one or more image repository. -- Allow you to navigate to the image repository details page. +- Filter image repositories by their name. +- [Delete](#delete-images-from-within-gitlab) one or more image repository. +- Navigate to the image repository details page. - Show a **Quick start** dropdown with the most common commands to log in, build and push -- Optionally, a banner will be visible if the [cleanup policy](#cleanup-policy) is enabled for this project. +- Show a banner if the optional [cleanup policy](#cleanup-policy) is enabled for this project. ### Control Container Registry for your group @@ -79,15 +79,15 @@ Navigate to your groups's **{package}** **Packages & Registries > Container Regi  -This view will: +This view allows you to: - Show all the image repositories of the projects that belong to this group. -- Allow to [delete](#delete-images-from-within-gitlab) one or more image repositories. -- Allow to navigate to a specific image repository details page. +- [Delete](#delete-images-from-within-gitlab) one or more image repositories. +- Navigate to a specific image repository details page. ### Image Repository details page -Clicking on the name of any image repository will navigate to the details. +Clicking on the name of any image repository navigates to the details.  @@ -133,8 +133,10 @@ enabled in your account, you need to pass a [personal access token](../../profile/personal_access_tokens.md) instead of your password in order to login to GitLab's Container Registry. -If a project is private, credentials will need to be provided for authorization. -There are two ways to do this: +Credentials must be provided for authorization to any non-public registry. Only project members can access private, +GitLab-hosted registries. + +There are two ways to authenticate: - By using a [personal access token](../../profile/personal_access_tokens.md). - By using a [deploy token](../../project/deploy_tokens/index.md). @@ -158,7 +160,7 @@ docker build -t registry.example.com/group/project/image . docker push registry.example.com/group/project/image ``` -Your image will be named after the following scheme: +Your image is named after the following scheme: ```plaintext <registry URL>/<namespace>/<project>/<image> @@ -175,8 +177,8 @@ registry.example.com/group/project/my/image:rc1 ## Build and push images using GitLab CI/CD -While you can build and push your images from your local machine, the true -power of the Container Registry comes when you combine it with GitLab CI/CD. +While you can build and push your images from your local machine, take +full advantage of the Container Registry by combining it with GitLab CI/CD. You can then create workflows and automate any processes that involve testing, building, and eventually deploying your project from the Docker image you created. @@ -192,7 +194,7 @@ Before diving into the details, some things you should be aware of: - Doing an explicit `docker pull` before each `docker run` fetches the latest image that was just built. This is especially important if you are using multiple Runners that cache images locally. Using the Git SHA in your - image tag makes this less necessary since each job will be unique and you + image tag makes this less necessary since each job is unique and you shouldn't ever have a stale image. However, it's still possible to have a stale image if you re-build a given commit after a dependency has changed. - You don't want to build directly to `latest` tag in case there are multiple jobs @@ -201,10 +203,7 @@ Before diving into the details, some things you should be aware of: ### Authenticating to the Container Registry with GitLab CI/CD There are three ways to authenticate to the Container Registry via -[GitLab CI/CD](../../../ci/yaml/README.md) which depend on the visibility of -your project. - -Available for all projects, though more suitable for public ones: +[GitLab CI/CD](../../../ci/yaml/README.md): - **Using the special `CI_REGISTRY_USER` variable**: The user specified by this variable is created for you in order to push to the Registry connected to your project. Its password is automatically @@ -216,14 +215,22 @@ Available for all projects, though more suitable for public ones: docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY ``` -For private and internal projects: +- **Using the GitLab Deploy Token**: You can create and use a + [special deploy token](../../project/deploy_tokens/index.md#gitlab-deploy-token) + with your projects. + Once created, you can use the special environment variables, and GitLab CI/CD + fills them in for you. You can use the following example as-is: + + ```shell + docker login -u $CI_DEPLOY_USER -p $CI_DEPLOY_PASSWORD $CI_REGISTRY + ``` - **Using a personal access token**: You can create and use a [personal access token](../../profile/personal_access_tokens.md) in case your project is private: - For read (pull) access, the scope should be `read_registry`. - - For read/write (pull/push) access, use `api`. + - For write (push) access, the scope should be `write_registry`. Replace the `<username>` and `<access_token>` in the following example: @@ -231,16 +238,6 @@ For private and internal projects: docker login -u <username> -p <access_token> $CI_REGISTRY ``` -- **Using the GitLab Deploy Token**: You can create and use a - [special deploy token](../../project/deploy_tokens/index.md#gitlab-deploy-token) - with your private projects. It provides read-only (pull) access to the Registry. - Once created, you can use the special environment variables, and GitLab CI/CD - will fill them in for you. You can use the following example as-is: - - ```shell - docker login -u $CI_DEPLOY_USER -p $CI_DEPLOY_PASSWORD $CI_REGISTRY - ``` - ### Container Registry examples with GitLab CI/CD If you're using Docker-in-Docker on your Runners, this is how your `.gitlab-ci.yml` @@ -276,7 +273,7 @@ build: Here, `$CI_REGISTRY_IMAGE` would be resolved to the address of the registry tied to this project. Since `$CI_COMMIT_REF_NAME` resolves to the branch or tag name, -and your branch-name can contain forward slashes (e.g., feature/my-feature), it is +and your branch name can contain forward slashes (for example, `feature/my-feature`), it is safer to use `$CI_COMMIT_REF_SLUG` as the image tag. This is due to that image tags cannot contain forward slashes. We also declare our own variable, `$IMAGE_TAG`, combining the two to save us some typing in the `script` section. @@ -352,8 +349,8 @@ is set to `always`. ### Using a Docker-in-Docker image from your Container Registry -If you want to use your own Docker images for Docker-in-Docker, there are a few -things you need to do in addition to the steps in the +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: 1. Update the `image` and `service` to point to your registry. @@ -373,8 +370,8 @@ Below is an example of what your `.gitlab-ci.yml` should look like: - docker run my-docker-image /script/to/run/tests ``` -If you forget to set the service alias, the `docker:19.03.12` image won't find the -`dind` service, and an error like the following will be thrown: +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 @@ -496,81 +493,71 @@ Container Registry. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15398) in GitLab 12.8. > - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/218737) from "expiration policy" to "cleanup policy" in GitLab 13.2. -For a specific project, if you want to remove tags you no longer need, -you can create a cleanup policy. When the policy is applied, tags matching the regex pattern are removed. +The cleanup policy is a scheduled job you can use to remove tags from the Container Registry. +For the project where it's defined, tags matching the regex pattern are removed. The underlying layers and images remain. -To delete the underlying layers and images no longer associated with any tags, Instance Administrators can use +To delete the underlying layers and images that aren't associated with any tags, administrators can use [garbage collection](../../../administration/packages/container_registry.md#removing-unused-layers-not-referenced-by-manifests) with the `-m` switch. -NOTE: **Note:** -For GitLab.com, cleanup policies are not available for projects created -before this feature was deployed to production (February 2020). -Support for pre-existing projects on GitLab.com -[is planned](https://gitlab.com/gitlab-org/gitlab/-/issues/196124). -For self-managed instances, cleanup policies may be enabled by an admin in the -[GitLab application settings](../../../api/settings.md#change-application-settings) by setting `container_expiration_policies_enable_historic_entries` to true. -Note the inherent [risks involved](./index.md#use-with-external-container-registries). - -The cleanup policy algorithm starts by collecting all the tags for a given repository in a list, -then goes through a process of excluding tags from it until only the ones to be deleted remain: - -1. Collect all the tags for a given repository in a list. -1. Excludes the tag named `latest` from the list. -1. Evaluates the `name_regex`, excluding non-matching names from the list. -1. Excludes any tags that do not have a manifest (not part of the options). -1. Orders the remaining tags by `created_date`. -1. Excludes from the list the N tags based on the `keep_n` value (Number of tags to retain). -1. Excludes from the list the tags more recent than the `older_than` value (Cleanup interval). -1. Excludes from the list any tags matching the `name_regex_keep` value (Images to preserve). -1. Finally, the remaining tags in the list are deleted from the Container Registry. +### Enable the cleanup policy -### Managing project cleanup policy through the UI +Cleanup policies can be run on all projects, with these exceptions: -To manage project cleanup policy, navigate to **{settings}** **Settings > CI/CD > Container Registry tag cleanup policy**. +- For GitLab.com, the project must have been created after 2020-02-22. + Support for projects created earlier + [is planned](https://gitlab.com/gitlab-org/gitlab/-/issues/196124). +- For self-managed GitLab instances, the project must have been created + in GitLab 12.8 or later. However, an administrator can enable the cleanup policy + for all projects (even those created before 12.8) in + [GitLab application settings](../../../api/settings.md#change-application-settings) + by setting `container_expiration_policies_enable_historic_entries` to true. -The UI allows you to configure the following: + There are performance risks with enabling it for all projects, especially if you + are using an [external registry](./index.md#use-with-external-container-registries). -- **Cleanup policy:** enable or disable the cleanup policy. -- **Cleanup interval:** how long tags are exempt from being deleted. -- **Cleanup schedule:** how often the cron job checking the tags should run. -- **Number of tags to retain:** how many tags to _always_ keep for each image. -- **Docker tags with names matching this regex pattern will expire:** the regex used to determine what tags should be cleaned up. To qualify all tags for cleanup, use the default value of `.*`. -- **Docker tags with names matching this regex pattern will be preserved:** the regex used to determine what tags should be preserved. To preserve all tags, use the default value of `.*`. +### How the cleanup policy works -#### Troubleshooting cleanup policies +The cleanup policy collects all tags in the Container Registry and excludes tags +until only the tags to be deleted remain. -If you see the following message: - -"Something went wrong while updating the cleanup policy." - -Check the regex patterns to ensure they are valid. +The cleanup policy: -You can use [Rubular](https://rubular.com/) to check your regex. -View some common [regex pattern examples](#regex-pattern-examples). +1. Collects all tags for a given repository in a list. +1. Excludes the tag named `latest` from the list. +1. Evaluates the `name_regex` (tags to expire), excluding non-matching names from the list. +1. Excludes any tags that do not have a manifest (not part of the options in the UI). +1. Orders the remaining tags by `created_date`. +1. Excludes from the list the N tags based on the `keep_n` value (Number of tags to retain). +1. Excludes from the list the tags more recent than the `older_than` value (Expiration interval). +1. Excludes from the list any tags matching the `name_regex_keep` value (tags to preserve). +1. Finally, the remaining tags in the list are deleted from the Container Registry. -### Managing project cleanup policy through the API +### Create a cleanup policy -You can set, update, and disable the cleanup policies using the GitLab API. +You can create a cleanup policy in [the API](#use-the-cleanup-policy-api) or the UI. -Examples: +To create a cleanup policy in the UI: -- Select all tags, keep at least 1 tag per image, clean up any tag older than 14 days, run once a month, preserve any images with the name `master` and the policy is enabled: +1. For your project, go to **Settings > CI/CD**. +1. Expand the **Cleanup policy for tags** section. +1. Complete the fields. - ```shell - curl --request PUT --header 'Content-Type: application/json;charset=UTF-8' --header "PRIVATE-TOKEN: <your_access_token>" --data-binary '{"container_expiration_policy_attributes":{"cadence":"1month","enabled":true,"keep_n":1,"older_than":"14d","name_regex":"","name_regex_delete":".*","name_regex_keep":".*-master"}}' 'https://gitlab.example.com/api/v4/projects/2' - ``` + | Field | Description | + |---------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------| + | **Cleanup policy** | Turn the policy on or off. | + | **Expiration interval** | How long tags are exempt from being deleted. | + | **Expiration schedule** | How often the policy should run. | + | **Number of tags to retain** | How many tags to _always_ keep for each image. | + | **Tags with names matching this regex pattern expire:** | The regex pattern that determines which tags to remove. For all tags, use `.*`. See other [regex pattern examples](#regex-pattern-examples). | + | **Tags with names matching this regex pattern are preserved:** | The regex pattern that determines which tags to preserve. The `latest` tag is always preserved. For all tags, use `.*`. See other [regex pattern examples](#regex-pattern-examples). | -See the API documentation for further details: [Edit project](../../../api/projects.md#edit-project). +1. Click **Set cleanup policy**. -### Use with external container registries +Depending on the interval you chose, the policy is scheduled to run. -When using an [external container registry](./../../../administration/packages/container_registry.md#use-an-external-container-registry-with-gitlab-as-an-auth-endpoint), -running a cleanup policy on a project may have some performance risks. If a project is going to run -a policy that will remove large quantities of tags (in the thousands), the GitLab background jobs that -run the policy may get backed up or fail completely. It is recommended you only enable container cleanup -policies for projects that were created before GitLab 12.8 if you are confident the amount of tags -being cleaned up will be minimal. +NOTE: **Note:** +If you edit the policy and click **Set cleanup policy** again, the interval is reset. ### Regex pattern examples @@ -602,6 +589,41 @@ Here are examples of regex patterns you may want to use: (?:v.+|master|release) ``` +### Use the cleanup policy API + +You can set, update, and disable the cleanup policies using the GitLab API. + +Examples: + +- Select all tags, keep at least 1 tag per image, clean up any tag older than 14 days, run once a month, preserve any images with the name `master` and the policy is enabled: + + ```shell + curl --request PUT --header 'Content-Type: application/json;charset=UTF-8' --header "PRIVATE-TOKEN: <your_access_token>" --data-binary '{"container_expiration_policy_attributes":{"cadence":"1month","enabled":true,"keep_n":1,"older_than":"14d","name_regex":"","name_regex_delete":".*","name_regex_keep":".*-master"}}' 'https://gitlab.example.com/api/v4/projects/2' + ``` + +See the API documentation for further details: [Edit project](../../../api/projects.md#edit-project). + +### Use with external container registries + +When using an [external container registry](./../../../administration/packages/container_registry.md#use-an-external-container-registry-with-gitlab-as-an-auth-endpoint), +running a cleanup policy on a project may have some performance risks. +If a project runs a policy to remove thousands of tags +the GitLab background jobs may get backed up or fail completely. +It is recommended you only enable container cleanup +policies for projects that were created before GitLab 12.8 if you are confident the number of tags +being cleaned up is minimal. + +### Troubleshooting cleanup policies + +If you see the following message: + +"Something went wrong while updating the cleanup policy." + +Check the regex patterns to ensure they are valid. + +You can use [Rubular](https://rubular.com/) to check your regex. +View some common [regex pattern examples](#regex-pattern-examples). + ## Use the Container Registry to store Helm Charts With the launch of [Helm v3](https://helm.sh/docs/topics/registries/), @@ -616,9 +638,9 @@ You can read more about the above challenges [here](https://gitlab.com/gitlab-or - Moving or renaming existing Container Registry repositories is not supported once you have pushed images, because the images are signed, and the signature includes the repository name. To move or rename a repository with a -Container Registry, you will have to delete all existing images. +Container Registry, you must delete all existing images. - Prior to GitLab 12.10, any tags that use the same image ID as the `latest` tag -will not be deleted by the cleanup policy. +are not deleted by the cleanup policy. ## Troubleshooting the GitLab Container Registry @@ -637,7 +659,7 @@ name. ### Troubleshoot as a GitLab server admin Troubleshooting the GitLab Container Registry, most of the times, requires -administration access to the GitLab server. +administrator access to the GitLab server. [Read how to troubleshoot the Container Registry](../../../administration/packages/container_registry.md#troubleshooting). @@ -655,22 +677,22 @@ the project. The following procedure uses these sample project names: -- For the current project: `example.gitlab.com/org/build/sample_project/cr:v2.9.1` -- For the new project: `example.gitlab.com/new_org/build/new_sample_project/cr:v2.9.1` +- For the current project: `gitlab.example.com/org/build/sample_project/cr:v2.9.1` +- For the new project: `gitlab.example.com/new_org/build/new_sample_project/cr:v2.9.1` Use your own URLs to complete the following steps: 1. Download the Docker images on your computer: ```shell - docker login example.gitlab.com - docker pull example.gitlab.com/org/build/sample_project/cr:v2.9.1 + docker login gitlab.example.com + docker pull gitlab.example.com/org/build/sample_project/cr:v2.9.1 ``` 1. Rename the images to match the new project name: ```shell - docker tag example.gitlab.com/org/build/sample_project/cr:v2.9.1 example.gitlab.com/new_org/build/new_sample_project/cr:v2.9.1 + docker tag gitlab.example.com/org/build/sample_project/cr:v2.9.1 gitlab.example.com/new_org/build/new_sample_project/cr:v2.9.1 ``` 1. Delete the images in both projects by using the [UI](#delete-images) or [API](../../../api/packages.md#delete-a-project-package). @@ -680,7 +702,7 @@ Use your own URLs to complete the following steps: 1. Restore the images: ```shell - docker push example.gitlab.com/new_org/build/new_sample_project/cr:v2.9.1 + docker push gitlab.example.com/new_org/build/new_sample_project/cr:v2.9.1 ``` Follow [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/18383) for details. diff --git a/doc/user/packages/dependency_proxy/index.md b/doc/user/packages/dependency_proxy/index.md index e68883a1382..e3ee8909165 100644 --- a/doc/user/packages/dependency_proxy/index.md +++ b/doc/user/packages/dependency_proxy/index.md @@ -4,9 +4,9 @@ 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/#designated-technical-writers --- -# Dependency Proxy **(PREMIUM ONLY)** +# Dependency Proxy **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7934) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.11. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7934) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.11. NOTE: **Note:** This is the user guide. In order to use the dependency proxy, an administrator @@ -63,10 +63,10 @@ To get a Docker image into the dependency proxy: image: gitlab.com/groupname/dependency_proxy/containers/alpine:latest ``` -GitLab will then pull the Docker image from Docker Hub and will cache the blobs -on the GitLab server. The next time you pull the same image, it will get the latest -information about the image from Docker Hub but will serve the existing blobs -from GitLab. +GitLab pulls the Docker image from Docker Hub and caches the blobs +on the GitLab server. The next time you pull the same image, GitLab gets the latest +information about the image from Docker Hub but serves the existing blobs +from the GitLab server. The blobs are kept forever, and there is no hard limit on how much data can be stored. @@ -82,6 +82,6 @@ for more details. The following limitations apply: -- Only public groups are supported (authentication is not supported yet). +- Only [public groups are supported](https://gitlab.com/gitlab-org/gitlab/-/issues/11582) (authentication is not supported yet). - Only Docker Hub is supported. - This feature requires Docker Hub being available. diff --git a/doc/user/packages/go_proxy/index.md b/doc/user/packages/go_proxy/index.md index a705b956d30..edf1528a751 100644 --- a/doc/user/packages/go_proxy/index.md +++ b/doc/user/packages/go_proxy/index.md @@ -4,13 +4,14 @@ 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/#designated-technical-writers --- -# GitLab Go Proxy **(PREMIUM)** +# GitLab Go Proxy > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27376) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.1. > - It's deployed behind a feature flag, disabled by default. > - It's disabled on GitLab.com. > - It's not recommended for production use. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-the-go-proxy). **(PREMIUM)** +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-the-go-proxy). +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. With the Go proxy for GitLab, every project in GitLab can be fetched with the [Go proxy protocol](https://proxy.golang.org/). @@ -53,7 +54,7 @@ the **{package}** **Packages > List** entry under your project's sidebar, verify the following: 1. Your GitLab administrator has - [enabled support for the Package Registry](../../../administration/packages/index.md). **(PREMIUM ONLY)** + [enabled support for the Package Registry](../../../administration/packages/index.md). 1. The Package Registry is [enabled for your project](../index.md). NOTE: **Note:** diff --git a/doc/user/packages/index.md b/doc/user/packages/index.md index ab9cdc204f8..92d31c31986 100644 --- a/doc/user/packages/index.md +++ b/doc/user/packages/index.md @@ -4,106 +4,37 @@ 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/#designated-technical-writers --- -# GitLab Package Registry +# Packages & Registries -With the GitLab Package Registry, you can use GitLab as a private or public repository -for a variety of common package managers. You can build and publish +The GitLab [Package Registry](package_registry/index.md) acts as a private or public registry +for a variety of common package managers. You can publish and share packages, which can be easily consumed as a dependency in downstream projects. -GitLab acts as a repository for the following: - -| Software repository | Description | Available in GitLab version | -| ------------------- | ----------- | --------------------------- | -| [Container Registry](container_registry/index.md) | The GitLab Container Registry enables every project in GitLab to have its own space to store [Docker](https://www.docker.com/) images. | 8.8+ | -| [Dependency Proxy](dependency_proxy/index.md) **(PREMIUM)** | The GitLab Dependency Proxy sets up a local proxy for frequently used upstream images/packages. | 11.11+ | -| [Conan Repository](conan_repository/index.md) **(PREMIUM)** | The GitLab Conan Repository enables every project in GitLab to have its own space to store [Conan](https://conan.io/) packages. | 12.6+ | -| [Maven Repository](maven_repository/index.md) **(PREMIUM)** | The GitLab Maven Repository enables every project in GitLab to have its own space to store [Maven](https://maven.apache.org/) packages. | 11.3+ | -| [NPM Registry](npm_registry/index.md) **(PREMIUM)** | The GitLab NPM Registry enables every project in GitLab to have its own space to store [NPM](https://www.npmjs.com/) packages. | 11.7+ | -| [NuGet Repository](nuget_repository/index.md) **(PREMIUM)** | The GitLab NuGet Repository will enable every project in GitLab to have its own space to store [NuGet](https://www.nuget.org/) packages. | 12.8+ | -| [PyPi Repository](pypi_repository/index.md) **(PREMIUM)** | The GitLab PyPi Repository will enable every project in GitLab to have its own space to store [PyPi](https://pypi.org/) packages. | 12.10+ | -| [Go Proxy](go_proxy/index.md) **(PREMIUM)** | The Go proxy for GitLab enables every project in GitLab to be fetched with the [Go proxy protocol](https://proxy.golang.org/). | 13.1+ | -| [Composer Repository](composer_repository/index.md) **(PREMIUM)** | The GitLab Composer Repository will enable every project in GitLab to have its own space to store [Composer](https://getcomposer.org/) packages. | 13.2+ | - -## View packages - -You can view packages for your project or group. - -1. Go to the project or group. -1. Go to **{package}** **Packages & Registries > Package Registry**. - -You can search, sort, and filter packages on this page. - -For information on how to create and upload a package, view the GitLab documentation for your package type. - -## Use GitLab CI/CD to build packages - -You can use [GitLab CI/CD](./../../ci/README.md) to build packages. -For Maven and NPM 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 repo](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates). - -Learn more about [using CI/CD to build Maven packages](maven_repository/index.md#creating-maven-packages-with-gitlab-cicd) -and [NPM packages](npm_registry/index.md#publishing-a-package-with-cicd). - -If you use CI/CD to build a package, extended activity -information is displayed when you view the package details: - - - -You can view which pipeline published the package, as well as the commit and -user who triggered it. - -## Download a package - -To download a package: - -1. Go to **{package}** **Packages & Registries > Package Registry**. -1. Click the name of the package you want to download. -1. In the **Activity** section, click the name of the package you want to download. - -## Delete a package - -You cannot edit a package after you publish it in the Package Registry. Instead, you -must delete and recreate it. - -- You cannot delete packages from the group view. You must delete them from the project view instead. - See [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/227714) for details. -- You must have suitable [permissions](../permissions.md). - -You can delete packages by using [the API](../../api/packages.md#delete-a-project-package) or the UI. - -To delete a package in the UI: - -1. Go to **{package}** **Packages & Registries > Package Registry**. -1. Find the name of the package you want to delete. -1. Click **Delete**. - -The package is permanently deleted. - -## Disable the Package Registry - -The Package Registry is automatically enabled. - -If you are using a self-managed instance of GitLab, your administrator can remove -the menu item, **{package}** **Packages & Registries**, from the GitLab sidebar. For more information, -see the [administration documentation](../../administration/packages/index.md). - -You can also remove the Package Registry for your project specifically: - -1. In your project, go to **{settings}** **Settings > General**. -1. Expand the **Visibility, project features, permissions** section and disable the - **Packages** feature. -1. Click **Save changes**. - -The **{package}** **Packages & Registries > Package Registry** entry is removed from the sidebar. - -## Package workflows - -Learn how to use the GitLab Package Registry to build your own custom package workflow. - -- [Use a project as a package registry](./workflows/project_registry.md) to publish all of your packages to one project. -- Publish multiple different packages from one [monorepo project](./workflows/monorepo.md). +The Package Registry supports the following formats: + +<div class="row"> +<div class="col-md-9"> +<table align="left" style="width:50%"> +<tr style="background:#dfdfdf"><th>Package type</th><th>GitLab version</th></tr> +<tr><td><a href="https://docs.gitlab.com/ee/user/packages/composer_repository/index.html">Composer</a></td><td>13.2+</td></tr> +<tr><td><a href="https://docs.gitlab.com/ee/user/packages/conan_repository/index.html">Conan</a></td><td>12.6+</td></tr> +<tr><td><a href="https://docs.gitlab.com/ee/user/packages/go_proxy/index.html">Go</a></td><td>13.1+</td></tr> +<tr><td><a href="https://docs.gitlab.com/ee/user/packages/maven_repository/index.html">Maven</a></td><td>11.3+</td></tr> +<tr><td><a href="https://docs.gitlab.com/ee/user/packages/npm_registry/index.html">NPM</a></td><td>11.7+</td></tr> +<tr><td><a href="https://docs.gitlab.com/ee/user/packages/nuget_repository/index.html">NuGet</a></td><td>12.8+</td></tr> +<tr><td><a href="https://docs.gitlab.com/ee/user/packages/pypi_repository/index.html">PyPI</a></td><td>12.10+</td></tr> +</table> +</div> +</div> + +You can also use the [API](../../api/packages.md) to administer the Package Registry. + +The GitLab [Container Registry](container_registry/index.md) is a secure and private registry for container images. +It's built on open source software and completely integrated within GitLab. +Use GitLab CI/CD to create and publish images. Use the GitLab [API](../../api/container_registry.md) to +manage the registry across groups and projects. + +The [Dependency Proxy](dependency_proxy/index.md) is a local proxy for frequently-used upstream images and packages. ## Suggested contributions diff --git a/doc/user/packages/maven_repository/index.md b/doc/user/packages/maven_repository/index.md index b194b7d837a..f98a8eb9c6d 100644 --- a/doc/user/packages/maven_repository/index.md +++ b/doc/user/packages/maven_repository/index.md @@ -4,9 +4,10 @@ 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/#designated-technical-writers --- -# GitLab Maven Repository **(PREMIUM)** +# GitLab Maven Repository -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5811) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5811) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.3. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. With the GitLab [Maven](https://maven.apache.org) Repository, every project can have its own space to store its Maven artifacts. @@ -17,7 +18,7 @@ project can have its own space to store its Maven artifacts. NOTE: **Note:** This option is available only if your GitLab administrator has -[enabled support for the Maven repository](../../../administration/packages/index.md).**(PREMIUM ONLY)** +[enabled support for the Maven repository](../../../administration/packages/index.md). After the Packages feature is enabled, the Maven Repository will be available for all new projects by default. To enable it for existing projects, or if you want @@ -321,7 +322,7 @@ repositories { name "GitLab" credentials(HttpHeaderCredentials) { name = 'Job-Token' - value = '${CI_JOB_TOKEN}' + value = System.getenv("CI_JOB_TOKEN") } authentication { header(HttpHeaderAuthentication) @@ -689,7 +690,7 @@ downloaded from the GitLab Package Registry: Downloading from gitlab-maven: http://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven/com/mycompany/mydepartment/my-project/1.0-SNAPSHOT/my-project-1.0-20200128.120857-1.pom ``` -#### Install with `mvn dependency:get` +### Install using Maven with `mvn dependency:get` The second way to install packages is to use the Maven commands directly. Inside your project directory, run: @@ -782,7 +783,7 @@ is updated: ```yaml deploy: - image: maven:3.3.9-jdk-8 + image: maven:3.6-jdk-11 script: - 'mvn deploy -s ci_settings.xml' only: @@ -807,7 +808,7 @@ is updated: ```yaml deploy: - image: gradle:latest + image: gradle:6.5-jdk11 script: - 'gradle publish' only: @@ -816,11 +817,6 @@ is updated: 1. Push those files to your repository. -The next time the `deploy` job runs, it will copy `ci_settings.xml` to the -user's home location (in this case the user is `root` since it runs in a -Docker container), and Maven will use the configured CI -[environment variables](../../../ci/variables/README.md#predefined-environment-variables). - ### Version validation The version string is validated using the following regex. @@ -833,10 +829,25 @@ You can play around with the regex and try your version strings on [this regular ## Troubleshooting -### Useful Maven command line options +### Review network trace logs + +If you are having issues with the Maven Repository, you may want to review network trace logs. + +For example, try to run `mvn deploy` locally with a PAT token and use these options: + +```shell +mvn deploy \ +-Dorg.slf4j.simpleLogger.log.org.apache.maven.wagon.providers.http.httpclient=trace \ +-Dorg.slf4j.simpleLogger.log.org.apache.maven.wagon.providers.http.httpclient.wire=trace +``` + +CAUTION: **Caution:** +When you set these options, all network requests are logged and a large amount of output is generated. + +### Useful Maven command-line options -There's some [maven command line options](https://maven.apache.org/ref/current/maven-embedder/cli.html) -which maybe useful when doing tasks with GitLab CI/CD. +There are some [Maven command-line options](https://maven.apache.org/ref/current/maven-embedder/cli.html) +that may be useful when performing tasks with GitLab CI/CD. - File transfer progress can make the CI logs hard to read. Option `-ntp,--no-transfer-progress` was added in diff --git a/doc/user/packages/npm_registry/index.md b/doc/user/packages/npm_registry/index.md index 390b2c28e10..5b90ec6f18c 100644 --- a/doc/user/packages/npm_registry/index.md +++ b/doc/user/packages/npm_registry/index.md @@ -4,9 +4,10 @@ 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/#designated-technical-writers --- -# GitLab NPM Registry **(PREMIUM)** +# GitLab NPM Registry -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5934) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5934) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.7. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. With the GitLab NPM Registry, every project can have its own space to store NPM packages. @@ -20,9 +21,9 @@ Only [scoped](https://docs.npmjs.com/misc/scope) packages are supported. NOTE: **Note:** This option is available only if your GitLab administrator has -[enabled support for the NPM registry](../../../administration/packages/index.md).**(PREMIUM ONLY)** +[enabled support for the NPM registry](../../../administration/packages/index.md). -After the NPM registry is enabled, it will be available for all new projects +Enabling the NPM registry makes it available for all new projects by default. To enable it for existing projects, or if you want to disable it: 1. Navigate to your project's **Settings > General > Visibility, project features, permissions**. @@ -36,7 +37,7 @@ get familiar with the package naming convention. ## Getting started -This section will cover installing NPM (or Yarn) and building a package for your +This section covers how to install NPM (or Yarn) and build a package for your JavaScript project. This is a quickstart if you are new to NPM packages. If you are already using NPM and understand how to build your own packages, move on to the [next section](#authenticating-to-the-gitlab-npm-registry). @@ -93,24 +94,24 @@ Or if you're using Yarn: yarn init ``` -This will take you through a series of questions to produce a `package.json` +This takes you through a series of questions to produce a `package.json` file, which is required for all NPM packages. The most important question is the package name. NPM packages must [follow the naming convention](#package-naming-convention) and be scoped to the project or group where the registry exists. Once you have completed the setup, you are now ready to upload your package to -the GitLab registry. To get started, you will need to set up authentication then +the GitLab registry. To get started, you need to set up authentication and then configure GitLab as a remote registry. ## Authenticating to the GitLab NPM Registry If a project is private or you want to upload an NPM package to GitLab, -credentials will need to be provided for authentication. [Personal access tokens](../../profile/personal_access_tokens.md) +you need to provide credentials for authentication. [Personal access tokens](../../profile/personal_access_tokens.md) and [deploy tokens](../../project/deploy_tokens/index.md) are preferred, but support is available for [OAuth tokens](../../../api/oauth2.md#resource-owner-password-credentials-flow). CAUTION: **Two-factor authentication (2FA) is only supported with personal access tokens:** -If you have 2FA enabled, you need to use a [personal access token](../../profile/personal_access_tokens.md) with OAuth headers with the scope set to `api` or a [deploy token](../../project/deploy_tokens/index.md) with `read_package_registry` or `write_package_registry` scopes. Standard OAuth tokens won't be able to authenticate to the GitLab NPM Registry. +If you have 2FA enabled, you need to use a [personal access token](../../profile/personal_access_tokens.md) with OAuth headers with the scope set to `api` or a [deploy token](../../project/deploy_tokens/index.md) with `read_package_registry` or `write_package_registry` scopes. Standard OAuth tokens cannot authenticate to the GitLab NPM Registry. ### Authenticating with a personal access token or deploy token @@ -168,7 +169,7 @@ Then, you could run `npm publish` either locally or via GitLab CI/CD: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9104) in GitLab Premium 12.5. If you’re using NPM with GitLab CI/CD, a CI job token can be used instead of a personal access token or deploy token. -The token will inherit the permissions of the user that generates the pipeline. +The token inherits the permissions of the user that generates the pipeline. Add a corresponding section to your `.npmrc` file: @@ -180,7 +181,7 @@ Add a corresponding section to your `.npmrc` file: ## Uploading packages -Before you will be able to upload a package, you need to specify the registry +Before you can upload a package, you need to specify the registry for NPM. To do this, add the following section to the bottom of `package.json`: ```json @@ -205,8 +206,8 @@ npm publish You can then navigate to your project's **Packages & Registries** page and see the uploaded packages or even delete them. -If you attempt to publish a package with a name that already exists within -a given scope, you will receive a `403 Forbidden!` error. +Attempting to publish a package with a name that already exists within +a given scope causes a `403 Forbidden!` error. ## Uploading a package with the same version twice @@ -245,7 +246,7 @@ project path is `My-Group/project-foo`, your package must be named `@My-Group/an `@my-group/any-package-name` will not work. CAUTION: **When updating the path of a user/group or transferring a (sub)group/project:** -If you update the root namespace of a project with NPM packages, your changes will be rejected. To be allowed to do that, make sure to remove any NPM package first. Don't forget to update your `.npmrc` files to follow the above naming convention and run `npm publish` if necessary. +Make sure to remove any NPM packages first. You cannot update the root namespace of a project with NPM packages. Don't forget to update your `.npmrc` files to follow the above naming convention and run `npm publish` if necessary. Now, you can configure your project to authenticate with the GitLab NPM Registry. @@ -253,16 +254,16 @@ Registry. ## Installing a package NPM packages are commonly installed using the `npm` or `yarn` commands -inside a JavaScript project. If you haven't already, you will need to set the +inside a JavaScript project. If you haven't already, set the URL for scoped packages. You can do this with the following command: ```shell npm config set @foo:registry https://gitlab.com/api/v4/packages/npm/ ``` -You will need to replace `@foo` with your scope. +Replace `@foo` with your scope. -Next, you will need to ensure [authentication](#authenticating-to-the-gitlab-npm-registry) +Next, you need to ensure [authentication](#authenticating-to-the-gitlab-npm-registry) is setup so you can successfully install the package. Once this has been completed, you can run the following command inside your project to install a package: @@ -281,7 +282,7 @@ yarn add @my-project-scope/my-package > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/55344) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.9. -By default, when an NPM package is not found in the GitLab NPM Registry, the request will be forwarded to [npmjs.com](https://www.npmjs.com/). +By default, when an NPM package is not found in the GitLab NPM Registry, the request is forwarded to [npmjs.com](https://www.npmjs.com/). Administrators can disable this behavior in the [Continuous Integration settings](../../admin_area/settings/continuous_integration.md). @@ -367,7 +368,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'll need to set a value prior to running `npm install` or set the value using [GitLab environment 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 need to set a value prior to running `npm install` or set the value using [GitLab environment variables](./../../../ci/variables/README.md): ```shell NPM_TOKEN=<your_token> npm install diff --git a/doc/user/packages/nuget_repository/index.md b/doc/user/packages/nuget_repository/index.md index 4ee5e5c4627..9fb50ce71fb 100644 --- a/doc/user/packages/nuget_repository/index.md +++ b/doc/user/packages/nuget_repository/index.md @@ -4,9 +4,10 @@ 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/#designated-technical-writers --- -# GitLab NuGet Repository **(PREMIUM)** +# GitLab NuGet Repository -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20050) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.8. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20050) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.8. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. With the GitLab NuGet Repository, every project can have its own space to store NuGet packages. @@ -18,7 +19,7 @@ The GitLab NuGet Repository works with: ## Setting up your development environment -You will need [NuGet CLI 5.2 or later](https://www.nuget.org/downloads). Earlier versions have not been tested +[NuGet CLI 5.2 or later](https://www.nuget.org/downloads) is required. Earlier versions have not been tested against the GitLab NuGet Repository and might not work. If you have [Visual Studio](https://visualstudio.microsoft.com/vs/), NuGet CLI is probably already installed. @@ -42,6 +43,9 @@ Available commands: [output truncated] ``` +NOTE: **Note:** +GitLab currently only supports NuGet v3. Earlier versions are not supported. + ### macOS support For macOS, you can also use [Mono](https://www.mono-project.com/) to run @@ -58,9 +62,9 @@ mono nuget.exe NOTE: **Note:** This option is available only if your GitLab administrator has -[enabled support for the Package Registry](../../../administration/packages/index.md). **(PREMIUM ONLY)** +[enabled support for the Package Registry](../../../administration/packages/index.md). -After the NuGet Repository is enabled, it will be available for all new projects +When the NuGet Repository is enabled, it is available for all new projects by default. To enable it for existing projects, or if you want to disable it: 1. Navigate to your project's **Settings > General > Visibility, project features, permissions**. @@ -71,7 +75,7 @@ You should then be able to see the **Packages & Registries** section on the left ## Adding the GitLab NuGet Repository as a source to NuGet -You will need the following: +You need the following: - Your GitLab username. - A personal access token or deploy token. For repository authentication: @@ -108,7 +112,7 @@ nuget source Add -Name "GitLab" -Source "https://gitlab.example/api/v4/projects/ 1. Open [Visual Studio](https://visualstudio.microsoft.com/vs/). 1. Open the **FILE > OPTIONS** (Windows) or **Visual Studio > Preferences** (Mac OS). -1. In the **NuGet** section, open **Sources**. You will see a list of all your NuGet sources. +1. In the **NuGet** section, open **Sources** to see a list of all your NuGet sources. 1. Click **Add**. 1. Fill the fields with: - **Name**: Desired name for the source @@ -152,8 +156,8 @@ When uploading packages, note that: - The maximum allowed size is 50 Megabytes. - If you upload the same package with the same version multiple times, each consecutive upload - is saved as a separate file. When installing a package, GitLab will serve the most recent file. -- When uploading packages to GitLab, they will not be displayed in the packages UI of your project + is saved as a separate file. When installing a package, GitLab serves the most recent file. +- When uploading packages to GitLab, they are not displayed in the packages UI of your project immediately. It can take up to 10 minutes to process a package. ### Upload packages with NuGet CLI @@ -197,7 +201,7 @@ dotnet nuget push MyPackage.1.0.0.nupkg --source gitlab CAUTION: **Warning:** By default, `nuget` checks the official source at `nuget.org` first. If you have a package in the GitLab NuGet Repository with the same name as a package at `nuget.org`, you must specify the source -name or the wrong package will be installed. +name to install the correct package. Install the latest version of a package using the following command: @@ -210,7 +214,7 @@ nuget install <package_id> -OutputDirectory <output_directory> \ Where: - `<package_id>` is the package ID. -- `<output_directory>` is the output directory, where the package will be installed. +- `<output_directory>` is the output directory, where the package is installed. - `<package_version>` (Optional) is the package version. - `<source_name>` (Optional) is the source name. @@ -232,3 +236,35 @@ Where: - `<package_id>` is the package ID. - `<package_version>` (Optional) is the package version. + +## Publishing a NuGet package with CI/CD + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36424) in GitLab 13.3. + +If you’re using NuGet with GitLab CI/CD, a CI job token can be used instead of a personal access token or deploy token. +The token inherits the permissions of the user that generates the pipeline. + +This example shows how to create a new package each time the `master` branch +is updated: + +1. Add a `deploy` job to your `.gitlab-ci.yml` file: + + ```yaml + image: mcr.microsoft.com/dotnet/core/sdk:3.1 + + stages: + - deploy + + deploy: + stage: deploy + script: + - dotnet restore -p:Configuration=Release + - dotnet build -c Release + - dotnet pack -c Release + - dotnet nuget add source "$CI_SERVER_URL/api/v4/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 + ``` + +1. Commit the changes and push it to your GitLab repository to trigger a new CI build. diff --git a/doc/user/packages/img/package_activity_v12_10.png b/doc/user/packages/package_registry/img/package_activity_v12_10.png Binary files differindex 4fea9a7ca3f..4fea9a7ca3f 100644 --- a/doc/user/packages/img/package_activity_v12_10.png +++ b/doc/user/packages/package_registry/img/package_activity_v12_10.png diff --git a/doc/user/packages/package_registry/index.md b/doc/user/packages/package_registry/index.md new file mode 100644 index 00000000000..fd250c9ac95 --- /dev/null +++ b/doc/user/packages/package_registry/index.md @@ -0,0 +1,93 @@ +--- +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/#designated-technical-writers +--- + +# Package Registry + +> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. + +With the GitLab Package Registry, you can use GitLab as a private or public registry +for a variety of common package managers. You can publish and share +packages, which can be easily consumed as a dependency in downstream projects. + +## View packages + +You can view packages for your project or group. + +1. Go to the project or group. +1. Go to **{package}** **Packages & Registries > Package Registry**. + +You can search, sort, and filter packages on this page. + +For information on how to create and upload a package, view the GitLab documentation for your package type. + +## Use GitLab CI/CD to build packages + +You can use [GitLab CI/CD](../../../ci/README.md) to build packages. +For Maven, NuGet and NPM 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 repo](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates). + +Learn more about [using CI/CD to build Maven packages](../maven_repository/index.md#creating-maven-packages-with-gitlab-cicd), [NPM packages](../npm_registry/index.md#publishing-a-package-with-cicd) and [NuGet Packages](../nuget_repository/index.md#publishing-a-nuget-package-with-cicd). + +If you use CI/CD to build a package, extended activity +information is displayed when you view the package details: + + + +You can view which pipeline published the package, as well as the commit and +user who triggered it. + +## Download a package + +To download a package: + +1. Go to **{package}** **Packages & Registries > Package Registry**. +1. Click the name of the package you want to download. +1. In the **Activity** section, click the name of the package you want to download. + +## Delete a package + +You cannot edit a package after you publish it in the Package Registry. Instead, you +must delete and recreate it. + +- You cannot delete packages from the group view. You must delete them from the project view instead. + See [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/227714) for details. +- You must have suitable [permissions](../../permissions.md). + +You can delete packages by using [the API](../../../api/packages.md#delete-a-project-package) or the UI. + +To delete a package in the UI: + +1. Go to **{package}** **Packages & Registries > Package Registry**. +1. Find the name of the package you want to delete. +1. Click **Delete**. + +The package is permanently deleted. + +## Disable the Package Registry + +The Package Registry is automatically enabled. + +If you are using a self-managed instance of GitLab, your administrator can remove +the menu item, **{package}** **Packages & Registries**, from the GitLab sidebar. For more information, +see the [administration documentation](../../../administration/packages/index.md). + +You can also remove the Package Registry for your project specifically: + +1. In your project, go to **Settings > General**. +1. Expand the **Visibility, project features, permissions** section and disable the + **Packages** feature. +1. Click **Save changes**. + +The **{package}** **Packages & Registries > Package Registry** entry is removed from the sidebar. + +## Package workflows + +Learn how to use the GitLab Package Registry to build your own custom package workflow. + +- [Use a project as a package registry](../workflows/project_registry.md) to publish all of your packages to one project. +- Publish multiple different packages from one [monorepo project](../workflows/monorepo.md). diff --git a/doc/user/packages/pypi_repository/index.md b/doc/user/packages/pypi_repository/index.md index 615741cc303..63e6cd7b5b4 100644 --- a/doc/user/packages/pypi_repository/index.md +++ b/doc/user/packages/pypi_repository/index.md @@ -4,9 +4,10 @@ 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/#designated-technical-writers --- -# GitLab PyPi Repository **(PREMIUM)** +# GitLab PyPi Repository -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/208747) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.10. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/208747) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.10. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. With the GitLab PyPi Repository, every project can have its own space to store PyPi packages. @@ -17,15 +18,15 @@ The GitLab PyPi Repository works with: ## Setting up your development environment -You will need a recent version of [pip](https://pypi.org/project/pip/) and [twine](https://pypi.org/project/twine/). +You need a recent version of [pip](https://pypi.org/project/pip/) and [twine](https://pypi.org/project/twine/). ## Enabling the PyPi Repository NOTE: **Note:** This option is available only if your GitLab administrator has -[enabled support for the Package Registry](../../../administration/packages/index.md). **(PREMIUM ONLY)** +[enabled support for the Package Registry](../../../administration/packages/index.md). -After the PyPi Repository is enabled, it will be available for all new projects +After the PyPi Repository is enabled, it is available for all new projects by default. To enable it for existing projects, or if you want to disable it: 1. Navigate to your project's **Settings > General > Visibility, project features, permissions**. @@ -36,7 +37,7 @@ You should then be able to see the **Packages & Registries** section on the left ## Getting started -This section will cover creating a new example PyPi package to upload. This is a +This section covers creating a new example PyPi package to upload. This is a quickstart to test out the **GitLab PyPi Registry**. If you already understand how to build and publish your own packages, move on to the [next section](#adding-the-gitlab-pypi-repository-as-a-source). @@ -158,7 +159,7 @@ Package Registry**. Before we do so, we next need to set up authentication. ### Authenticating with a personal access token -You will need the following: +You need the following: - A personal access token. You can generate a [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to `api` for repository authentication. - A suitable name for your source. @@ -179,7 +180,7 @@ password = <your personal access token> ### Authenticating with a deploy token -You will need the following: +You need the following: - A deploy token. You can generate a [deploy token](./../../project/deploy_tokens/index.md) with the `read_package_registry` and/or `write_package_registry` scopes for repository authentication. - A suitable name for your source. @@ -204,7 +205,7 @@ When uploading packages, note that: - The maximum allowed size is 50 Megabytes. - If you upload the same package with the same version multiple times, each consecutive upload - is saved as a separate file. When installing a package, GitLab will serve the most recent file. + is saved as a separate file. When installing a package, GitLab serves the most recent file. ### Upload packages with Twine @@ -228,8 +229,8 @@ Uploading mypypipackage-0.0.1.tar.gz This indicates that the package was uploaded successfully. You can then navigate to your project's **Packages & Registries** page and see the uploaded packages. -If you did not follow the guide above, the you'll need to ensure your package -has been properly built and you [created a PyPi package with setuptools](https://packaging.python.org/tutorials/packaging-projects/). +If you did not follow the guide above, then you need to ensure your package +has been properly built and you [created a PyPi package with `setuptools`](https://packaging.python.org/tutorials/packaging-projects/). You can then upload your package using the following command: diff --git a/doc/user/packages/workflows/monorepo.md b/doc/user/packages/workflows/monorepo.md index 5acd4fd0735..c87f181bf82 100644 --- a/doc/user/packages/workflows/monorepo.md +++ b/doc/user/packages/workflows/monorepo.md @@ -1,3 +1,9 @@ +--- +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/#designated-technical-writers +--- + # Monorepo package management workflows Oftentimes, one project or Git repository may contain multiple different @@ -76,44 +82,39 @@ Using the example project above, this `gitlab-ci.yml` file will publish and publish `MyPackage` anytime changes are made to anywhere _except_ the `Foo` directory on the `master` branch. -```shell +```yaml +image: node:latest + stages: - build -.default-rule: &default-rule - if: '$CI_MERGE_REQUEST_IID || $CI_COMMIT_REF_SLUG == "master"' - -.foo-package: +build-foo-package: + stage: build variables: PACKAGE: "Foo" - before_script: + script: - cd src/components/Foo + - echo "Building $PACKAGE" + - npm publish only: + refs: + - master + - merge_requests changes: - "src/components/Foo/**/*" -.parent-package: +build-my-project-package: + stage: build variables: PACKAGE: "MyPackage" - except: - changes: - - "src/components/Foo/**/*" - -.build-package: - stage: build script: - echo "Building $PACKAGE" - npm publish - rules: - - <<: *default-rule - -build-foo-package: - extends: - - .build-package - - .foo-package - -build-my-project-package: - extends: - - .build-package - - .parent-package + only: + refs: + - master + - merge_requests + except: + changes: + - "src/components/Foo/**/*" ``` diff --git a/doc/user/packages/workflows/project_registry.md b/doc/user/packages/workflows/project_registry.md index df330931ac5..a7bc4436d0e 100644 --- a/doc/user/packages/workflows/project_registry.md +++ b/doc/user/packages/workflows/project_registry.md @@ -1,3 +1,9 @@ +--- +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/#designated-technical-writers +--- + # Project as a package registry Using the features of the package registry, it is possible to use one project to store all of your packages. |
