All Ruby and Rails developers need to use Ruby gems for common work. It’s also a great practice for you to create your own Gems to separate functionality that you can reuse across your projects. You can publish your gems to the world using the RubyGems site which is the starting point for almost all gems!

However, you might also have gems that you do not want to publish to the world and have it in a private repository. You can still use Bundler but there are a couple of things to keep in mind. If you do a search, you will usually find examples for GitHub, so this is a quick post on what you need to do for BitBucket.

Basically, you need to add this to your Gemfile.

# Gemfile
gem "ruby_my_gem", git: HTTPS_URL

So, how do we get the HTTPS_URL? Grab the link that you would use to clone the gem. Let’s say it looked like this:

git clone https://the_user_name@bitbucket.org/the_org/ruby-my-gem.git

Of course, in this, these would be different for you:

• the_user_name: your user name (someone who has access to the repository)
• the_org: your organisation (the owner of the gem)
• my-gem.git: the actual Git repository

If you add this to your Gemfile as:

# Gemfile
gem "ruby_my_gem", git: "https://the_user_name@bitbucket.org/the_org/ruby-my-gem.git"

and then do bundle install – you will probably get an authentication error if the repository is private.

For this, you need to use HTTP authentication by changing the URL to https://user:password@bitbucket.org/the_org/ruby-my-gem.git so that the user name and password are used. You can either use your own user name and password, or use it from cache, or as environment variables, etc.

So, next, you need your BitBucket login (or the login for any user that has access to the gem). Usually, this will be:

• an email address
• password

That would mean that you want the HTTPS_URL to be

https://user_email@example.org:password@bitbucket.org/the_org/ruby-my-gem.git

You’ll notice immediately that it looks odd that there are 2 @ symbols in the URL – so, that won’t work!

What we need to do is use URL Encoding/ percent encoding for special symbols. You can find the percent-encoding list on Wikipedia but keep in mind that you need to escape all the special characters. This needs to be done for both the user email and the password. Specifically, you will need to escape characters like the following:

• @ – %40
• . – %2E
• ! – %21
• : – %2A
• ; – %3B
• (space) – %20

The picture below is a snapshot from the Wikipedia page of the reserved characters.

The picture below is a snapshot from the Wikipedia page of the commonly used characters.

So, if you (for example) had:

• user_name: “user@example.org” —> “user%40example%2Eorg”
• password: “:password!” —> “%2Apassword%21”

This will then give you an HTTPS address as:

https://user%40example%2Eorg:%2Apassword%21@bitbucket.org/the_org/ruby-my-gem.git

Let’s drop this into the Gemfile!

# Gemfile
gem "ruby_my_gem", git: "https://user%40example%2Eorg:%2Apassword%21@bitbucket.org/the_org/ruby-my-gem.git"

After this, you can do bundle install and it should work. Remember that you might need to do bundle exec ruby blah.rb to be able to use the gem.

Using an API Token

Bitbucket/ Atlassian allows you to issue an API Token and the documentation says that you can use it for HTTP basic authentication. However, I could not get it to work from within Bundler. I tried:

• Using the email_address:api_token and seeing if it works
• Using just the api_token@bitbucket.org to see if that works

For now, I am not sure if this works the way it seems to work on GitHub.

As always, this is for me to be able to remember how to do it but if it helps someone, that’s great! Also, if you have some comments, please add below so that I can reflect changes here, especially if you know a better way to do this.