CircleCi is a leading continious integration and delivery platform for building workflow jobs. The xMatters orb gives CI/CD authors the ability to generate xMatters events as a command in a job.
- A CircleCi account
- xMatters account - If you don't have one, get one!
- CircleCi - The communications plan with the form templates and inbound integration script.
How it works
There are two commands available in the xMatters orb. The first is
notify and accepts individual parameters, most of which come from the environment variables. The other command is
notify_raw and accepts a generic json payload. This allows infinite flexibility for the values in the payload which can then be acted on in the inbound integration script in xMatters.
Each command will fire a webhook into an xMatters inbound integration script, which will then parse the payload to generate the event.
xMatters set up
- Upload the CircleCi.zip comm plan to the Comm Plans section of the Developer tab.
- Click edit on the comm plan and navigate to the integration builder. Expand the inbound integrations section.
- Click the link for Inbound from CircleCi integration and scroll to the bottom.
- Select the appropriate user to use for authentication. This can be an integration user or your user depending on the use case. Make sure the user selected has access permissions on the Comm Plan and Sender Permissions on the Build Notification form.
- Copy the url and save for later.
CircleCi set up
- To avoid making the xMatters inbound url publically accessible, it is recommended to store it in a Project environment variable. Call this variable
- Update your project
.circleci/config.ymlfile to add a new step to execute either the
notify_raw. See the examples in the orb for more details.
Build the target project and inspect the build steps in the CircleCi UI and you should receive an event:
The CircleCi build log will have details up to the point it makes the curl request to xMatters:
Any failure messages in making the call to xMatters will be displayed here. If this shows all successful, but there is still no xMatters event, check the Activity Stream in the inbound integration for any errors.