Setting up CI/CD With GitHub Actions, Now-SDK and Update Sets

[Jon G Lind]

This covers how to create a pipeline using GitHub Actions and deploying with Update Sets. For deploying using Application Repository (App Repo), check out Setting Up CI/CD with Github Actions, Now-SDK and App Repo.

Not everyone can use App Repo for deployments so this shows how to use update sets instead.

ServiceNow SDK now offers great tools for implementing a Continuous Integration and Deployment (CI/CD) pipeline using App Repo, but not everyone can use it. This tutorial will show you how to use Update Sets to deploy, leveraging ServiceNow SDK (Now SDK) to authenticate to an instance and build and deploy a Fluent app from your CI/CD system. This example will use GitHub Actions to commit it on TEST as an update set, and move it to PROD after a reviewer approves. This walkthrough uses a small sample app, so you can see the whole flow before implementing it in your own project.

Caution: the pipeline writes to your instances without a human in the loop. Use sub-production instances to validate and keep credentials out of version control.

Step 0: Prerequisites

1. Two instances: one for TEST and one for PROD. PROD needs an Update Source record that points at TEST, because the move command retrieves update sets through the Update Sources feature. See Setting a source for an update set for setup.
2. A GitHub account. Private repositories need a paid plan to use required reviewers.
3. The GitHub CLI (gh) installed and signed in with gh auth login (this allows you to automate setting the variables and secrets, but you may also do it manually).
4. Node.js 22 or greater.

Step 1: Fork the repository

1. Open github.com/jon-lind-sn/update-set-cicd and select Fork.
2. Clone your fork locally:

   git clone https://github.com/<your-user>/update-set-cicd.git
   cd update-set-cicd

3. Open the Actions tab of your fork on GitHub and enable workflows. (GitHub disables them on a new fork.)

Step 2: Set up the credentials

Repeat the following credential setup steps on TEST and PROD. OAuth client credentials allow authentication without saving a password to your CI/CD system.

Follow Set Up OAuth Client Credentials for the ServiceNow SDK on each instance. For each environment save the Client ID and Client Secret (keep this one safe!)

Step 3: Store the credentials in GitHub

Go to the local folder for your project and run this script to setup the credentials with the GitHub CLI (gh).

scripts/setup-cicd.sh --repo <your-user>/update-set-cicd

The script prompts for the instance, auth type, and credentials for TEST and then PROD, and saves them as GitHub variables and secrets.

Optional: Set them manually

Without the GitHub CLI, go to Settings > Secrets and variables > Actions in your fork on GitHub and create the entries below. Set the TEST and PROD rows for the auth type you chose on each instance. I.e. you will set different properties for basic vs. OAuth.

Variables Tab

Name	Used when	Value
SN_SDK_TEST_INSTANCE_URL	Always	TEST instance URL
SN_SDK_PROD_INSTANCE_URL	Always	PROD instance URL
SN_SDK_TEST_AUTH_TYPE	Always	oauth or basic
SN_SDK_PROD_AUTH_TYPE	Always	oauth or basic
SN_SDK_TEST_USER	TEST uses basic	TEST user name
SN_SDK_PROD_USER	PROD uses basic	PROD user name

Secrets Tab

Name	Used when	Value
SN_SDK_TEST_OAUTH_CLIENT_ID	TEST uses oauth	Client ID from TEST
SN_SDK_TEST_OAUTH_CLIENT_SECRET	TEST uses oauth	Client Secret from TEST
SN_SDK_PROD_OAUTH_CLIENT_ID	PROD uses oauth	Client ID from PROD
SN_SDK_PROD_OAUTH_CLIENT_SECRET	PROD uses oauth	Client Secret from PROD
SN_SDK_TEST_USER_PWD	TEST uses basic	TEST user password
SN_SDK_PROD_USER_PWD	PROD uses basic	PROD user password

Step 4: Create the approval gate

1. In your fork go to Settings > Environments > New environment.
2. Name it exactly production (the workflow uses this exact name).
3. Select Required reviewers and add yourself.

Step 5 (optional): Require the checks before merge

1. Go to Settings > Rules > Rulesets > New branch ruleset and target main.
2. Select Require status checks to pass and add build / build and unit-tests.
3. Select Require branches to be up to date before merging.

Step 6: Run a change through the pipeline

1. Create a branch:

   git checkout -b my-first-change

2. In update-set-cicd-sample/src/server/fix-scripts/hello-update-set-cicd.js, change the message.
3. In update-set-cicd-sample/package.json, raise version (for example 0.0.4 to 0.0.5). Every new version produces a new update set.
4. Commit and push:
   

   git add update-set-cicd-sample
   git commit -m "Update the hello message and bump the version"
   git push -u origin my-first-change

5. Return to GitHub and create Pull Request (PR) for this checkin.
6. The Sample app: PR build and generate check builds the app and generates the update set. 
7. Merge the PR. Sample app: deploy TEST then PROD imports the update set to TEST.
8. The run pauses at deploy-prod. Inside of your GitHub repo open Actions, select the latest running workflow (e.g. Merge pull request 14).
9. In the banner there will be a prompt for you to review deployments. Open that, select "production" and Approve and Deploy.
10. In your Prod instance open System Definition > Fix Scripts and find Hello Update Set CICD and verify that the script holds your new message.

If the preview finds a problem, the run stops and nothing is committed. The log lists each conflict. You may either manually fix and commit or merge a new version.

Use the CLI from your terminal

The same commands run from a terminal. Store a Now-SDK auth alias for the instance, build the sample app, generate the update set, and import it:

Bash

cd update-set-cicd-sample
npm ci
npx now-sdk auth --add https://{test-instance}.service-now.com --type basic --alias test
npx now-sdk build
npx github:jon-lind-sn/update-set-cicd generate dist/app --out-dir out
npx github:jon-lind-sn/update-set-cicd import out/*.xml --to test --commit

Windows

cd update-set-cicd-sample
npm ci
npx now-sdk auth --add https://{test-instance}.service-now.com --type basic --alias test
npx now-sdk build
npx github:jon-lind-sn/update-set-cicd generate dist/app --out-dir out
npx github:jon-lind-sn/update-set-cicd import (Get-ChildItem out/*.xml) --to test --commit

This uploads the update set, previews it, and commits it. Remove --commit to preview only.

Going deeper

1. How the pipeline works and the flow diagram.
2. Workflow files. Call _move-update-sets.yml from your own repository to promote existing update sets.
3. CI/CD with GitHub Actions and the Now SDK, create a CI/CD pipeline deploying Fluent apps through the Application Repository.
4. ServiceNow SDK documentation, including CI integration.
5. GitHub: Actions and environments and approvals.