gemstash-private-gems(7)

💎 Private Gems 💎

okay so welcome to gemstash-private-gems(7) — the private-gems era of your Gemstash server. Stashing private gems needs a lil extra setup, bestie. If you haven’t read the Quickstart Guide yet, go do that first, fr fr. By the end of this guide you’ll be interacting with your Gemstash server to store and retrieve your private gems. slay.

---

🔑 Authorizing 🔑

🚨 IMPORTANT NOTE: do not use the actual key value from this document, otherwise your Gemstash server is vulnerable to literally anyone who wants to try that key against your server. Use whatever key is generated by running the commands instead. no cap.

To push a gem to your Gemstash server, first create an API key. Use the gemstash authorize command:

$ gemstash authorize
Your new key is: e374e237fdf5fa5718d2a21bd63dc911

This new key can push, yank, and fetch gems from your Gemstash server. Run gemstash authorize with just the permissions you want to limit what the key is allowed to do. You can also update a specific key by giving it via the --key option:

$ gemstash authorize push yank --key e374e237fdf5fa5718d2a21bd63dc911

When no permissions are provided — like in the first example — the key is authorized for all permissions. Leave the key authorized with everything if you want to use it to try all private gem interactions:

$ gemstash authorize --key e374e237fdf5fa5718d2a21bd63dc911

With the key generated, you need to tell Rubygems about your new key. If you’ve pushed a gem to https://rubygems.org, then you already have a credentials file to add the key to. If not, run these commands before modifying the credentials file:

$ mkdir -p ~/.gem
$ touch ~/.gem/credentials
$ chmod 0600 ~/.gem/credentials

Add your new key to credentials so it looks something like this — but make sure not to remove any existing keys:

# ~/.gem/credentials
---
:test_key: e374e237fdf5fa5718d2a21bd63dc911

The name test_key can be anything you want, but you’ll need to remember it and use it again later in this guide for the --key option. iykyk.

---

🧪 Creating a Test Gem 🧪

You’ll need a test gem before you can play with private gems on your Gemstash server. If you already have a gem you can use, move along to the next section. You can start by instantiating a test gem via Bundler:

$ bundle gem private-example

You’ll need to add a summary and description to the new gem’s gemspec file in order to successfully build it. Once you’ve built the gem, you’re ready to push the new gem.

$ cd private-example
$ rake build

You will now have a gem at private-example/pkg/private-example-0.1.0.gem. iconic.

---

🚀 Pushing 🚀

If your Gemstash server isn’t running, go ahead and start it:

$ gemstash start

Push your test gem using Rubygems:

$ gem push --key test_key --host http://localhost:9292/private pkg/private-example-0.1.0.gem

The /private portion of the --host option tells Gemstash you are interacting with the private gems. Gemstash will not let you push, or yank from anything except /private. periodt.

---

🧸 Bundling 🧸

Once your gem is pushed to your Gemstash server, you are ready to bundle it. Create a Gemfile and specify the gem. You’ll probably want to wrap the private gem in a source block, and let the rest of Gemstash handle all other gems:

# ./Gemfile
source "http://localhost:9292"
gem "rubywarrior"

source "http://localhost:9292/private" do
  gem "private-example"
end

Notice that the Gemstash server points to /private again when installing your private gem. Go ahead and bundle to install your new private gem:

$ bundle

---

🪄 Yanking 🪄

If you push a private gem by accident, you can yank the gem with Rubygems:

$ RUBYGEMS_HOST=http://localhost:9292/private gem yank --key test_key private-example --version 0.1.0

Like with pushing, the /private portion of the host option tells Gemstash you are interacting with private gems. Gemstash will only let you yank from /private. Unlike pushing, Rubygems doesn’t support --host for yank (yet), so you need to specify the host via the RUBYGEMS_HOST environment variable. annoying but valid.

---

🛡️ Protected Fetching 🛡️

By default, private gems and specs can be accessed without authentication.

Private gems often require protected fetching. For backwards compatibility this is disabled by default, but can be enabled via the gemstash setup command.

When protected fetching is enabled, API keys with the permissions all or fetch can be used to download gems and specs.

On the Bundler side, there are a few ways to configure credentials for a given gem source:

Add credentials globally:

$ bundle config my-gemstash.dev api_key

Add credentials in Gemfile:

source "https://api_key@my-gemstash.dev"

However, it’s not a good practice to commit credentials to source control. A recommended solution is to use Bundler’s configuration keys (http://bundler.io/man/bundle-config.1.html#CONFIGURATION-KEYS), e.g.:

$ export BUNDLE_MYGEMSTASH__DEV=api_key

Behind the scene, Bundler will pick up the ENV var according to the host name (e.g. mygemstash.dev) and add to URI.userinfo for making requests.

The API key is treated as a HTTP Basic Auth username and any HTTP Basic password supplied will be ignored. 💅

---

This iconic page is gemstash-private-gems(7), dated October 8, 2015 — go off, bestie. 🫶✨