diff options
Diffstat (limited to 'doc/user/packages')
| -rw-r--r-- | doc/user/packages/composer_repository/index.md | 33 | ||||
| -rw-r--r-- | doc/user/packages/conan_repository/index.md | 18 | ||||
| -rw-r--r-- | doc/user/packages/container_registry/index.md | 19 | ||||
| -rw-r--r-- | doc/user/packages/dependency_proxy/index.md | 5 | ||||
| -rw-r--r-- | doc/user/packages/generic_packages/index.md | 8 | ||||
| -rw-r--r-- | doc/user/packages/go_proxy/index.md | 3 | ||||
| -rw-r--r-- | doc/user/packages/index.md | 4 | ||||
| -rw-r--r-- | doc/user/packages/maven_repository/index.md | 13 | ||||
| -rw-r--r-- | doc/user/packages/npm_registry/index.md | 44 | ||||
| -rw-r--r-- | doc/user/packages/nuget_repository/index.md | 17 | ||||
| -rw-r--r-- | doc/user/packages/package_registry/index.md | 3 | ||||
| -rw-r--r-- | doc/user/packages/pypi_repository/index.md | 12 | ||||
| -rw-r--r-- | doc/user/packages/rubygems_registry/index.md | 137 | ||||
| -rw-r--r-- | doc/user/packages/workflows/project_registry.md | 2 |
14 files changed, 275 insertions, 43 deletions
diff --git a/doc/user/packages/composer_repository/index.md b/doc/user/packages/composer_repository/index.md index f935fa87d68..bc1e59e4ac2 100644 --- a/doc/user/packages/composer_repository/index.md +++ b/doc/user/packages/composer_repository/index.md @@ -8,12 +8,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15886) in GitLab Premium 13.2. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. +> - Support for Composer 2.0 [added](https://gitlab.com/gitlab-org/gitlab/-/issues/259840) in GitLab Free 13.10. Publish [Composer](https://getcomposer.org/) packages in your project's Package Registry. Then, install the packages whenever you need to use them as a dependency. -Only Composer 1.x is supported. Consider contributing or even adding support for -[Composer 2.0 in the Package Registry](https://gitlab.com/gitlab-org/gitlab/-/issues/259840). +For documentation of the specific API endpoints that the Composer +client uses, see the [Composer API documentation](../../../api/packages/composer.md). ## Create a Composer package @@ -268,10 +269,36 @@ To install a package: Without the `gitlab-domains` definition in `composer.json`, Composer uses the GitLab token as basic-auth, with the token as a username and a blank password. This results in a 401 error. -Output indicates that the package has been successfully installed. +1. With the `composer.json` and `auth.json` files configured, you can install the package by running: + + ```shell + composer update + ``` + + Or to install the single package: + + ```shell + composer req <package-name>:<package-version> + ``` + + If successful, you should see output indicating that the package installed successfully. + + You can also install from source (by pulling the Git repository directly) using the + `--prefer-source` option: + + ```shell + composer update --prefer-source + ``` 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 [HashiCorp Vault](../../../ci/secrets/index.md). + +## Supported CLI commands + +The GitLab Composer repository supports the following Composer CLI commands: + +- `composer install`: Install Composer dependencies. +- `composer update`: Install the latest version of Composer dependencies. diff --git a/doc/user/packages/conan_repository/index.md b/doc/user/packages/conan_repository/index.md index 3b8be68cff6..9df4aeb404a 100644 --- a/doc/user/packages/conan_repository/index.md +++ b/doc/user/packages/conan_repository/index.md @@ -18,6 +18,9 @@ remote and authenticate with it. Then you can run `conan` commands and publish your package to the Package Registry. +For documentation of the specific API endpoints that the Conan package manager +client uses, see the [Conan API documentation](../../../api/packages/conan.md). + ## Build a Conan package This section explains how to install Conan and build a package for your C/C++ @@ -125,7 +128,7 @@ To add the remote: For example: ```shell - conan search Hello* --all --remote=gitlab + conan search Hello* --remote=gitlab ``` ### Add a remote for your instance @@ -402,16 +405,3 @@ The GitLab Conan repository supports the following Conan CLI commands: packages you have permission to view. - `conan info`: View the information on a given package from the Package Registry. - `conan remove`: Delete the package from the Package Registry. - -## Troubleshooting Conan packages - -### `ERROR: <package> was not found in remote <remote>` - -When you attempt to install a Conan package, you might receive a `404` error -like `ERROR: <package> was not found in remote <remote>`. - -This issue occurs when you request a download from the project-level Conan API. -The resulting URL is missing is project's `/<id>` and Conan commands, like -`conan install`, fail. - -For more information, see [issue 270129](https://gitlab.com/gitlab-org/gitlab/-/issues/270129). diff --git a/doc/user/packages/container_registry/index.md b/doc/user/packages/container_registry/index.md index 18c4edd61c7..bc96d3c937c 100644 --- a/doc/user/packages/container_registry/index.md +++ b/doc/user/packages/container_registry/index.md @@ -4,7 +4,7 @@ group: Package info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# GitLab Container Registry +# GitLab Container Registry **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/4040) in GitLab 8.8. > - Docker Registry manifest `v1` support was added in GitLab 8.9 to support Docker @@ -35,7 +35,8 @@ You can view the Container Registry for a project or group. 1. Go to your project or group. 1. Go to **Packages & Registries > Container Registry**. -You can search, sort, filter, and [delete](#delete-images-from-within-gitlab) containers on this page. +You can search, sort, filter, and [delete](#delete-images-from-within-gitlab) +containers on this page. You can share a filtered view by copying the URL from your browser. Only members of the project or group can access a private project's Container Registry. @@ -499,11 +500,11 @@ The cleanup policy: 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 from the list any tags matching the `name_regex_keep` value (tags to preserve). 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. WARNING: @@ -635,6 +636,14 @@ Examples: 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" ``` +Valid values for `cadence` when using the API are: + +- `1d` (every day) +- `7d` (every week) +- `14d` (every two weeks) +- `1month` (every month) +- `3month` (every quarter) + See the API documentation for further details: [Edit project](../../../api/projects.md#edit-project). ### Use with external container registries @@ -670,8 +679,8 @@ and stored by Docker, it is not possible for GitLab to parse this data and meet ## Limitations - 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 +once you have pushed images, because the images are stored in a path that matches +the repository path. To move or rename a repository with a 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 are not deleted by the cleanup policy. diff --git a/doc/user/packages/dependency_proxy/index.md b/doc/user/packages/dependency_proxy/index.md index ad2d2ac2a8e..3dd900d2cbe 100644 --- a/doc/user/packages/dependency_proxy/index.md +++ b/doc/user/packages/dependency_proxy/index.md @@ -68,6 +68,11 @@ The requirement to authenticate is a breaking change added in 13.7. An [administ disable it](../../../administration/packages/dependency_proxy.md#disabling-authentication) if it has disrupted your existing Dependency Proxy usage. +WARNING: +If [SSO enforcement](../../group/saml_sso/index.md#sso-enforcement) +is enabled for your Group, requests to the dependency proxy will fail. This bug is being tracked in +[this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/294018). + Because the Dependency Proxy is storing Docker images in a space associated with your group, you must authenticate against the Dependency Proxy. diff --git a/doc/user/packages/generic_packages/index.md b/doc/user/packages/generic_packages/index.md index b9186e99357..57d6245dd96 100644 --- a/doc/user/packages/generic_packages/index.md +++ b/doc/user/packages/generic_packages/index.md @@ -16,18 +16,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This feature might not be available to you. Check the **version history** note above for details. -Publish generic files, like release binaries, in your project’s Package Registry. Then, install the packages whenever you need to use them as a dependency. +Publish generic files, like release binaries, in your project's Package Registry. Then, install the packages whenever you need to use them as a dependency. ## 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 job token](../../../api/README.md#gitlab-ci-job-token), or [deploy token](../../project/deploy_tokens/index.md). +[CI/CD job token](../../../api/README.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 job token](../../../api/README.md#gitlab-ci-job-token), or a [deploy token](../../project/deploy_tokens/index.md). +a [CI/CD job token](../../../api/README.md#gitlab-cicd-job-token), or a [deploy token](../../project/deploy_tokens/index.md). ## Publish a package file @@ -47,7 +47,7 @@ PUT /projects/:id/packages/generic/:package_name/:package_version/:file_name?sta | -------------------| --------------- | ---------| -------------------------------------------------------------------------------------------------------------------------------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](../../../api/README.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. It can contain only numbers (`0-9`), and dots (`.`). Must be in the format of `X.Y.Z`, i.e. should match `/\A\d+\.\d+\.\d+\z/` regular expression. +| `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 (`_`). | `status` | string | no | The package status. It can be `default` (default) or `hidden`. Hidden packages do not appear in the UI or [package API list endpoints](../../../api/packages.md). diff --git a/doc/user/packages/go_proxy/index.md b/doc/user/packages/go_proxy/index.md index 1fdc34e820e..36348fcde18 100644 --- a/doc/user/packages/go_proxy/index.md +++ b/doc/user/packages/go_proxy/index.md @@ -16,6 +16,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w With the Go proxy for GitLab, every project in GitLab can be fetched with the [Go proxy protocol](https://proxy.golang.org/). +For documentation of the specific API endpoints that the Go Proxy uses, see the +[Go Proxy API documentation](../../../api/packages/go_proxy.md). + ## Enable the Go proxy The Go proxy for GitLab is under development, and isn't ready for production use diff --git a/doc/user/packages/index.md b/doc/user/packages/index.md index b35015d0b67..74072aa95e1 100644 --- a/doc/user/packages/index.md +++ b/doc/user/packages/index.md @@ -4,7 +4,7 @@ group: Package info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Packages & Registries +# Packages and Registries **(FREE)** 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 @@ -24,6 +24,7 @@ The Package Registry supports the following formats: <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> <tr><td><a href="https://docs.gitlab.com/ee/user/packages/generic_packages/index.html">Generic packages</a></td><td>13.5+</td></tr> +<tr><td><a href="https://docs.gitlab.com/ee/user/packages/rubygems_registry/index.html">RubyGems</a></td><td>13.10+</td></tr> </table> </div> </div> @@ -49,7 +50,6 @@ guides you through the process. | P2 | [#36895](https://gitlab.com/gitlab-org/gitlab/-/issues/36895) | | Puppet | [#36897](https://gitlab.com/gitlab-org/gitlab/-/issues/36897) | | RPM | [#5932](https://gitlab.com/gitlab-org/gitlab/-/issues/5932) | -| RubyGems | [#803](https://gitlab.com/gitlab-org/gitlab/-/issues/803) | | SBT | [#36898](https://gitlab.com/gitlab-org/gitlab/-/issues/36898) | | Terraform | [Draft: Merge Request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/18834) | | Vagrant | [#36899](https://gitlab.com/gitlab-org/gitlab/-/issues/36899) | diff --git a/doc/user/packages/maven_repository/index.md b/doc/user/packages/maven_repository/index.md index 828eec812fa..d4dc9f0ae78 100644 --- a/doc/user/packages/maven_repository/index.md +++ b/doc/user/packages/maven_repository/index.md @@ -9,9 +9,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5811) in GitLab Premium 11.3. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. -Publish [Maven](https://maven.apache.org) artifacts in your project’s Package Registry. +Publish [Maven](https://maven.apache.org) artifacts 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 the Maven package manager +client uses, see the [Maven API documentation](../../../api/packages/maven.md). + ## Build a Maven package This section explains how to install Maven and build a package. @@ -868,3 +871,11 @@ package: - 'mvn help:system' - 'mvn package' ``` + +## Supported CLI commands + +The GitLab Maven repository supports the following Maven CLI commands: + +- `mvn deploy`: Publish your package to the Package Registry. +- `mvn install`: Install packages specified in your Maven project. +- `mvn dependency:get`: Install a specific package. diff --git a/doc/user/packages/npm_registry/index.md b/doc/user/packages/npm_registry/index.md index f048440e383..b6312002184 100644 --- a/doc/user/packages/npm_registry/index.md +++ b/doc/user/packages/npm_registry/index.md @@ -124,7 +124,7 @@ npm config set @foo:registry https://gitlab.example.com/api/v4/projects/<your_pr # Add the token for the scoped packages URL. Replace <your_project_id> # with the project where your package is located. -npm config set '//gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken' "<your_token>" +npm config set -- '//gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken' "<your_token>" ``` - `<your_project_id>` is your project ID, found on the project's home page. @@ -147,7 +147,7 @@ npm config set @foo:registry https://gitlab.example.com/api/v4/packages/npm/ # Add the token for the scoped packages URL. This will allow you to download # `@foo/` packages from private projects. -npm config set '//gitlab.example.com/api/v4/packages/npm/:_authToken' "<your_token>" +npm config set -- '//gitlab.example.com/api/v4/packages/npm/:_authToken' "<your_token>" ``` - `<your_token>` is your personal access token or deploy token. @@ -189,8 +189,8 @@ To use the [instance-level](#use-the-gitlab-endpoint-for-npm-packages) npm endpo To avoid hard-coding the `authToken` value, you may use a variable in its place: ```shell -npm config set '//gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken' "${NPM_TOKEN}" -npm config set '//gitlab.example.com/api/v4/packages/npm/:_authToken' "${NPM_TOKEN}" +npm config set -- '//gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken' "${NPM_TOKEN}" +npm config set -- '//gitlab.example.com/api/v4/packages/npm/:_authToken' "${NPM_TOKEN}" ``` Then, you can run `npm publish` either locally or by using GitLab CI/CD. @@ -251,9 +251,6 @@ Prerequisites: - [Authenticate](#authenticate-to-the-package-registry) to the Package Registry. - Set a [project-level npm endpoint](#use-the-gitlab-endpoint-for-npm-packages). -- Your npm package name must be in the format of [@scope/package-name](#package-naming-convention). - It must match exactly, including the case. This is different than the - npm naming convention, but it is required to work with the GitLab Package Registry. To upload an npm package to your project, run this command: @@ -263,6 +260,16 @@ npm publish To view the package, go to your project's **Packages & Registries**. +You can also define `"publishConfig"` for your project in `package.json`. For example: + +```json +{ +"publishConfig": { "@foo:registry":" https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/" } +} +``` + +This forces the package to publish only to the specified registry. + If you try to publish a package [with a name that already exists](#publishing-packages-with-the-same-name-or-version) within a given scope, you get a `403 Forbidden!` error. @@ -402,6 +409,9 @@ Due to a bug in npm 6.9.0, deleting distribution tags fails. Make sure your npm ## Troubleshooting +When troubleshooting npm issues, first run the same command with the `--verbose` flag to confirm +what registry you are hitting. + ### 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 @@ -469,8 +479,9 @@ NPM_TOKEN=<your_token> npm install If you get this error, ensure that: - Your token is not expired and has appropriate permissions. -- [Your token does not begin with `-`](https://gitlab.com/gitlab-org/gitlab/-/issues/235473). - A package with the same name or version doesn't already exist within the given scope. +- Your NPM package name does not contain a dot `.`. This is a [known issue](https://gitlab.com/gitlab-org/gitlab-ee/issues/10248) + in GitLab 11.9 and earlier. - The scoped packages URL includes a trailing slash: - Correct: `//gitlab.example.com/api/v4/packages/npm/` - Incorrect: `//gitlab.example.com/api/v4/packages/npm` @@ -504,4 +515,19 @@ This is usually a permissions issue with either: - The remote bucket if [object storage](../../../administration/packages/#using-object-storage) is used. -In the latter case, ensure the bucket exists and the GitLab has write access to it. +In the latter case, ensure the bucket exists and GitLab has write access to it. + +## Supported CLI commands + +The GitLab npm repository supports the following commands for the npm CLI (`npm`) and yarn CLI +(`yarn`): + +- `npm install`: Install npm packages. +- `npm publish`: Publish an npm package to the registry. +- `npm dist-tag add`: Add a dist-tag to an npm package. +- `npm dist-tag ls`: List dist-tags for a package. +- `npm dist-tag rm`: Delete a dist-tag. +- `npm ci`: Install npm packages directly from your `package-lock.json` file. +- `npm view`: Show package metadata. +- `yarn add`: Install an npm package. +- `yarn update`: Update your dependencies. diff --git a/doc/user/packages/nuget_repository/index.md b/doc/user/packages/nuget_repository/index.md index e1b61f28818..7e59b19076a 100644 --- a/doc/user/packages/nuget_repository/index.md +++ b/doc/user/packages/nuget_repository/index.md @@ -9,7 +9,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. -Publish NuGet packages in your project’s Package Registry. Then, install the +Publish NuGet packages in your project's Package Registry. Then, install the packages whenever you need to use them as a dependency. The Package Registry works with: @@ -18,6 +18,9 @@ The Package Registry works with: - [.NET Core CLI](https://docs.microsoft.com/en-us/dotnet/core/tools/) - [Visual Studio](https://visualstudio.microsoft.com/vs/) +For documentation of the specific API endpoints that these +clients use, see the [NuGet API documentation](../../../api/packages/nuget.md). + ## Install NuGet The required minimum versions are: @@ -314,7 +317,7 @@ dotnet nuget push MyPackage.1.0.0.nupkg --source gitlab > [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 +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. @@ -390,3 +393,13 @@ dotnet add package <package_id> \ - `<package_id>` is the package ID. - `<package_version>` is the package version. Optional. + +## Supported CLI commands + +The GitLab NuGet repository supports the following commands for the NuGet CLI (`nuget`) and the .NET +CLI (`dotnet`): + +- `nuget push`: Upload a package to the registry. +- `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. diff --git a/doc/user/packages/package_registry/index.md b/doc/user/packages/package_registry/index.md index 0e83843f3e8..f04f6f1316e 100644 --- a/doc/user/packages/package_registry/index.md +++ b/doc/user/packages/package_registry/index.md @@ -19,7 +19,8 @@ You can view packages for your project or group. 1. Go to the project or group. 1. Go to **Packages & Registries > Package Registry**. -You can search, sort, and filter packages on this page. +You can search, sort, and filter packages on this page. You can share your search results by copying +and pasting the URL from your browser. You can also find helpful code snippets for configuring your package manager or installing a given package. diff --git a/doc/user/packages/pypi_repository/index.md b/doc/user/packages/pypi_repository/index.md index a6cc5cf1f07..17b51e313fa 100644 --- a/doc/user/packages/pypi_repository/index.md +++ b/doc/user/packages/pypi_repository/index.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/208747) in GitLab Premium 12.10. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. -Publish PyPI packages in your project’s Package Registry. Then install the +Publish PyPI packages in your project's Package Registry. Then install the packages whenever you need to use them as a dependency. The Package Registry works with: @@ -17,6 +17,9 @@ The Package Registry works with: - [pip](https://pypi.org/project/pip/) - [twine](https://pypi.org/project/twine/) +For documentation of the specific API endpoints that the `pip` and `twine` +clients use, see the [PyPI API documentation](../../../api/packages/pypi.md). + ## Build a PyPI package This section explains how to create a PyPI package. @@ -356,3 +359,10 @@ characters are removed. A `pip install` request for `my.package` looks for packages that match any of the three characters, such as `my-package`, `my_package`, and `my....package`. + +## Supported CLI commands + +The GitLab PyPI repository supports the following CLI commands: + +- `twine upload`: Upload a package to the registry. +- `pip install`: Install a PyPI package from the registry. diff --git a/doc/user/packages/rubygems_registry/index.md b/doc/user/packages/rubygems_registry/index.md new file mode 100644 index 00000000000..aa50bc6c2bc --- /dev/null +++ b/doc/user/packages/rubygems_registry/index.md @@ -0,0 +1,137 @@ +--- +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 +--- + +# Ruby gems in the Package Registry **(FREE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/803) in [GitLab Free](https://about.gitlab.com/pricing/) 13.10. + +WARNING: +The Ruby gems registry for GitLab is under development and isn't ready for production use due to +limited functionality. + +You can publish Ruby gems in your project's Package Registry, then install the packages when you +need to use them as a dependency. Although you can push gems to the registry, you cannot install +them from the registry. However, you can download `gem` files directly from the Package Registry's +UI, or by using the [API](../../../api/packages/rubygems.md#download-a-gem-file). + +For documentation of the specific API endpoints that the Ruby gems and Bundler package manager +clients use, see the [Ruby gems API documentation](../../../api/packages/rubygems.md). + +## Enable the Ruby gems registry + +The Ruby gems registry for GitLab is behind a feature flag that is disabled by default. GitLab +administrators with access to the GitLab Rails console can enable this registry for your instance. + +To enable it: + +```ruby +Feature.enable(:rubygem_packages) +``` + +To disable it: + +```ruby +Feature.disable(:rubygem_packages) +``` + +To enable or disable it for specific projects: + +```ruby +Feature.enable(:rubygem_packages, Project.find(1)) +Feature.disable(:rubygem_packages, Project.find(2)) +``` + +## Create a Ruby Gem + +If you need help creating a Ruby gem, see the [RubyGems documentation](https://guides.rubygems.org/make-your-own-gem/). + +## Authenticate to the Package Registry + +Before you can push to the Package Registry, you must authenticate. + +To do this, you can use: + +- A [personal access token](../../../user/profile/personal_access_tokens.md) + with the scope set to `api`. +- A [deploy token](../../project/deploy_tokens/index.md) with the scope set to + `read_package_registry`, `write_package_registry`, or both. +- A [CI job token](#authenticate-with-a-ci-job-token). + +### Authenticate with a personal access token or deploy token + +To authenticate with a personal access token, create or edit the `~/.gem/credentials` file and add: + +```ini +--- +https://gitlab.example.com/api/v4/projects/<project_id>/packages/rubygems: '<your token>' +``` + +- `<your token>` must be the token value of either your personal access token or deploy token. +- Your project ID is on your project's home page. + +### Authenticate with a CI job token + +To work with RubyGems commands within [GitLab CI/CD](../../../ci/README.md), +you can use `CI_JOB_TOKEN` instead of a personal access token or deploy token. + +For example: + +```yaml +image: ruby:latest + +run: + script: +``` + +You can also use `CI_JOB_TOKEN` in a `~/.gem/credentials` file that you check in to +GitLab: + +```ini +--- +https://gitlab.example.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/rubygems: '${env.CI_JOB_TOKEN}' +``` + +## Push a Ruby gem + +Prerequisites: + +- You must [authenticate to the Package Registry](#authenticate-to-the-package-registry). +- The maximum allowed gem size is 3 GB. + +To push your gem, run a command like this one: + +```shell +gem push my_gem-0.0.1.gem --host <host> +``` + +Note that `<host>` is the URL you used when setting up authentication. For example: + +```shell +gem push my_gem-0.0.1.gem --host https://gitlab.example.com/api/v4/projects/1/packages/rubygems +``` + +This message indicates that the gem uploaded successfully: + +```plaintext +Pushing gem to https://gitlab.example.com/api/v4/projects/1/packages/rubygems... +{"message":"201 Created"} +``` + +To view the published gem, go to your project's **Packages & Registries** page. Gems pushed to +GitLab aren't displayed in your project's Packages UI immediately. It can take up to 10 minutes to +process a gem. + +### Pushing gems with the same name or version + +You can push a gem if a package of the same name and version already exists. +Both are visible and accessible in the UI. However, only the most recently +pushed gem is used for installs. + +## Install a Ruby gem + +The Ruby gems registry for GitLab is under development, and isn't ready for production use. You +cannot install Gems from the registry. However, you can download `.gem` files directly from the UI +or by using the [API](../../../api/packages/rubygems.md#download-a-gem-file). diff --git a/doc/user/packages/workflows/project_registry.md b/doc/user/packages/workflows/project_registry.md index c63c2cc9989..3e1c1e7f2ad 100644 --- a/doc/user/packages/workflows/project_registry.md +++ b/doc/user/packages/workflows/project_registry.md @@ -4,7 +4,7 @@ group: Package info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Store all of your packages in one GitLab project +# Store all of your packages in one GitLab project **(FREE)** You can store all of your packages in one project's Package Registry. Rather than using a GitLab repository to store code, you can use the repository to store all your packages. |