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://email@example.com/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://firstname.lastname@example.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:email@example.com/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
That would mean that you want the HTTPS_URL to be
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: “firstname.lastname@example.org” —> “user%40example%2Eorg”
- password: “:password!” —> “%2Apassword%21”
This will then give you an HTTPS address as:
Let’s drop this into the Gemfile!
# Gemfile gem "ruby_my_gem", git: "https://user%40example%2Eorg:%2Apasswordemail@example.com/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 firstname.lastname@example.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.