A command line interface for smithing Ruby gems.
:toc: macro :toclevels: 5 :figure-caption!:
:containable_link: link:https://alchemists.io/projects/containable[Containable] :infusible_link: link:https://alchemists.io/projects/infusible[Infusible] :ruby_gems_link: link:https://rubygems.org[RubyGems] :sod_link: link:https://alchemists.io/projects/sod[Sod]
= Gemsmith
Gemsmith is a command line interface for smithing Ruby gems. Perfect for when you need a professional and robust tool beyond link:https://bundler.io[Bundler]'s basic gem skeletons. While Bundler is great for creating your first gem, you'll quickly outgrow Bundler when creating and maintaining multiple gems. This is where Gemsmith can increase your productivity by providing much of the tooling you need from the start with the ability to customize as desired.
toc::[]
== Features
== Requirements
. A UNIX-based system. . link:https://www.ruby-lang.org[Ruby]. . {ruby_gems_link}.
== Setup
To install with security, run:
If multiple versions of the same gem are detected, you'll be prompted to pick which gem you want to
edit. Otherwise, the gem will immediately be opened within your default editor (or whatever you
have set in your EDITOR environment variable).
Editing a local gem is a great way to learn from others or quickly debug issues.
==== View
Gemsmith can be used to view existing gem documentation. You can do this by running:
If multiple versions of the same gem are detected, you'll be prompted to pick which gem you want to view. Otherwise, the gem will immediately be opened within your default browser.
Viewing a gem is a great way to learn more about the gem and documentation in general.
=== Configuration
This gem can be configured via a global configuration:
.... $HOME/.config/gemsmith/configuration.yml ....
It can also be configured via link:https://alchemists.io/projects/xdg[XDG] environment variables.
The default configuration is everything provided in the link:https://alchemists.io/projects/rubysmith/#_configuration[Rubysmith] with the addition of the following:
It is recommended that you provide URLs for your project which would be all keys found in this section:
project: uri: # Add sub-key values here.
When these values exist, you'll benefit from having this information added to your generated
gemspec and project documentation. Otherwise -- if these values are empty -- they are removed from
new gem generation.
=== Workflows
When building/testing your gem locally, a typical workflow is:
gemsmith build --name demo
cd demo bundle exec rake
gemsmith --install
=== Security
==== Git Signing Key
To securely sign your Git tags, install and configure link:https://www.gnupg.org[GPG]:
When creating your GPG key, choose these settings:
To obtain your key, run the following and take the part after the forward slash:
Add your key to your global Git configuration in the [user] section. Example:
.... [user] signingkey = ....
Now, when publishing your gems with Gemsmith (i.e. bundle exec rake publish), signing of your Git
tag will happen automatically.
==== Gem Certificates
To create a certificate for your gems, run the following:
The above breaks down as follows:
~/.gem directory is where your credentials and certificates are stored. This is also where the Gem.default_key_path and Gem.default_cert_path methods look for your certificates. I'll talk more about these shortly.gem-private_key.pem and gem-public_cert.pem certificates with a two year duration (i.e. 365 * 2) before expiring. You can also see this information on the {ruby_gems_link} page for your gem (scroll to the bottom). Security-wise, this isn't great but the way {ruby_gems_link} certification is implemented and enforced is weak to begin with. Regardless, this is important to do in order to be a good citizen within the ecosystem. You'll also be prompted for a private key passphrase so make sure it is long and complicated and then store it in your favorite password manager.gems.pem to keep the URL simple but you can name it how you like and document usage for others. For example, here's how you'd add my public certificate (same as done locally but via a URL this time): `gem cert --add --trust-policy HighSecurityTo learn more about gem certificates, check out the RubyGems link:https://guides.rubygems.org/security[Security] documentation.
=== Private Gem Servers
By default, the following command will publicly publish your gem to {ruby_gems_link}:
You can change this behavior by adding metadata to your gemspec that will allow Gemsmith to publish your gem to an alternate/private gem server instead. This can be done by updating your gem specification and RubyGems credentials.
==== Gem Specification Metadata
Add the following gemspec metadata to privately publish new versions of your gem:
The gemspec metadata (i.e. keys and values) must be strings per the link:https://guides.rubygems.org/specification-reference/#metadata[RubyGems Specification].
Use of the allowed_push_host key provides two important capabilities:
$HOME/.gem/credentials file which contains your private
credentials for authentication to your private server (more on this below).==== Gem Credentials
With your gem specification metadata established, you are ready to publish your gem to a public or
private server. If this is your first time publishing a gem and no gem credentials have been
configured, you'll be prompted for them. Gem credentials are stored in the RubyGems
$HOME/.gem/credentials file. From this point forward, future gem publishing will use your stored
credentials instead.
Multiple credentials can be stored in the $HOME/.gem/credentials file as well. Example:
Notice how the first line contains credentials for the public RubyGems server while the second line is for our private example server. You'll also notice that the key is not a symbol but a URL string to our private server. This is important because this is how we link our gem specification metadata to our private credentials. To illustrate further, here are both files truncated and shown together:
....
spec.metadata = {"allowed_push_host" => "https://private.example.com"}
https://private.example.com: Basic dXNlcjpwYXNzd29yZA== ....
When the above are linked together, you enable Gemsmith to publish your gem using only the following command:
This is especially powerful when publishing to link:https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-rubygems-registry[GitHub Packages] which would look like this when properly configured (truncated for brevity while using fake data):
....
spec.metadata = {"allowed_push_host" => "https://rubygems.pkg.github.com/alchemists"}
https://rubygems.pkg.github.com/alchemists: Bearer ghp_c5b8d394abefebbf45c7b27b379c74978923 ....
Lastly, should you need to delete a credential (due to a bad login/password for example), you can
open the $HOME/.gem/credentials in your default editor and remove the line(s) you don't need. Upon
next publish of your gem, you'll be prompted for the missing credentials.
==== Bundler Configuration
So far, I've shown how to privately publish a gem but now we need to teach Bundler how to install the gem as dependency within your upstream project. For demonstration purposes, I'm going to assume you are using GitHub Packages as your private gem server. You should be able to quickly translate this documentation if using an alternate private gem server, though.
The first step is to create your own GitHub Personal Access Token (PAT) which is fast to do by following GitHub's own link:https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token[documentation]. At a minimum, you'll need to enable repo and packages scopes with read/write access.
With your PAT in hand, you'll need to ensure link:https://bundler.io[Bundler] can authenticate to the private GitHub Packages gem server by running the following:
bundle config set --global rubygems.pkg.github.com :
Using Bundler's --global flag ensures you only have to define these credentials once for all
projects which reduces maintenance burden on you. The path to this global configuration can be found
here: $HOME/.config/bundler/configuration.yml.
Lastly, you can add this gem to your Gemfile as follows:
At this point -- if you run bundle install -- you should see the following in your console:
.... Fetching gem metadata from https://rubygems.pkg.github.com/alchemists/... Resolving dependencies...Fetching gem metadata from https://rubygems.org/..... ....
If so, you're all set!
==== GitHub Actions/Packages Automation
Earlier, I hinted at using GitHub Packages but what if you could automate the entire publishing process? Well, good news, you can by using GitHub Actions to publish your packages. Here's the YAML necessary to accomplish this endeavor:
…The above will ensure the following:
main
branch will a new version be automatically published.This entire workflow is explained in my link:https://alchemists.io/talks/ruby_git_hub_packages[talk] on this exact subject too.
== Development
To contribute, run:
You can also use the IRB console for direct access to all objects:
== Test
No open issues yet, or sync has not completed.