Jenkins setup for Rails and Bitbucket

Initial Jenkins setup

If you haven’t installed Jenkins yet, hop over to the Jenkins Wiki page on installing Jenkins. On Ubuntu, the easiest way to install Jenkins is simply sudo apt-get install jenkins , but if you want the latest version you have to add the Jenkins apt repository.

1. Once you have a fresh copy of Jenkins running open up http://yourserver:8080 in your browser and click Manage Jenkins. At the top of the page you will see a warning about your Jenkins installation being unsecured. Click on “Configure Global Security” to set up permissions the way you want. See the Jenkins Wiki for help on the most common setup.
2. After setting up security, click on “Manage Plugins” from the “Manage Jenkins” page and install the “Git Plugin”.
3. Because the jenkins will be pulling code from your git repositories, it will need to have it’s own ssh key and git details:
4. Because the jenkins will be pulling code from your git repositories, it will need to have it’s own ssh key and git details:
5. Now you can go to “Credentials” -> “Global Credentials” and click “Add Credentials”. Select “SSH Username with private key” as the “Kind” and choose “From the Jenkins master ~/.ssh”.

Setup for a Rails project

1. Set up rbenv for the jenkins user. See rbenv’s GitHub readme for details.
2. Create a new Jenkins job: Click “New Job” on the front page, pick a name for your job and choose “Build a free-style software project”.
3. Under “Source Code Managment” choose Git and fill in your repository URL. As the credentials choose jenkin’s ssh key. If your repository is private, you will get an error “Failed to connect to repository” beacuse the jenkins user doesn’t have permission to access your repository yet. Don’t worry about this for now, we will set up jenkin’s key with Bitbucket later. You can also specify which branch you would like to build, so you can set up different jobs for your development and production branches for example.
4. Under “Build Triggers” check “Trigger builds remotely (e.g., from scripts)” and set an authentication token, any moderately long random string will do. Here’s a quick oneliner to grab 30 random characters: tr -dc 'a-zA-Z0-9' </dev/urandom | head -c 30. If you don’t see the “Trigger builds remotely” option it probably means you have not configured security in Jenkins. Go back to the previous section and get that done first ;)
5. Under “Build Environment” check “SSH Agent” and select jenkin’s ssh key.
6. Under “Build” click “Add build step” and select “Execute shell”. Here you need a script which will run tests for our Rails project. Here is mine:
7. This script assumes you are using PostgreSQL for your Rails app and have it set up on your Jenkins machine. Note the use of the JOB_NAME variable in the database name. This way you can safely share this build script between different Jenkins jobs and not worry about parallel jobs stepping on each other because every job will be using a different database. It also assumes you are using Capybara in your tests which requires a running X server. To fix this problem we prefix our rake command with xvfb-run -a. Xvfb runs a virtual X framebuffer in memory (without output to the screen). For this to work you will need to install xvfb (apt-get install xvfb on Ubuntu). If you aren’t using Capybara in your tests you can remove the xvfb-run -a prefix.
8. Add email notifications for yourself and your teammates.
9. For setting up integration with Bitbucket you will need an API token. On the Jenkins front page click on “People”, choose your account and click “Configure”. Under “API Token” click on “Show API Token” and copy it.

Integration with Bitbucket

We want our Jenkins job to be fired off on every push to our Bitbucket repository. To set this up visit your repository’s page and click on the Administration (gear) button on the top right (you will need administrative privileges).

1. First of all you need to grant Jenkins read-only access to the repository. Click on “Deployment keys” and add the ssh key you created for the jenkins user.
2. Next, click on “Hooks”, select Jenkins and click “Add hook”. In the window that pops up you need to fill in: Endpoint: For this you will need a public URL of your Jenkins server, the username of your Jenkins account and your API token. Here is the url format: http://username:api_token@yourserver.com/ Project name: The name of your Jenkins job. Token: The token you generated for your job’s build trigger.

That’s it! You can try pushing a commit to your repository to check if everything is working.

Optional goodies: ci_reporter and Doony

With the above setup when a job fails you can see the details by looking at the console output. If you would like a graphical view of your test results you will need to install the ci_reporter gem in your Rails project. See the ci_reporter GitHub readme for details on gem installation and configuring your Jenkins job. You will also need to edit your build script. Change the rake command at the end to: xvfb-run -a rake ci:setup:minitest minitest:all:quick (or omit xvfb-run -a if you are not using Capybara).

Speaking of eyecandy, if you’re not a fan of Jenkin’s default look and feel, check out Doony which makes your Jenkins interface look nice and slick while also offering some usability improvements.

Credits

I’d like to give credit to Felix Leon’s blog post “Hooking Bitbucket up with Jenkins”. It was my main source of information about integrating Jenkins with Bitbucket and some of the instructions in my post were adapted from it.

photo from unsplash.com