Configuring a build badge for a Node.js project status

- By Abhijit Kini on May 23, 2016


I have gone through the steps of running  basic Continuous Integration (CI) on a Node.js app hosted on a private repository. Now I'll configure a visual indicator to display the status of the Node.js app when CI is run, using build badges. As shown below, I use it to update my team mates about the latest build status of my project in a convenient way.

Build badge for a nodejs application

First, what is a Badge and where is it used?

Badges, in the context of continuous integration, are used to display the meta-data of a build. For example, at the completion of a build, a status is displayed on whether a build succeeded or failed. This build status is incorporated into a build badge and can be displayed to viewers in different ways and in different locations. Badges are used to display different meta-data such as build status, code coverage percentage, status of third party dependencies, release versions, etc.

In this tutorial, I'll configure the Node.js app on Shippable to embed build status in two ways and show few examples of the outcome.

Before you begin:

Ensure you have -

  • Have signed into Shippable using your GitHub or BitBucket credentials
  • Completed the previous tutorial of running continuous integration for a Node.js app
  • Have an enabled project on Shippable platform, to run continuous integration

I'll continue to use my enabled project - Node.js app (available for download on GitHub) for this tutorial.

Configure Project settings

You can configure the build badges for any branch of your project on Shippable. Once you select the branch that you want to display the build status, there are two ways you can get embedded build status for that branch of the project on Shippable.

  1. Image URL
  2. Markdown

I will configure both for the 'Master' branch of the 'nodejs' project. Here are the steps:

  • From your home page, select your 'Subscription'.
    • 'Shippable-Demo' in this case.
  • In your subscription select your enabled project that you want to configure build badges.
    • 'nodejs' in this example.
  • Click the 'Settings' tab of your project.
  • Scroll down to the 'Status Badge' section.
  • Select 'master' from the Branch section drop down.
    • Since this project has Master branch only, you'll see only 'Master'. For projects with multiple branches, all branches are displayed.
  • Select 'Image URL' from thedropdown.
    • Copy the URL ( https://api.shippable.com/projects/573654952a8192902e200e8a/badge?branch=master) and embed it in a desired location. For this example, I'll use a browser.
  • Select 'Markdown' from thedropdown.
    • Copy the code ([![Run Status](https://api.shippable.com/projects/573654952a8192902e200e8a/badge?branch=master)](https://app.shippable.com/projects/573654952a8192902e200e8a))and embed it in a desired location. For this example, I'll put it in the README file of the Node.js app.
      Markdown code for a build badge

Use the picture below as a reference to the Project settings configuration:

  Configuring a build badge for a nodejs continuous integration project

 

View Badge status

I have configured the 'Status Badge' settings and now let us view the output.

  1. Image URL: For this tutorial, I put the URL into a browser and the output is shown below. You can get creative & embed this URL in any of your applications.

    Continuous Integration Build badge status in a URL

  2. Markdown: Since I embedded this in my local README file, I'll push this change to my 'nodejs' GitHub repository. To do that, from my local 'nodejs' directory in my Terminal, I run these commands:
    • git add .
    • git commit -m "update readme with build status badge"
    • git push origin master
      The above commands updates the README file on my GitHub 'nodejs' repository as shown below and also triggers a build on Shippable. The updated README is shown below:

      Continuous Integration Build badge status using markdown

Build Status Badge options

Shippable provides you with the ability to add build status badges and supports the following status:

Build Status Status Badge Image
Waiting, Processing

Build badge status for a pending continuous integration build

Timeout, Failed

Build badge status for a failed continuous integration build

Unstable

Build badge status for a unstable continuous integration build

Cancelled

Build badge status for a cancelled continuous integration build

Successful

Build badge status for a successful continuous integration build

 

I have successfully configured our project to show the build status badge. Based on the build status, the badge displays one of the images above.

What if we want to take it a step further & customize the badges? For example, I would like to add my own custom words & change the colors. Here's a tutorial on this.

In the next tutorial, I'll configure test results to visualize passed & failed tests


Try Shippable

Topics: continuous integration (CI), nodejs, Notifications, tutorial, tips