Working with the RubyGems registry

You can configure RubyGems to publish a package to GitHub Packages and to use packages stored on GitHub Packages as dependencies in a Ruby project with Bundler.

GitHub Packages is available with GitHub Free, GitHub Pro, GitHub Free for organizations, GitHub Team, GitHub Enterprise Cloud, GitHub Enterprise Server 3.0 or higher, and GitHub AE. For more information about upgrading your GitHub Enterprise Server instance, see "About upgrades to new releases" and refer to the Upgrade assistant to find the upgrade path from your current release version.

注:这种包类型可能不适用于您的实例,因为站点管理员可以启用或禁用每种支持的包类型。 更多信息请参阅“为企业配置软件包支持”。

Prerequisites

  • 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

Authenticating to GitHub Packages

You need an access token to publish, install, and delete packages.

You can use a personal access token (PAT) to authenticate to GitHub Packages or the GitHub Enterprise Server API. When you create a personal access token, you can assign the token different scopes depending on your needs. For more information about packages-related scopes for a PAT, see "About permissions for GitHub Packages."

To authenticate to a GitHub Packages registry within a GitHub Actions workflow, you can use:

  • GITHUB_TOKEN to publish packages associated with the workflow repository.
  • a PAT to install packages associated with other private repositories (which GITHUB_TOKEN can't access).

有关 GitHub Actions 工作流程中使用的 GITHUB_TOKEN 的更多信息,请参阅“工作流程中的身份验证”。

Authenticating with a personal access token

您必须使用具有适当范围的个人访问令牌才可在 GitHub Packages 中发布和安装。 更多信息请参阅“关于 GitHub Packages”。

You can authenticate to GitHub Packages 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 GitHub Packages 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 TOKEN

To install gems, you need to authenticate to GitHub Packages by editing the ~/.gemrc file for your project to include https://USERNAME:TOKEN@REGISTRY-URL/OWNER/. You must replace:

  • USERNAME with your GitHub username.
  • TOKEN with your personal access token.
  • OWNER with the name of the user or organization account that owns the repository containing your project.
  • 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 GitHub Enterprise Server instance.

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@REGISTRY-URL/OWNER/
:update_sources: true
:verbose: true  

To authenticate with Bundler, configure Bundler to use your personal access token, replacing USERNAME with your GitHub 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. 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 GitHub Enterprise Server instance.

$ bundle config https://REGISTRY-URL/OWNER USERNAME:TOKEN

Publishing a package

默认情况下,GitHub 将包发布到名称与包相同的现有仓库中。 For example, when you publish octo-gem to the octo-org organization, GitHub Packages 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.

在发布包后,您可以在 GitHub 上查看该包。 更多信息请参阅“查看包”。

  1. 向 GitHub Packages 验证。 更多信息请参阅“向 GitHub Packages 验证”。

  2. Build the package from the gemspec to create the .gem package.

    gem build OCTO-GEM.gemspec
  3. Publish a package to GitHub Packages, replacing OWNER with the name of the user or organization account that owns the repository containing your project and OCTO-GEM with the name of your gem package. 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 host name of your GitHub Enterprise Server instance.

    $ gem push --key github \
    --host https://REGISTRY-URL/OWNER \
    OCTO-GEM-0.0.1.gem

Publishing multiple packages to the same repository

To publish multiple gems to the same repository, you can include the URL to the GitHub repository in the github_repo field in gem.metadata. If you include this field, GitHub matches the repository based on this value, instead of using the gem name. Replace HOSTNAME with the host name of your GitHub Enterprise Server instance.

gem.metadata = { "github_repo" => "ssh://HOSTNAME/OWNER/REPOSITORY" }

Installing a package

You can use gems from GitHub Packages much like you use gems from rubygems.org. You need to authenticate to GitHub Packages by adding your GitHub user or organization as a source in the ~/.gemrc file or by using Bundler and editing your Gemfile.

  1. 向 GitHub Packages 验证。 更多信息请参阅“向 GitHub Packages 验证”。

  2. For Bundler, add your GitHub 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 GitHub Packages only for the packages you specify, replacing GEM NAME with the package you want to install from GitHub Packages and OWNER with the user or organization that owns the repository containing the gem you want to install. 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 host name of your GitHub Enterprise Server instance.

    source "https://rubygems.org"
    
    gem "rails"
    
    source "https://REGISTRY-URL/OWNER" do
      gem "GEM NAME"
    end
    
  3. 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://REGISTRY-URL/OWNER"
    source "https://rubygems.org"
    
    gem "rails"
    gem "GEM NAME"
    
  4. Install the package:

    $ gem install octo-gem --version "0.1.1"

Further reading

此文档对您有帮助吗?

隐私政策

帮助我们创建出色的文档!

所有 GitHub 文档都是开源的。看到错误或不清楚的内容了吗?提交拉取请求。

做出贡献

或者, 了解如何参与。