Shipkit — getting started

ShipKit is a new Continuous Delivery tool that allows you to ship every change to production without hassle. Automated versioning, generating release notes and publishing are, among others, its most important features. In this tutorial I would like to show you how you can start using ShipKit in your project in 15 minutes.

Starting with Shipkit

To configure Shipkit you need add a dependency on “gradle.plugin.org.shipkit:shipkit:${version}” which currently can be downloaded from “https://plugins.gradle.org/m2/”, so you need to add this Maven repository to your gradle configuration if you don’t already have it. After that you need to apply “org.shipkit.java” plugin, only in your root project.

buildscript {
    repositories {
        maven { url "https://plugins.gradle.org/m2/" }
    }

    dependencies {
        classpath "gradle.plugin.org.shipkit:shipkit:0.8.80"
    }
}

apply plugin: "org.shipkit.java"

When you are done you can open the terminal and in your project’s root directory run the following command:

./gradlew initShipkit

This will generate three configuration files:

• version.properties — it has the information about version of your project. From now on you should have version specified only here, instead of in any of the Gradle configuration files. The default is based on your current version of the project, taken from Gradle project.version or “0.0.1” if unspecified. You can override it yourself by changing ‘version’ property manually.
• shipkit.gradle — it’s a place for all configuration properties (GitHub repo, Bintray etc). It is filled with examplary values and a few may not need to be changed but most of them you need to change by yourself.
• .travis.yml — this file is needed by Travis and it specifies what kind of build logic will be executed there.

At the beginning of shipkit.gradle you can find shipkit extension:

shipkit {
   gitHub.repository = "wwilk/shipkit-demo"
   gitHub.readOnlyAuthToken = "e7fe8fcfd6ffedac384c8c4c71b2a48e646"
   gitHub.writeAuthUser = "shipkit"
}

Property github.repository is by default filled with your remote origin URL so usually you can start with only changing github.readOnlyAuthToken. You need to generate this token on GitHub. As the name of the property suggests you should not give attach any scopes with write access to this API key. You will of course also need another API key, so that Shipkit can push updated resources (version, release notes) to your GitHub repo. The best way to provide Shipkit with it is to set environment variable GH_WRITE_TOKEN.

There is a lot of other properties that you can change in shipkit extension. You can find them here.

Bintray configuration

Bintray configuration of the generated shipkit.gradle looks like this:

allprojects {
   plugins.withId("org.shipkit.bintray") {
       bintray {
           key = '7ea297848ca948adb7d3ee92a83292112d7ae989'
           pkg {
               repo = 'bootstrap'
               user = 'shipkit-bootstrap-bot'
               userOrg = 'shipkit-bootstrap'
               name = 'maven'
               licenses = ['MIT']
               labels = ['continuous delivery', 'release automation', 'shipkit']
           }
       }
   }
}

To only play around with Shipkit you don’t need to change any Bintray configuration! Shipkit maintains shipkit-bootstrap Bintray organisation for you to try on Shipkit publishing without even creating a Bintray account!

Of course after testing you need to change default values to appropriate for your project. For this you have to create a Bintray account, add organisation and at least one repository. Shipkit uses Gradle Bintray Plugin underneath and the same Bintray extension, so you can check its documentation to get more details and other properties you can configure.

Additionally you have to set bintray.key property, or, a more recommended solution, set BINTRAY_API_KEY environment variable. We will later in this tutorial get to setting it on Travis. This property you fill with your generated Bintray API key.

Travis configuration

You can sign in to Travis with your GitHub account, and then you need to enable your project to be built on Travis.

Here is how generated (by running initShipkit task) .travis.yml file looks like:

# More details on how to configure the Travis build
# https://docs.travis-ci.com/user/customizing-the-build/

# Speed up build with travis caches
cache:
  directories:
    - $HOME/.gradle/caches/
    - $HOME/.gradle/wrapper/

language: java

jdk:
  - oraclejdk8

#don't build tags
branches:
  except:
  - /^v\d/

#build and test the release logic
script:
  - ./gradlew build -s -i

#check release criteria and make release if criteria are met!
after_success:
  - ./gradlew assertReleaseNeeded && ./gradlew ciReleasePrepare && ./gradlew performRelease -Pshipkit.dryRun=false

Interesting part for us is what happens in after_success.

A few Shipkit Gradle tasks are run there:

• assertReleaseNeeded which checks if release should be made during this build. There is a number of ways how you can skip release — eg. by using [ci skip-release] in your commit message or set SKIP_RELEASE environment variable. You can find more ways here.
• ciReleasePrepare that sets up Git configuration on Travis, eg. sets git.user and git.email properties
• performRelease which, among others, bumps PATCH part of the semantic version in your version.properties, updates release notes and publishes artifacts to Bintray
• shipkit.dryRun needs to be set to false, because for running in development it’s set to true by default (which means that performRelease task doesn’t push to GitHub or publish to Bintray)

One more thing to do is setting environment variables on Travis. It is recommended to set BINTRAY_API_KEY and GH_WRITE_TOKEN there.

This is it! Shipkit is now configured in your project. You can try it by pushing anything to master, which should start the Travis build.