Configure CI/CD with Github Actions and Now-SDK using OAuth or Basic Auth

[Jon G Lind]

Setting up CI/CD With ServiceNow SDK and GitHub Actions

This is the full, start-to-finish walkthrough for wiring up a Github repo's pipeline against your own ServiceNow instances to implement a Continuous Integration/Continuous Deployment pipeline using the new Now-SDK CICD features.  

⚠️ Caution: Setting up this pipeline means creating automations with CI/CD credentials, service users and OAuth applications. These can write directly to your ServiceNow instances without a human in the loop so configure and use these carefully--keep secrets out of version control and understand exactly what each workflow will do to your instance before you run it. Always start by testing in sub-prod instances.

Step 0: Getting started

Install Github command line utility (GH)

Install the Github command line utility from https://github.com/cli/

Get the code

You will need the github action configs, and you may want the setup scripts in the repo to help with configuring your repo.  Forking is the easiest way to get started and immediately configure it on your instances.  

github.com/jon-lind-sn/dev-passport-brazil 

Fork Me

Forking is the easiest way to get a copy of this into your own repo, install it into you instance and begin experimenting with the pipelines.

Login to your Github account and open the repo and use "Fork" on the repo's main page then proceed from there.

Clone Me

If you already have a project you may also clone this project locally and then copy the .github and scripts folders to your project and update the package.json to match the dependencies.

git clone https://github.com/jon-lind-sn/dev-passport-brazil.git

What this pipeline does

The pipeline is built entirely on the ServiceNow SDK's Continuous Integration/Continuous Delivery (CI/CD) commands (now-sdk install and now-sdk cicd ...).  GitHub Actions is the runner that calls them in order, but a similar automation could be implemented elsewhere.

The pipeline has two workflows.  The first one, implemented in pr-validation.yml, executes whenever a new Pull Request (PR) is created in Github and will compile and install the application to the test instance and execute the specified ATF test suites.  The second, implemented in deploy-main.yml, starts a process to publish the version to App Repo and deploy to prod.  

 

Basic Auth vs OAuth

Both Basic and OAuth client-credentials auth are supported independently (e.g. you could configure Basic for test, OAuth for prod). See .github/workflows/README.md for more details.

OAuth is recommended and I am actively trying to discourage the use of basic auth whenever possible.  With the OAuth the client secret authenticates the CI system itself rather than using a person's login, so a leaked secret can be rotated without touching anyone's account password, and there's no live password sitting in a CI variable.

Step 1: ServiceNow-instance-side setup

Create a Service User (basic or OAuth)

Create a user with:

• Name: e.g. cicd.deployer
• Identity Type: Human (you may need to modify the form's view to add this field).
• Give it the admin role.

Basic auth

Seriously, OAuth setup isn't that hard. Please consider proceeding to the next step and configuring OAuth, or else you may move on to the next section "Github setup".  Otherwise you just need the username and password for the user created in the previous step.

OAuth client credentials

1. Enable the client_credentials grant on the instance

Set or create The system property glide.oauth.inbound.client.credential.grant_type.enabled of type true | false  and value of  true.  KB1645212

2. Create the OAuth Application Registry

Navigate to System OAuth → Application Registry → New Inbound Integration Experience → New Integration → OAuth Client Credentials Grant

• Name: SDK CI
• Provider Name: SDK CI Provider 
• OAuth application user: the service user created earlier
• Allow access only to APIs in selected scope: unchecked

Save, and Skip the "assign an auth scope" warning

Validate the credentials locally

Set the following environment variables from the command line before running the now-sdk query to validate that they are able to connect successfully. 

Set your instance name and get the Client ID and Client Secret from the previously created registry record before copy and pasting this into a terminal window.

Bash:

export SN_SDK_NODE_ENV=SN_SDK_CI_INSTALL
export SN_SDK_AUTH_TYPE=oauth
export SN_SDK_INSTANCE_URL=https://your-instance.service-now.com
export SN_SDK_OAUTH_CLIENT_ID=<client-id>
export SN_SDK_OAUTH_CLIENT_SECRET='<client-secret>'

npx @servicenow/sdk query sys_user -q "active=true" --limit 1 -o json

Windows:

set SN_SDK_NODE_ENV=SN_SDK_CI_INSTALL
set SN_SDK_AUTH_TYPE=oauth
set SN_SDK_INSTANCE_URL=https://your-instance.service-now.com
set SN_SDK_OAUTH_CLIENT_ID=<client-id>
set SN_SDK_OAUTH_CLIENT_SECRET=<client-secret>

npx @servicenow/sdk query sys_user -q "active=true" --limit 1 -o json

A working credential returns {"ok":true, ...} 

Step 2: GitHub-side setup

Initialize a git repo and push it to github.  Consider forking the example or adding the .github/workflow files to your own repo.  The configuration and credentials are all stored on github so it should drop-in.

Option A: Use the setup script from the cloned repo

NOTE: Copy the Client IDs and Secrets from the OAuth Registry records created earlier.

Bash:

./scripts/setup-cicd.sh

Windows:

 scripts\setup-cicd.bat

Option B: Manual

Login to the Github repo and navigate to Settings > Secrets and Variables > Actions and  use the Secrets and Variables tabs to set the following values.

Repo Variables

Auth type	Variable(s)
basic & oauth	SN_SDK_TEST_INSTANCE_URL, SN_SDK_PROD_INSTANCE_URL,  SN_SDK_TEST_AUTH_TYPE, SN_SDK_PROD_AUTH_TYPE
basic	SN_SDK_TEST_USER, SN_SDK_PROD_USER

Repo Secrets

NOTE: Copy the Client IDs and Secrets from the OAuth Registry records created earlier.

Auth type	Secret(s)
basic	SN_SDK_TEST_USER_PWD, SN_SDK_PROD_USER_PWD
oauth	SN_SDK_TEST_OAUTH_CLIENT_ID, SN_SDK_TEST_OAUTH_CLIENT_SECRET,  SN_SDK_PROD_OAUTH_CLIENT_ID, SN_SDK_PROD_OAUTH_CLIENT_SECRET

 

Step 3: Make a change and watch the pipeline run

Example of Action executing (see Actions tab in Github).

1. Branch off main, make your change.
2. Bump version in package.json 
3. Push your branch and open a PR.  Watch for the PR Validation flow to run against the test instance.
4. Open Actions tab in the repo to see current and previously run workflows.
5. If it fails, e.g. a failed ATF test, push another commit with the fix to the same branch and it will re-run the validation.
6. Once the check is green, merge to main and the Deploy to Prod pipeline executes and waits for the production approval gate. You will get an email and you can use the "Review deployments" button on the Action in Github.
   

Going deeper

Hopefully you enjoyed this tutorial.  The repo also contains assets to assist your coding agents in pushing and editing your pipeline.  Be sure to fork it or copy it to your own project as a good starting point for your own automations.

The repo contains markdown files that will assist your AI tools in modifying or expanding these workflows so that you can easily make it your own.

References

• GitHub Actions documentation — how workflows, jobs, and Environments work.
• GitHub Actions workflow syntax — the reference for editing .github/workflows/*.yml files.
• ServiceNow SDK documentation — CI/CD integration guide.
• @servicenow/sdk on npm
• Installing the GitHub CLI (gh) — Optional, but enables scripts/setup-cicdfor help configuring your Secrets and Variables and the manual gh commands throughout this doc.
• Short link to this page: https://sn.works/sdk/cicd