1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
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).
|
