Using Onboardbase in Github CI/CD Workflow

Continuous integration/Continuous Deployment is a Software Engineering practice that aids in team collaboration and enhances software development.

In this tutorial, we will show how you can integrate Onboardbase in your CI/CD Pipeline on GitHub. This knowledge can be applied even if your CI/CD Pipeline is not on Github

Onboardbase Service Tokens: The Secret Sauce of Onboardbase Integration

As we showed in a previous tutorial on Using Onboardbase in Docker, Onboardbase Service Token allows us to authenticate the Onboardbase CLI without running onboardbase login.

Running onboardbase login will require manual intervention to complete the process of authenticating via a web browser. But by using the Service Token, you can authenticate the Onboardbase CLI automatically.

To make this tutorial short, we will only integrate Onboardbase for Continuous Integration. The process we will show here will work for continuous deployment regardless of the Deployment environment.

Setting Up The Sample Project

If you wish to follow along, you must fork the repository here. Then you clone your fork on your local machine.

It's a very simple NodeJs Express server that requires two environment variables, PORT AND DB_URL

const express = require("express");
const app = express();

app.get("/", (req, res) => {
  res.send("Hello world");
});

const port = process.env.PORT;
if (!port) {
  throw Error("You must set a Port for the App to Run");
}

const server = app.listen(port, () => {
  console.log(`Example app listening on port ${port}`);
});

server.close();
module.exports = { app, server };

const request = require("supertest");
const { app, server } = require("./app");

afterAll(() => {
  server.close();
});

describe("GET /", () => {
  it("respond with Hello world", (done) => {
    request(app).get("/").expect("Hello world", done);
  });
});

The app.test.js is a minimal Integration test. Typically, in a CI/CD flow, you must ensure that your automated tests pass before new code is integrated or deployment occurs.

We also have a fundamental GitHub workflow in the .github/workflows folder:

# This is a basic workflow to help you get started with Actions

name: CI

# Controls when the workflow will run
on:
  # Triggers the workflow on push or pull request events but only for the "main" branch
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
  # This workflow contains a single job called "build"
  build:
    # The type of runner that the job will run on
    runs-on: ubuntu-latest

    # Steps represent a sequence of tasks that will be executed as part of the job
    steps:
      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
      - uses: actions/checkout@v3

      # Runs a single command using the runners shell
      - name: Run a one-line script
        run: echo Hello, world!

      # Runs a set of commands using the runners shell
      - name: Run a multi-line script
        run: |
          echo Add other actions to build,
          echo test, and deploy your project.

The workflow has triggered events such as Pushes or Pull Requests to the main branch. We are going to a new Action to install NodeJS and run tests.

Replace the steps section with the following:

...    
	steps:
      - name: Checkout Code
        uses: actions/checkout@v3

      - uses: actions/setup-node@v3
        with:
         node-version: '16.x'
      - run: npm install
      - run: npm test
 ...

Now we are installing NodeJs, Running npm install and then running npm test in the workflow. Checkout to a new branch, commit and push the changes to it. Then go on Github to make a Pull Request to the main branch to trigger the workflow on GitHub.

Click on Details in the display showing the CI/Build on the PR information page to see the status of the workflow

The workflow should fail because the tests could not be executed as the environment variables are unavailable.

Setting up Onboardbase in the GitHub Workflow

To add Onboardbase to the GitHub Workflow, you must have a Project setup on Onboardbase Already, with an environment and the environment variables needed. If you don't have that, you can follow the instructions here to create a new Onboardbase Project.

I'm making use of the same Onboardbase Project we created in the tutorial on Setting Up Onboardbase in a NodeJs Server; I have only added a new DB_URL variable to the development environment:

Generating A Service Token

To create a Service Token, click on your avatar at the top-right section of your dashboard (far end of the navigation bar) and select "Manage your Organization."

On the next page, scroll to the Service Token section and click on Create a Token

Proceed to fill in the details for the Service Token you want to create. Make sure to select the right Project and Environment for the Service Token:

After generating a Service Token, you can click on the token name to copy it.

Adding Onboardbase Service Token to Github Secrets

We need to add the service token to Github Secrets for the Repository. Click on the Settings tab on the GitHub Repository. On the Settings Page, click on Actions under Secrets and variables on the left navigation panel:

On the secrets page, click on New repository secret to add a new Secret

Add a new Secret named ONBOARDBASE_TOKEN, the value of the Secret will be the Service Token from Onboardbase. Click on Add secret to add the new secret.

Using The Service Token in Github Workflow

After adding ONBOARDBASE_TOKEN to Github Secrets, the next steps is to use the token inside of the GitHub workflow, update the deploy.yml file in the github/workflows folder:

 steps:
      - name: Checkout Code
        uses: actions/checkout@v3

      - uses: actions/setup-node@v3
        with:
         node-version: '16.x'
      - run: yarn install

      - name: Install Onboardbase
        run: yarn global add @onboardbase/cli

      - name: Authenticate Onboardbase
        run: onboardbase config:set --token ${{secrets.ONBOARDBASE_TOKEN}}

      - name: Run tests
        run: onboardbase run "yarn test" -p simple-express-server -e development

We have included steps to Install the Onboardbase CLI. We are also authenticating Onboardbase by running onboardbase config:set --token ${{secrets.ONBOARDBASE_TOKEN}}. GitHub makes the ONBOARDBASE_TOKEN we set available in the secrets object.

The last step is to run the tests; we are running the test with onboardbase run so that Onboardbase can inject the environment variables. We also set the project (-p flag) and environment (-e flag) so that Onboardbase can know which project and environment to inject.

onboardbase run "yarn test" -p simple-express-server -e development

Commit the updates and push to trigger the workflow:

Yay . The Workflow completes successfully.

Conclusion

In this tutorial, we have shown how Onboardbase can be incorporated into Github workflows. We showed how Onboardbase Service Token enables automatic integration with Onboardbase.

You can apply the ideas from this tutorial to set up a complete CI/CD Pipeline on any platform of your choice.