When you publish version 1.0 of a gem with gem push, how do RubyGems API keys, MFA and --otp work, and which gemspec metadata hardens the release?

## The publishing path Publishing a gem is two commands: `gem build` writes `hue_palette-1.0.0.gem`, and `gem push hue_palette-1.0.0.gem` uploads it to the push server (rubygems.org unless told otherwise), which adds it to the index so `gem install hue_palette` can find it. Everything interesting is in **how the push is authorised**. ## API keys and scopes `gem push` authenticates with an **API key**, looked up in this order: 1. the `GEM_HOST_API_KEY` environment variable; 2. a named key chosen with `-k, --key NAME` from the credentials file; 3. a key stored for that specific host; 4. the default rubygems.org key. If there is none, `gem push` signs you in first. Signing in asks for your username or email and password and creates a new API key with **scopes**: - `index_rubygems` and `push_rubygem` are offered by default; - `yank_rubygem`, `add_owner`, `remove_owner` and `access_webhooks` can be added; - `show_dashboard` is an exclusive scope: a key that has it gets no other scope. The key is written to the **credentials file**, `~/.gem/credentials` (or the XDG data directory when that file does not exist); `gem env credentials` prints the path. If a key lacks the scope a command needs, `gem` says the existing key doesn't have that access and asks you to sign in again to add the scope. ## MFA and --otp When the account has **multi-factor authentication** enabled, the server answers a push, yank, owner change or sign-in with an unauthorised response that starts `You have enabled multifactor authentication`. `gem` then: - prints `You have enabled multi-factor authentication. Please enter OTP code.` and waits for a code from your authenticator app, or - when a security key is registered, prints a **WebAuthn** URL to visit and polls until you have verified. To avoid the prompt, pass the code up front: - `gem push hue_palette-1.0.0.gem --otp 123456` - or `GEM_HOST_OTP_CODE=123456 gem push hue_palette-1.0.0.gem` The `--otp` option exists on `gem push`, `gem yank`, `gem owner` and `gem signin`. Codes are short-lived, so a script that needs one is really an interactive release. ## Metadata that hardens a gem Two gemspec `metadata` keys change what publishing allows: | Key | Effect | |---|---| | `rubygems_mfa_required` = `"true"` | rubygems.org requires MFA for pushes of this gem, so every owner must pass a second factor | | `allowed_push_host` = a URL | `gem push` pushes there by default and refuses any other host | `allowed_push_host` protects against the opposite accident as well: a private gem whose gemspec names an internal server cannot be pushed to rubygems.org by mistake, because `gem push` stops with `... is not allowed by the gemspec, which only allows ...`. For a public gem, set it to `https://rubygems.org` or leave it out; the placeholder that `bundle gem` generates must not be left as is. ## Owners and automation - **Owners.** `gem owner hue_palette --add USER` and `--remove USER` manage who may push; these calls also need the matching `add_owner` or `remove_owner` scope and an MFA code when MFA is on. - **Several owners** mean a release does not depend on one person's account, and each owner's account should have MFA. - **Automated pushes** read the key from `GEM_HOST_API_KEY`, which a CI system stores as a secret. Give that key only `push_rubygem`, and remember that `rubygems_mfa_required` will then refuse pushes that cannot supply a code; keyless publishing from CI is a separate mechanism with its own setup. ## Habits for a 1.0 release - Enable MFA on the account and set `rubygems_mfa_required`, so a leaked API key alone cannot publish. - Keep API keys narrow: a key used for pushing does not need `add_owner`. - Never commit the credentials file or put `GEM_HOST_API_KEY` in a repository; treat it like a password. - Push from a clean checkout and a freshly built `.gem`, after inspecting its file list. - Add co-owners with `gem owner hue_palette --add ...` so a release does not depend on one person's account.