RubyGems package registry documentation

c823ebd6 · Steve Abrams · Nick Gaskill · 204238b3 · c823ebd6 · c823ebd6
Commit c823ebd6 authored Apr 09, 2021 by Steve Abrams Committed by Nick Gaskill Apr 09, 2021
3 changed files
--- a/doc/api/packages/rubygems.md
+++ b/doc/api/packages/rubygems.md
+---
+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 API
+
+This is the API documentation for [Ruby gems](../../user/packages/rubygems_registry/index.md).
+
+WARNING:
+This API is used by the [Ruby gems and Bundler package manager clients](https://maven.apache.org/)
+and is generally not meant for manual consumption. This API is under development and is not ready
+for production use due to limited functionality.
+
+For instructions on how to upload and install gems from the GitLab
+package registry, see the [Ruby gems registry documentation](../../user/packages/rubygems_registry/index.md).
+
+NOTE:
+These endpoints do not adhere to the standard API authentication methods.
+See the [Ruby gems registry documentation](../../user/packages/rubygems_registry/index.md)
+for details on which headers and token types are supported.
+
+## Enable the Ruby gems API
+
+The Ruby gems API for GitLab is behind a feature flag that is disabled by default. GitLab
+administrators with access to the GitLab Rails console can enable this API 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))
+```
+
+## Download a gem file
+
+> Introduced in GitLab 13.10.
+
+Download a gem:
+
+```plaintext
+GET projects/:id/packages/rubygems/gems/:file_name
+```
+
+| Attribute    | Type   | Required | Description |
+| ------------ | ------ | -------- | ----------- |
+| `id`         | string | yes      | The ID or full path of the project. |
+| `file_name`  | string | yes      | The name of the `.gem` file. |
+
+```shell
+curl --header "Authorization:<personal_access_token>" "https://gitlab.example.com/api/v4/projects/1/packages/rubygems/gems/my_gem-1.0.0.gem"
+```
+
+Write the output to file:
+
+```shell
+curl --header "Authorization:<personal_access_token>" "https://gitlab.example.com/api/v4/projects/1/packages/rubygems/gems/my_gem-1.0.0.gem" >> my_gem-1.0.0.gem
+```
+
+This writes the downloaded file to `my_gem-1.0.0.gem` in the current directory.
+
+## Fetch a list of dependencies
+
+> Introduced in GitLab 13.10.
+
+Fetch a list of dependencies for a list of gems:
+
+```plaintext
+GET projects/:id/packages/rubygems/api/v1/dependencies
+```
+
+| Attribute | Type   | Required | Description |
+| --------- | ------ | -------- | ----------- |
+| `id`      | string | yes      | The ID or full path of the project. |
+| `gems`    | string | no       | Comma-separated list of gems to fetch dependencies for. |
+
+```shell
+curl --header "Authorization:<personal_access_token>" "https://gitlab.example.com/api/v4/projects/1/packages/rubygems/api/v1/dependencies?gems=my_gem,foo"
+```
+
+This endpoint returns a marshalled array of hashes for all versions of the requested gems. Since the
+response is marshalled, you can store it in a file. If Ruby is installed, you can use the following
+Ruby command to read the response. For this to work, you must
+[set your credentials in `~/.gem/credentials`](../../user/packages/rubygems_registry/index.md#authenticate-with-a-personal-access-token-or-deploy-token):
+
+```shell
+$ ruby -ropen-uri -rpp -e \
+  'pp Marshal.load(open("https://gitlab.example.com/api/v4/projects/1/packages/rubygems/api/v1/dependencies?gems=my_gem,rails,foo"))'
+
+[{:name=>"my_gem", :number=>"0.0.1", :platform=>"ruby", :dependencies=>[]},
+ {:name=>"my_gem",
+  :number=>"0.0.3",
+  :platform=>"ruby",
+  :dependencies=>
+   [["dependency_1", "~> 1.2.3"],
+    ["dependency_2", "= 3.0.0"],
+    ["dependency_3", ">= 1.0.0"],
+    ["dependency_4", ">= 0"]]},
+ {:name=>"my_gem",
+  :number=>"0.0.2",
+  :platform=>"ruby",
+  :dependencies=>
+   [["dependency_1", "~> 1.2.3"],
+    ["dependency_2", "= 3.0.0"],
+    ["dependency_3", ">= 1.0.0"],
+    ["dependency_4", ">= 0"]]},
+ {:name=>"foo",
+  :number=>"0.0.2",
+  :platform=>"ruby",
+  :dependencies=>
+    ["dependency_2", "= 3.0.0"],
+    ["dependency_4", ">= 0"]]}]
+```
+
+This writes the downloaded file to `mypkg-1.0-SNAPSHOT.jar` in the current directory.
+
+## Upload a gem
+
+> Introduced in GitLab 13.11.
+
+Upload a gem:
+
+```plaintext
+POST projects/:id/packages/rubygems/api/v1/gems
+```
+
+| Attribute | Type   | Required | Description |
+| --------- | ------ | -------- | ----------- |
+| `id`      | string | yes      | The ID or full path of the project. |
+
+```shell
+curl --request POST \
+     --upload-file path/to/my_gem_file.gem \
+     --header "Authorization:<personal_access_token>" \
+     "https://gitlab.example.com/api/v4/projects/1/packages/rubygems/api/v1/gems"
+```
--- a/doc/user/packages/index.md
+++ b/doc/user/packages/index.md
@@ -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) |

--- a/doc/user/packages/rubygems_registry/index.md
+++ b/doc/user/packages/rubygems_registry/index.md
+---
+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
+
+> [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).