How to use a gem in a private GitHub repo in your Rails application

Developers love to separate concerns - it's one of our main principles. One of the best ways to do this is to extract libraries, which are called gems in Ruby. Gems are normally released through RubyGems. However, this makes your lib available to the public, which can be problematic if the gem serves a meaningful purpose in your business logic.

In order to avoid that, you can make your gem private. It requires a bit of tinkering, but this article should help you get everything set up without having to jump through hoops (because I jumped through them for you 😭).

Step 1 - Setup your Gemfile

Like any other Gems, your private gem needs to be listed in your Gemfile – but you can add options to specify where Bundler will look for the gem.

I recommend using the git option, which requires a link to a git repository with a .gemspec file at its root. Make sure to use a HTTPS link.👇

# Use a https link. It's important for the authentication part.
gem "your_gem", git: "https://github.com/<owner>/<repo>.git", branch: "your_branch"

There are other ways of implementing this → full list here.

Step 2 - Authentication

Since your gem is private, not anybody can access its code. That means your Bundler should be configured to be successfully authenticated when running any bundle command. Otherwise, you'll see an error message such as this one:

fatal: Authentication failed for 'path_to_your_gem.git'

Congrats, you've selected HTTPS authentication 😎 so this should now be a piece of cake.

Create a personal access token

Go to https://github.com/settings/tokens. Click on "Generate new token" with the "repo" scope. Select the expiration you want, give it a name and click the big green button.
Copy the newly generated token. Don't lose it, this is the last time you'll be able to see it ! Don't worry, you can always generate a new one.
Create a new key BUNDLE_GITHUB__COM in your .env file and paste the key you copied above as its value☝️

Voilà ! You should now be able to successfully run bundle install 😙

Step 3 - Deploying

You can now use your gem on your local machine. That's great, but web developers usually push their code somewhere, right ? 🤨

Github Actions

You can specify env variables when running Github Actions, and that's what we'll use for authentication. Go to your repo's secrets page (https://github.com/[user]/[repo]/settings/secrets/actions) and create a repository secret with the access token you generated in Step 2. You can use it in your workflow file like so:

name: your_job

jobs:
  your_job:
    runs-on: ubuntu-latest
    env:
      BUNDLE_GITHUB__COM: "x-access-token:${{ secrets.YOUR_SECRET_NAME }}"

Heroku

Simply add the same BUNDLE_GITHUB__COM env variable as in your .env in your dyno configuration.

Let me know if I missed anything in the comments – and if I didn't, tell me how that worked out for you 😉