Create a gem project

To create a new gem skeleton, use Bundler’s gem command:

bundle gem my_gem
cd my_gem

This generates a my_gem.gemspec file. Fill in the required metadata before building:

Gem::Specification.new do |spec|
  spec.name    = "my_gem"
  spec.version = "1.0.0"
  spec.authors = ["Your Name"]
  spec.email   = ["[email protected]"]
  spec.summary = "A sample gem published to Repsy."
  spec.files   = Dir["lib/**/*", "README.md"]
end

Build the .gem archive:

gem build my_gem.gemspec

This produces my_gem-1.0.0.gem in the current directory.

Store credentials

Gem push credentials are kept in ~/.gem/credentials. Repsy expects a Basic auth value (Base64-encoded username:password). Run the following command — replace <username> and <password-or-token> with your actual values:

echo ":repsy: Basic $(echo -n '<username>:<password-or-token>' | base64)" \
  >> ~/.gem/credentials
chmod 0600 ~/.gem/credentials

The echo -n flag suppresses the trailing newline so the base64 encoding is correct. After running the command, ~/.gem/credentials will contain a line like:

---
:repsy: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Tip: For CI/CD pipelines, use a Deploy Token instead of your account password.

With a deploy token, the username can be any value: Repsy checks only the token. If the ~/.gem directory does not exist yet, create it first with mkdir -p ~/.gem. RubyGems refuses to use a credentials file that other users can read, which is why the commands end with chmod 0600. The tutorial Publishing and Installing Gems with gem shows the other ways to hand the key to gem push.

Push the gem

Use gem push with the --host flag pointing to your Repsy repository and --key matching the credential entry you added above:

gem push my_gem-1.0.0.gem \
  --host https://<your-repsy-host>/<repo-name> \
  --key repsy

Replace <repo-name> with the name of your repository. There is no username in the address, and https://<your-repsy-host> stands for the address of the package protocol port of your instance, for example http://localhost:9090 for a local start, see Ports and Repository URLs. If gem push refuses the gem because the allowed_push_host of the gemspec does not match this address, remove that line from the gemspec or set it to the address of your repository. bundle gem generates a gemspec with the line.

Congratulations, you have published a gem to your Repsy repository! You can now install it in any Ruby project.

Yank a gem version

If you need to remove a specific version from your repository, use gem yank:

gem yank my_gem -v 1.0.0 \
  --host https://<your-repsy-host>/<repo-name> \
  --key repsy

Add --platform <platform> for a gem that was built for a platform other than ruby, for example java; without it, Repsy looks for the ruby platform of that version.

Note: Yanking a version removes it from the index, so gem install and Bundler no longer find it, and it cannot be pushed again under the same version number. Its .gem file stays downloadable from its exact address. Yanking needs the password of an administrator or a Read/Write deploy token, and gem yank exits with 0 even when Repsy refuses the request, so read its output. See Yanking Gems.