GitHub Action
ServiceNow DevOps Change Automation
This custom action needs to be added at step level in a job to create change in ServiceNow instance. Using this custom action in parallel jobs is not supported.
- credentials (Devops integration token of a GitHub tool created in ServiceNow DevOps or username and password for a ServiceNow devops integration user)
- instance URL for your ServiceNow dev, test, prod, etc. environments
- tool_id of your GitHub tool created in ServiceNow DevOps
On GitHub, go in your organization settings or repository settings, click on the Secrets > Actions and create a new secret.
For token based authentication which is available from v4.0.0, create secrets called
SN_DEVOPS_INTEGRATION_TOKENrequired for token based authenticationSN_INSTANCE_URLyour ServiceNow instance URL, for example https://test.service-now.comSN_ORCHESTRATION_TOOL_IDonly the sys_id is required for the GitHub tool created in your ServiceNow instance
For basic authentication , create secrets called
SN_INSTANCE_URLyour ServiceNow instance URL, for example https://test.service-now.comSN_DEVOPS_USERSN_DEVOPS_PASSWORDSN_ORCHESTRATION_TOOL_IDonly the sys_id is required for the GitHub tool created in your ServiceNow instance
Step 3: Identify upstream job that must complete successfully before the job using this custom action will run
Use needs to configure the identified upstream job. See test.yml for usage.
deploy:
name: Deploy
needs: <upstream job>
runs-on: ubuntu-latest
steps:
- name: ServiceNow Change
uses: ServiceNow/[email protected]
id: create
with:
devops-integration-token: ${{ secrets.SN_DEVOPS_INTEGRATION_TOKEN }}
instance-url: ${{ secrets.SN_INSTANCE_URL }}
tool-id: ${{ secrets.SN_ORCHESTRATION_TOOL_ID }}
context-github: ${{ toJSON(github) }}
job-name: 'Deploy'
change-request: '{"setCloseCode":"true","autoCloseChange":true,"attributes":{"short_description":"Automated Software Deployment","description":"Automated Software Deployment.","assignment_group":"a715cd759f2002002920bde8132e7018","implementation_plan":"Software update is tested and results can be found in Test Summaries Tab; When the change is approved the implementation happens automated by the CICD pipeline within the change planned start and end time window.","backout_plan":"When software fails in production, the previous software release will be re-deployed.","test_plan":"Testing if the software was successfully deployed"}}'
interval: '100'
timeout: '3600'
changeCreationTimeOut: '3600'
abortOnChangeCreationFailure: true
abortOnChangeStepTimeout: true
deployment-gate: '{"environment":"deploymentgate","jobName":"Deploy"}'
- name: Output of Change Creation
run: echo "change-request-number = ${{ steps.create.outputs.change-request-number }}" >> $GITHUB_OUTPUTdeploy:
name: Deploy
needs: <upstream job>
runs-on: ubuntu-latest
steps:
- name: ServiceNow Change
uses: ServiceNow/[email protected]
with:
devops-integration-user-name: ${{ secrets.SN_DEVOPS_USER }}
devops-integration-user-password: ${{ secrets.SN_DEVOPS_PASSWORD }}
instance-url: ${{ secrets.SN_INSTANCE_URL }}
tool-id: ${{ secrets.SN_ORCHESTRATION_TOOL_ID }}
context-github: ${{ toJSON(github) }}
job-name: 'Deploy'
change-request: '{"setCloseCode":"true","autoCloseChange":true,"attributes":{"short_description":"Automated Software Deployment","description":"Automated Software Deployment.","assignment_group":"a715cd759f2002002920bde8132e7018","implementation_plan":"Software update is tested and results can be found in Test Summaries Tab; When the change is approved the implementation happens automated by the CICD pipeline within the change planned start and end time window.","backout_plan":"When software fails in production, the previous software release will be re-deployed.","test_plan":"Testing if the software was successfully deployed"}}'
interval: '100'
timeout: '3600'
changeCreationTimeOut: '3600'
abortOnChangeCreationFailure: true
abortOnChangeStepTimeout: true
- name: Output of Change Creation
run: echo "change-request-number = ${{ steps.create.outputs.change-request-number }}" >> $GITHUB_OUTPUT
The values for secrets should be setup in Step 1. Secrets should be created in Step 2.
Optional DevOps Integration Token of GitHub tool created in ServiceNow instance for token based authentication.
Required DevOps Integration Username to ServiceNow instance.
Required DevOps Integration User Password to ServiceNow instance.
Required URL of ServiceNow instance to create change in ServiceNow.
Required Orchestration Tool Id for GitHub created in ServiceNow DevOps
Required Github context contains information about the workflow run details.
Required Display name of the job given for attribute name in which steps have been added for this custom action. For example, if display name of job is Deploy then job-name value must be 'Deploy'
The change request details to be used while creating change in ServiceNow instance. The change request is a JSON object surrounded by curly braces {} containing key-value pair separated by a comma ,. A key-value pair consists of a key and a value separated by a colon :. The keys supported in key-value pair are setCloseCode, short_description, description, assignment_group, implementation_plan, backout_plan, test_plan
The time in seconds to wait between trying the API. The default value is 100 seconds.
The maximum time in seconds to wait until the action should fail. The default value is 3600 seconds.
The maximum time in seconds to wait for change creation. The default value is 3600 seconds.
This value will be used to resume or abort the pipeline if the change is not created within the mentioned time period (changeCreationTimeOut). The default value is true.
This value will be used to resume or abort the pipeline if the change step is not completed within the mentioned time period (timeout). The default value is true.
This change request number is provided as output upon successful creation of the change.
This change request sys id is provided as output upon successful creation of the change.
ServiceNow customers may request support through the Now Support (HI) portal.
Initially, ServiceNow product management and engineering representatives will own governance of these integrations to ensure consistency with roadmap direction. In the longer term, we hope that contributors from customers and our community developers will help to guide prioritization and maintenance of these integrations. At that point, this governance model can be updated to reflect a broader pool of contributors and maintainers.