Many Shippable customers create branches on their source control repository in order to work on new features.
Let's take an example of two developers, Ted and Mary, who're going to work on Feature #42 for the FooApp application. Their feature branch workflow will look something like this:
- Ted creates a feature branch off the
masterbranch. He calls the new branch
- Ted and Mary commit code changes to
- When coding for Feature #42 is complete, Mary sends a pull request to merge
- A dev lead reviews the pull request.and if everything looks good, merges the code into
- If the merged code passes all checks,
Fig 1: Gitflow workflow
The Atlassian team has written a more detailed description of the feature branch and Gitflow workflow which explains how to handle it from a source control provider perspective:
Let us look into how you can configure your Continuous Integration (CI) platform to handle these scenarios. In this example, we'll use Shippable's native CI functionality.
Step 1: Enabling a project
To get started with Shippable CI, you need to do three things:
- Sign in with your GitHub or Bitbucket credentials
- Create theCI config file shippable.yml and commit to the root of your repository
- Enable your repository so that we can set up webhooks on your behalf
Step 2: Creating build artifacts with a unique id
Your CI workflow will likely create build artifacts. These are application packages that can be pushed to a versioned storage and deployed into a test environment. Examples of build artifacts are JAR/WAR files or Docker images.
Since you plan to work off feature branches, you will need a way to identify which branch each build artifact was created from. To do this, you can use standard environment variables that are available for use in CI config for every build on Shippable.
In this scenario, two environment variables are useful:
- $BRANCH is the branch from where the build was triggered
- $BUILD_NUMBER is the build number on Shippable.
The combination of $BRANCH and $BUILD_NUMBER is always unique on Shippable. This means you can use these variables to uniquely name your build artifact, such as:
- Tag a Docker image: FooAppImage:$BRANCH.$BUILD_NUMBER
- Name a JAR file: myapp_$BRANCH_$BUILD_NUMBER.jar
Step 3: Creating a branch
When you start working on a feature, create a branch for that feature. As an example, here is how you create a branch on GitHub/Bitbucket:
Since your CI config is stored in your repository, your new branch will automatically have the config. When you push code changes to your branches, CI will trigger automatically. Environment variables will also be set automatically, so you'll be able to identify which artifacts came from your new feature branch.
Step 3: Customizing CI for branches
In some scenarios, you might want to run a subset of tests for feature branches but the entire test suite for the master branch. You can use the $BRANCH environment variable to set up this customization. For example:
- if [ "$BRANCH" == "feature/"* ]; then ./run-feature-branch-tests.sh; else ./run-full-test-suite.sh; fi
Step 4: Including/excluding branches
By default, Shippable triggers your CI for changes to all branches of enabled repositories. You can control which branches trigger CI by including or excluding specific branches, or branches matching a specific regex. For example, if you only want to trigger CI for master and feature branches, you would include the following in your yml:
branches: only: - master - feature*
On the other hand, to exclude CI for specific branch(es), you can configure the following:
branches: exclude: - develop
As shown above, the config can include branch names or regular expessions. More on branch confg here: Specifying branches to build
The complete CI configuration is available here: shippable.yml structure
You can also check out the config for our sample application which uses the
$BRANCH.$BUILD_NUMBER tag for a Docker image generated during CI. The images generated are pushed to Docker Hub with the right tag. You can also fork the sample app and follow instructions to set it up yourself and play around with the config.