Continuous Integration (CI) is a development practice that requires developers to integrate code into a shared repository several times a day. Each check-in is then verified by an automated build, allowing teams to detect problems early. By integrating regularly, you can detect errors quickly, and locate them more easily.
Shippable's CI platform supports different source control providers, languages, platform, notification providers, Docker registry services, container services and IaaS/PaaS providers for an end-to-end application delivery pipeline. In this tutorial, I'll go over basic CI for a simple Node.js app. The work flow includes sign up, enabling the repository that hosts the Node.js app, creating a yml.file that instructs Shippable on the details of running CI & completing a successful CI build.
Before you begin:
To follow along with the tutorial, make sure you have:
- Installed Node.js on your Mac/PC
- A GitHub or BitBucket account
For this tutorial, I use a simple Node.js app, available to download from GitHub. As shown below, you'll see six files in the root of the 'nodejs' GitHub public repository that hosts the Node.js app. NOTE: By clicking the above link, if you see additional files, they were added through subsequent tutorials.
Let's dive right in to perform basic CI using Shippable.
Step 1: Sign In
Go to the Shippable portal and sign in with your source control provider credentials (GitHub in this walk-through).
- Click on 'GitHub'.
Step 2: Authorize access to your repository
Shippable accesses your source control provider's (GitHub, in this case) identity using OAuth authentication. The advantage is that you do not need a separate Shippable account. You can use either GitHub or Bitbucket to log into Shippable.
- Click on 'Authorize application'.
By authorizing access, you are allowing Shippable to access your Public repositories only. The screen below shows the details of the access such as read/write access on specific components of your repository.
- Click on 'Authorize application'. Provide your GitHub password, if prompted.
NOTE: I'll cover authorizing access to private repositories in subsequent tutorials.
Step 3: Enable your project
Source control repos are called Projects within the Shippable platform. After you authorize your public repo, you'll see a landing page that gives you links to key tasks in Shippable. You'll continue to see this landing page until you enable your first repo.
To enable your first project:
- Click on 'Subscriptions' and select your account.
- Review the list of all public repos from your source control provider
- Click on 'Enable' button for the desired repo/project - 'nodejs' for this tutorial
NOTE: If you do not see the repository, type the name in the search box and click 'Sync'. This will sync permissions with your source control provider & resurface the repositories in that account.
Upon enabling the project, you'll see a 'Build' button. You can use this button to trigger a manual build. Before you do that, let's complete the next step.
Step 4: Create a
This is a critical step in this process: all build configuration happens through the
shippable.yml file. This file needs to be created in the root of your GitHub repository. Without this file no process takes place on the Shippable platform. For this walk-through, I'll configure the shippable.yml file, at the root of 'nodejs', with minimum information - language used, version of the language and the 'npm install' command to install dependencies. Use the shippable.yml reference guide to understand the full power and capabilities supported on the Shippable platform.
Step 5: Trigger a build
Once I enable a repository, Shippable establishes a web hook to that repository. With this web hook, Shippable actively listens for any commits or pull requests for that repository. When a commit or a pull request happens (independent of the user who created it), a build is automatically triggered on the Shippable platform.
Since I created the
shippable.yml file at the root of the local 'nodejs' directory, I'll push this code to GitHub, as shown below and trigger the build on Shippable automatically.
In my Terminal, I run the following commands from my local 'nodejs' directory, with the output shown below:
git add .
git commit -m "added shippable.yml"
git push origin master
Switch back to the Shippable portal and see the build has been automatically triggered.
Upon triggering the build, many things happen on the Shippable platform. Given below is an overview, based on the simple
shippable.ymlfile, I've used.
- A minion (Docker based container) is provisioned. Shippable determines the Docker image to use for spinning up your build minion. This is done based on what is configured in the
shippable.ymlfile. In this case, since we specified the language & version as
0.12a default build image with Node.js v0.12 is used.
- All commands in the
cisection are executed. In our
shippable.yml, we have the
buildsection that includes:
- Installation of Node Package Manager (npm)
- You will see all steps in the console & at the end of this sequence, the build status is updated. You will see a green build, when successful.
- The build minions are transient and upon completion of the build sequence, they are destroyed.
- For information on additional sections of the
shippable.ymlfile and details of how builds are executed, refer to our documentation.
Step 6: Complete a successful CI run
The build status upon successful completion shows a green build. I've now successfully run a basic continuous integration on the Node.js app.
Next, I'll configure a simple npm unit test to check for errors on the Node.js application.
In the mean time, if you have questions or feedback, reach out by adding a comment below or opening a new Support Issue and we will get you to green CI build.