Skip to content

ServiceNow Integration MVC

Problem to solve

For customers using ServiceNow as a change management system, we need to be able to include that approval as part of the pipeline process before deployment.

Intended users

This feature will be used by a variety of roles for the following purposes:

Role Use
Developer This allows developers to stay compliant to their organizations change management practices without having to ever leave GitLab
Change Manager This allows change management staff to evaluate and approve/deny releases to infrastructure without having to leave ServiceNow

Further details

The primary need for this tool is to allow organizations to restrict the deployment of builds to their environments, adding a gated process that requires explicit approval along a predefined process. There are a variety of reasons for this type of process:

  1. Compliance/regulatory requirements -- Needs to ensure that specific review practices are being followed on the release of code, be those technical, legal, operational, etc.
  2. Change window practices -- Some companies only release change during specific periods, such as after-hours, on weekends, or during a certain day of the month. Conversely, some companies have strict blackout periods, and this sort of tooling would allow them to enforce those at the ServiceNow level.

Proposal

To address this need, we need to define a CI job (or set of jobs) that has the ability to take predefined data and CI artifacts and create a ServiceNow change request with that data, wait for approval of the request, and then resume running the pipeline to deployment.

Workflow

Setup

  1. Project owner adds ServiceNow credentials/configuration variables to Secrets
    • Variables include SNOW URL, Token, and other relevant values such as assignee, subject/title template, labels, etc.
  2. Developer copies a ServiceNow job template and adds it to their .gitlab-ci.yml in the appropriate location

Development workflow

  1. Developer commits code to the project
  2. Pipeline on branch runs, and if all jobs pass, code is able to be merged to master
  3. Developer merges code to master

Change request creation workflow

  1. Pipeline on master runs, containing a section that uses only: master
  2. A ServiceNow_request_approval job is run
    • Using the ServiceNow API, job checks to see if an existing change request exists for this hash
    • If no request exists, ServiceNow_request_approval creates a change request via the ServiceNow API and adds a noteable in the MR with a link to the change request
    • If a request exists, ServiceNow_request_approval manually calls the next step, ServiceNow_verify_approval
  3. ServiceNow_request_approval completes

Change approval verification workflow

  1. The ServiceNow_verify_approval job is either run directly by user intervention, called by the previous workflow step, or called by ServiceNow via the GitLab API
  2. ServiceNow_verify_approval uses the ServiceNow API to loop up the Change Request and verify it has been approved
  3. If approved:
    1. ServiceNow_verify_approval creates a notable in the MR showing that it was approved and is being deployed.
    2. ServiceNow_verify_approval passes and allows the pipeline to proceed to deployment
  4. If not approved, job fails, noting the approval was not found

Documentation

Future Concerns

Items that are currently out of the MVC scope, worth considering for follow-up issues.

  • How can we prevent users from circumventing the change management process?
    • How can we enforce this job or some version of it being run on a set of Projects (in a group or instance)
  • If the commit happened on a branch belonging to an MR, the SNOW ticket status should be reflected in the MR activity feed
  • Post-deployment, this integration should post a comment on the SNOW ticket indicating whether the deployment succeeded/failed.

Links / references

Edited by Patrick Deuley