title | intro | product | redirect_from | versions | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Configuring RubyGems for use with GitHub Packages |
You can configure RubyGems to publish a package to {% data variables.product.prodname_registry %} and to use packages stored on {% data variables.product.prodname_registry %} as dependencies in a Ruby project with Bundler. |
{% data reusables.gated-features.packages %} |
|
|
{% data reusables.package_registry.packages-ghes-release-stage %} {% data reusables.package_registry.packages-ghae-release-stage %}
{% data reusables.package_registry.admins-can-configure-package-types %}
-
You must have rubygems 2.4.1 or higher. To find your rubygems version:
$ gem --version
- You must have bundler 1.6.4 or higher. To find your Bundler version:
$ bundle --version Bundler version 1.13.7
- Install keycutter to manage multiple credentials. To install keycutter:
$ gem install keycutter
{% data reusables.package_registry.authenticate-packages %}
{% data reusables.package_registry.required-scopes %}
You can authenticate to {% data variables.product.prodname_registry %} with RubyGems by editing the ~/.gem/credentials file for publishing gems, editing the ~/.gemrc file for installing a single gem, or using Bundler for tracking and installing one or more gems.
To publish new gems, you need to authenticate to {% data variables.product.prodname_registry %} with RubyGems by editing your ~/.gem/credentials file to include your personal access token. Create a new ~/.gem/credentials file if this file doesn't exist.
For example, you would create or edit a ~/.gem/credentials to include the following, replacing TOKEN with your personal access token.
---
:github: Bearer <em>TOKEN</em>
To install gems, you need to authenticate to {% data variables.product.prodname_registry %} by editing the ~/.gemrc file for your project to include https://USERNAME:TOKEN@{% if currentVersion == "free-pro-team@latest" %}rubygems.pkg.github.com{% else %}REGISTRY-URL{% endif %}/OWNER/
. You must replace:
USERNAME
with your {% data variables.product.prodname_dotcom %} username.TOKEN
with your personal access token.OWNER
with the name of the user or organization account that owns the repository containing your project.{% if enterpriseServerVersions contains currentVersion %}REGISTRY-URL
with the URL for your instance's Rubygems registry. If your instance has subdomain isolation enabled, userubygems.HOSTNAME
. If your instance has subdomain isolation disabled, useHOSTNAME/_registry/rubygems
. In either case, replace HOSTNAME with the hostname of your {% data variables.product.prodname_ghe_server %} instance. {% elsif currentVersion == "github-ae@latest" %}REGISTRY-URL
with the URL for your instance's Rubygems registry,rubygems.HOSTNAME
. Replace HOSTNAME with the hostname of {% data variables.product.product_location %}. {% endif %}
If you don't have a ~/.gemrc file, create a new ~/.gemrc file using this example.
---
:backtrace: false
:bulk_threshold: 1000
:sources:
- https://rubygems.org/
- https://USERNAME:TOKEN@{% if currentVersion == "free-pro-team@latest" %}rubygems.pkg.github.com{% else %}REGISTRY-URL{% endif %}/OWNER/
:update_sources: true
:verbose: true
To authenticate with Bundler, configure Bundler to use your personal access token, replacing USERNAME with your {% data variables.product.prodname_dotcom %} username, TOKEN with your personal access token, and OWNER with the name of the user or organization account that owns the repository containing your project.{% if enterpriseServerVersions contains currentVersion %} Replace REGISTRY-URL
with the URL for your instance's Rubygems registry. If your instance has subdomain isolation enabled, use rubygems.HOSTNAME
. If your instance has subdomain isolation disabled, use HOSTNAME/_registry/rubygems
. In either case, replace HOSTNAME with the hostname of your {% data variables.product.prodname_ghe_server %} instance.{% elsif currentVersion == "github-ae@latest" %}Replace REGISTRY-URL
with the URL for your instance's Rubygems registry, rubygems.HOSTNAME
. Replace HOSTNAME with the hostname of {% data variables.product.product_location %}.{% endif %}
$ bundle config https://{% if currentVersion == "free-pro-team@latest" %}rubygems.pkg.github.com{% else %}REGISTRY-URL{% endif %}/<em>OWNER USERNAME:TOKEN</em>
{% data reusables.package_registry.package-registry-with-github-tokens %}
{% data reusables.package_registry.default-name %} For example, when you publish octo-gem
to the octo-org
organization, {% data variables.product.prodname_registry %} publishes the gem to the octo-org/octo-gem
repository. For more information on creating your gem, see "Make your own gem" in the RubyGems documentation.
{% data reusables.package_registry.viewing-packages %}
{% data reusables.package_registry.authenticate-step %} 2. Build the package from the gemspec to create the .gem package.
gem build OCTO-GEM.gemspec
- Publish a package to {% data variables.product.prodname_registry %}, replacing
OWNER
with the name of the user or organization account that owns the repository containing your project andOCTO-GEM
with the name of your gem package.{% if enterpriseServerVersions contains currentVersion %} ReplaceREGISTRY-URL
with the URL for your instance's Rubygems registry. If your instance has subdomain isolation enabled, userubygems.HOSTNAME
. If your instance has subdomain isolation disabled, useHOSTNAME/_registry/rubygems
. In either case, replace HOSTNAME with the host name of your {% data variables.product.prodname_ghe_server %} instance.{% elsif currentVersion == "github-ae@latest" %} ReplaceREGISTRY-URL
with the URL for your instance's Rubygems registry,rubygems.HOSTNAME
. Replace HOSTNAME with the hostname of {% data variables.product.product_location %}.{% endif %}
$ gem push --key github \
--host https://{% if currentVersion == "free-pro-team@latest" %}rubygems.pkg.github.com{% else %}REGISTRY-URL{% endif %}/<em>OWNER</em> \
<em>OCTO-GEM-0.0.1</em>.gem
To publish multiple gems to the same repository, you can include the URL to the {% data variables.product.prodname_dotcom %} repository in the github_repo
field in gem.metadata
. If you include this field, {% data variables.product.prodname_dotcom %} matches the repository based on this value, instead of using the gem name.{% if enterpriseServerVersions contains currentVersion or currentVersion == "github-ae@latest" %} Replace HOSTNAME with the host name of {% data variables.product.product_location %}.{% endif %}
gem.metadata = { "github_repo" => "ssh://{% if currentVersion == "free-pro-team@latest" %}github.com{% else %}HOSTNAME{% endif %}/OWNER/REPOSITORY" }
You can use gems from {% data variables.product.prodname_registry %} much like you use gems from rubygems.org. You need to authenticate to {% data variables.product.prodname_registry %} by adding your {% data variables.product.prodname_dotcom %} user or organization as a source in the ~/.gemrc file or by using Bundler and editing you Gemfile.
{% data reusables.package_registry.authenticate-step %}
- For Bundler, add your {% data variables.product.prodname_dotcom %} user or organization as a source in your Gemfile to fetch gems from this new source. For example, you can add a new
source
block to your Gemfile that uses {% data variables.product.prodname_registry %} only for the packages you specify, replacing GEM NAME with the package you want to install from {% data variables.product.prodname_registry %} and OWNER with the user or organization that owns the repository containing the gem you want to install.{% if enterpriseServerVersions contains currentVersion %} ReplaceREGISTRY-URL
with the URL for your instance's Rubygems registry. If your instance has subdomain isolation enabled, userubygems.HOSTNAME
. If your instance has subdomain isolation disabled, useHOSTNAME/_registry/rubygems
. In either case, replace HOSTNAME with the host name of your {% data variables.product.prodname_ghe_server %} instance.{% elsif currentVersion == "github-ae@latest" %} ReplaceREGISTRY-URL
with the URL for your instance's Rubygems registry,rubygems.HOSTNAME
. Replace HOSTNAME with the hostname of {% data variables.product.product_location %}.{% endif %}
source "https://rubygems.org"
gem "rails"
source "https://{% if currentVersion == "free-pro-team@latest" %}rubygems.pkg.github.com{% else %}REGISTRY-URL{% endif %}/OWNER" do
gem "GEM NAME"
end
- For Bundler versions earlier than 1.7.0, you need to add a new global
source
. For more information on using Bundler, see the bundler.io documentation.
source "https://{% if currentVersion == "free-pro-team@latest" %}rubygems.pkg.github.com{% else %}REGISTRY-URL{% endif %}/OWNER"
source "https://rubygems.org"
gem "rails"
gem "GEM NAME"
- Install the package:
$ gem install octo-gem --version "0.1.1"
- "{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %}Deleting and restoring a package{% elsif currentVersion ver_lt "enterprise-server@3.1" or currentVersion == "github-ae@latest" %}Deleting a package{% endif %}"