Replace Basic Auth with OAuth and configure CI/CD with Github Actions and Now-SDK

[Jon G Lind]

OAuth with CI/CD With ServiceNow SDK and GitHub Actions

This is the full, start-to-finish walkthrough for wiring up this repo's pipeline against your own ServiceNow instances — both authentication options (Basic and OAuth client credentials), on both the test and production side.

Step 0: Get the code

You will need the github action configs and the setup scripts.  I suggest forking it or just cloning it as a starting point, but you will need to be working from the github repo you wish to wire up to use CI/CD.

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

What this pipeline does

The pipeline is split across three files, all built entirely on the ServiceNow SDK's own Continuous Integration/Continuous Delivery (CI/CD) commands that are part of Now-SDK (now-sdk install and now-sdk cicd) 

• .github/workflows/_validate.yml — a reusable workflow (workflow_call) holding the build/install/Automated Test Framework (ATF) steps shared by both pipelines below, so there's one copy of this logic to maintain:
  1. build-and-install-test — builds the Fluent source and installs it directly onto a test instance (now-sdk install)
  2. atf-test — runs the app's ATF regression suite against that same instance (now-sdk cicd testsuite run)
• .github/workflows/pr-validation.yml — runs on every pull request targeting merge to main. Calls the reusable workflow above so a broken change shows up as a check on the PR before it's merged, and pushing a fix to the same branch automatically re-runs it.
• .github/workflows/deploy-main.yml — runs on every completed push to main (i.e. after a PR merges). After deploying it continues to publish the version to ServiceNow's Application Repository (App Repo) via now-sdk cicd publish. Next there is a manual approval gate on Github followed by install-prod which deploys to prod (now-sdk cicd install).

 

Basic Auth vs OAuth

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

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".

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

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 create a new PR.
6. Once the check is green, merge to main and dthe Deploy to Prod pipeline executes and waits for the production approval gate before installing to prod. (NOTE: This will not work on a Personal Developer Instance (PDI) due to the lack of an App Repo).

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.

See the ServiceNow SDK docs or run now-sdk explain ci-integration locally.