How to set up CI for a Node.js project

October 29, 2020

Building high-quality software efficiently is hard. Software testing with continuous integration (CI) tooling makes it much easier. CI software runs your tests automatically each time you commit code to your repository. Whether it’s in a feature branch or a pull request, your CI software will make sure that your code passes your tests.

Continuous deployment (CD) takes CI one step further by automatically deploying your code if it passes your tests and meets certain other requirements. By using CI and CD software, you can make your software more reliable and ship it to your customers faster.

Snake CI is a powerful self-hosted CI/CD solution for Bitbucket. Although it works with any programming language or runtime environment, we’ll focus on Node.js for the purposes of this tutorial. By the time you’ve finished reading, you’ll be ready to supercharge your development process with state-of-the-art tools.

Prerequisites

To follow this tutorial, you’ll need a few things already set up:

  • A functioning Bitbucket instance.
  • An additional server (or a few) with Docker installed.
  • An existing Bitbucket repository with your code.
  • Your repository cloned onto your development machine.

What Will the Development Flow Look Like Once We’re Done?

To get a better idea of how continuous integration fits into your software development lifecycle, let’s take a look at what the process will look like after setting up Snake CI. For this example, we’ll pretend that your team wants to deploy a simple bugfix:

  1. A developer on your team implements a fix on their local computer. They test it manually to make sure that it addresses the issue.
  2. They commit the fix with Git and push it to Bitbucket.
  3. As soon as the commit is pushed, Snake CI gets going. Git prints out a link in the terminal where the developer can watch the status of their commit as it gets tested.
  4. Snake CI builds the software at that commit in a Docker container and runs all of your tests against it. Any errors are visible in the Bitbucket interface.
  5. If all of the tests pass and there’s a stage set up to deploy the software, Snake CI will deploy it.

Compared to developing without CI, this process lets teams quickly deploy their software with confidence, knowing that their software has been tested and is known to work.

Now that we’ve seen how Snake CI will improve your software development process, let’s start setting it up.

1. Install the Bitbucket Add-on

screenshot

From the Bitbucket admin panel, click Find new apps.

screenshot

Type Snake CI into the search bar.

screenshot

Accept the terms and install the add-on.

screenshot

2. Install Snake Runner

Now that you’ve installed the add-on for Bitbucket, you’ll need to configure another server to actually run the build and test processes for your application.

screenshot

From the Bitbucket admin panel, click Runners in the newly created Snake CI/CD section.

screenshot

Copy the command and run it on a server with Docker installed. We recommend that this server isn’t the same one you use to host Bitbucket.

screenshot

If everything worked, you should see a new runner on the Runners page.

3. Design a CI Pipeline

Your next job is to create a YAML configuration file that describes your pipeline, or the full lifecycle of your project. If you want to learn more about concepts and terminology in Snake CI, take a look at the documentation on this subject.

A pipeline is simply defined in a file called snake-ci.yamlin the root of your repository. Within a pipeline are stages, which are groups of jobs. Jobs are the simplest concept in Snake CI: they’re just a list of commands, run in an isolated Docker container.

Although your pipeline will certainly differ, here’s a simple example utilizing NPM, the Mocha testing framework, and the NYC coverage tool:

image: node:13

stages:
  - deps
  - test
  - coverage

install dependencies:
  stage: deps
  commands:
    - npm install

unit tests:
  stage: test
  commands:
    - node_modules/.bin/nyc --reporter=text node_modules/.bin/mocha

coverage:
  stage: coverage
  commands:
    # fails if the total coverage is below 90%
    - node_modules/.bin/nyc --check-coverage --lines 90

Let’s go through each part of this file one step at a time:

  1. The very first line tells Snake CI to use the official Node Docker image, version 13.
  2. After that, we define the stages in this project: deps, test, and coverage.
  3. Then, we define a job called “install dependencies”, which is part of the deps stage.
  4. In the next chunk, we define a job called “unit tests” as part of the test stage. This stage runs Mocha using NYC. Any unit test failures will cause this job to fail, causing the stage to fail, causing the pipeline to fail. If this happens, a clear visual marker will appear in the Bitbucket interface, showing that the commit failed CI.
  5. Finally, we define the “coverage” job in the coverage stage, which runs NYC to check code coverage. If NYC returns a non-zero error code (i.e. code coverage is below 90%), the same cascading failure will occur, resulting in the commit failing CI.

4. Commit the Pipeline File and Test the Configuration

Once you commit the Snake CI configuration file and push it to the Bitbucket repository, the add-on will automatically start running your pipeline on new commits. To make sure that your pipeline works as intended, try making a small change. Test it both locally and with Snake CI in a separate branch of your repository. If everything works the same in both environments, odds are that you set it up correctly.

5. Start Working

Congratulations! You just finished setting up Snake CI for your Node.js project. As you continue working on your project, you may want to add additional features to your pipeline file. The documentation is full of specific details that should help you set up complex configurations.

If you run into any issues or need help, chat with us on Slack.

Start building faster. Today.

Free 30-days trial.