After a recent laptop upgrade, I needed to reset my access to BitBucket from my new laptop, and figured this post might save some hassles for other folks trying to do the same.
Sticking with Windows for my OS when most other developers have moved to Mac might strike some readers as a strange thing: for me, it is a mixture of wanting the OS to be something I never think about (I care much more about the setup of my Chrome browser) as well as always being a bootstrapper (the equivalent Mac to my Samsung Ultrabook is another 30% more) means I’d rather stick with Windows (until I can really do without MS Office, at which point I’ll happily go Linux, but Google Docs isn’t there yet and being a CEO means a lot of spreadsheet and presentation work).
The problem, though, is being an outlier from a dev perspective means the instructions/process isn’t always so clear – now we know how Mac users have felt for 20 years!
SourceTree and PuttyGen/Pageant
When you’re using SourceTree you’ll probably be using it alongside the excellent Putty package (download it here; I recommend using the “Windows Installer” option half way down the page). When installed, this package includes a handful of utilities; the three we care about here are:
- PuTTY: this is used for making SSH connections. You don’t actually need it for SourceTree things, but you’ll almost certainly need it for lots of other things.
- Pageant: this is a background, resident app that handles the SSH handshake from your Windows apps, including SourceTree.
- PuTTYgen: this is the key generation app for Windows which makes it easy to create public/private keys.
The process of getting SourceTree to work nicely with key based access is:
- Use PuTTYgen to create a public/private key pair. Save the private key to somewhere safe on your local machine.
- Select/copy the public key section (the bit in the top grey window of PuTTYgen when the key has been created) and paste it in as a new SSH key in your BitBucket Account page under SSH Keys (the URL will be something like https://bitbucket.org/account/user/YOURUSERAME/ssh-keys/)
- Each time you boot your machine, fire up Pageant and “Load” your private key from step 1 – this will then “authenticate” your push, pull, fetch and other remote requests against BitBucket.
SourceTree’s Coolest Feature on Windows – the Terminal
However, if you’re like me, you’ll quickly tire of having to always use the SourceTree UI – it can be really slow and clunky (thanks Java). In this case, you’ll want to use the “Terminal” option in SourceTree.
When you click on the “Terminal” option, you get a fairly fully featured Linux-like terminal right there on your machine. This terminal makes it easy for you to do things like pulls, pushed, checking out other branches, changing the permissions on a file to make it executable – everything you want to do at the Git command line, and a lot more.
The problem with this Terminal, though, is that it doesn’t get the benefits of Pageant’s private key access – if you try and do a push or a pull or anything else that requires authentication to BitBucket, you’re going to get an access denied situation.
Enabling SSH Key access from the Terminal
As mentioned, the Terminal is more than just a command line interface for Git – it has a lot of built in Linux functionality there (I haven’t explored/dug in to work out how much). However, because it is running as an emulated environment within Windows, but not really as part of it, you need to set up your own keys.
The process is as follows:
- Fire up the terminal by clicking on the “Terminal” button in SourceTree. It doesn’t matter which repository you launch the terminal from since we’re going to be affecting your whole terminal environment.
- Type in ssh-keygen -t rsa -C ‘email@example.com’ (obviously replacing the email address with your own account).
- Accept the defaults, and enter a passphrase if you want to be prompted to enter one each time you use the key.
- You’ll then need to copy the public key (located at C:\Users\YOURUSERNAME\.ssh\id_rsa.pub – right click and open it in Notepad) to your clipboard.
- Finally, you’ll need to paste the public key into your BitBucket Account page under SSH Keys (the URL will be something like https://bitbucket.org/account/user/YOURUSERAME/ssh-keys/).
Once you’ve done this, you’ll be able to run “git pull” and “git push” in your Terminal and interact with the BitBucket server.