GitHub is an open-source version control software that lets multiple people make separate changes to a project or application’s source code at the same time. With Cutover’s GitHub integration, you can automate your work and maximize productivity –effortlessly create and execute tasks within the Cutover platform to create branches and pull requests in GitHub.
Prerequisites
To use this integration, you will need to create an app token with permissions to your GitHub repositories. Additionally, please note that each integration action and linked repository counts as its own individual integration.
Permissions
To enable the integration, the Integrations Admin role is needed. Please contact your Customer Success Manager (CSM) for assistance in setting this up.
Integration features
Create branches and pull requests in GitHub within Cutover by first adding your GitHub integration connection and associated action items within the Global Settings > Integrations menu.
Once you’ve entered the necessary details, your GitHub action items will be enabled and available for use in your runbook. Your repository will update accordingly after your tasks are executed.
Add a GitHub connection
To add a GitHub connection, first navigate to Settings > Integrations.
Any previously configured integrations will be displayed on the Integrations Connections page.
Note: If you have not previously added integrations, this page will be blank.
To find out more about our integrations, click Learn more at the top of the Integrations Connections page. To create your new predefined integration, click on + Create integration.
The New Integration Connection window displays. Click on the Predefined integration radio button.
The definition of a predefined integration is displayed. Predefined integrations are restricted to cloud to cloud authorisation and have predefined parameters.
Note: Please see our Developer Portal Integration pages if you would prefer to set up an integration based on your own requirements, authorisation and authentication.
Click in the Integration field to search for an integration. You can type the integration name or scroll to search.
Note: You will first need to create the integration before adding the integration action, as illustrated by the steps listed below.
Enter the following details:
Name: A default name is added however this can be manually changed in the Name field. The name entered here is what is displayed in the task edit panel when the integration is added
Image URL: This field is automatically populated
GitHub Authorization token: Enter your app token so that Cutover can access your GitHub repositories
Name of your GitHub organization: Enter the name of the repository you wish to use
When you have finished, click CREATE. The newly created integration will be listed at the bottom of the Integrations Connections page.
Add an integration action
Once you have successfully connected GitHub to Cutover, you will need to set up an action that your integration will perform within Cutover.
First, select your newly added GitHub connection to open the Edit GitHub panel. Click New.
In the New GitHub Action modal, complete the following details:
Action: Select the action you would like the integration to execute. The available actions are Create Branch, Create Pull Request, and Create a release.
Name: Enter the specific GitHub name for the action. This is what you will search for when you want to add this action to your runbook.
Image URL: Enter the image URL for your action item.
Trigger: Select the trigger for the action. The current available trigger is On Task Start. The integration will trigger when your task has been started.
Visibility: Select what workspace the integration is assigned to in this drop-down menu. In the drop-down, browse the available workspaces in your Cutover instance. By default, this field is set to “Global.”
Plus there are Additional Settings options:
Auto start: The task will automatically start upon the task's predecessor completing, without requiring manual intervention to get it underway. If the trigger is “On Task Start“ then this also means that the integration will fire automatically.
Enable fixed start time: It will be possible to add a fixed start time in a runbook’s editing panel for the task; this means the task can only be started at the day and time that has been set.
Cancelable: It will be possible to cancel a task during its execution.
Notify Webhook on Cancel: On task cancellation, an HTTP request will send an abort/cancel message to the specified URL.
Important: Aborting an integration prevents any further integration actions from being executed but will not stop any process that the integration has initiated when invoking the third-party API.
Finish task on success: The task will finish when the integration’s status is set to success.
Include context in Request: The outbound payload request will contain information about the runbook and task.
Execute in Rehearsal: The task can be executed when the runbook is in rehearsal mode.
Note: The GitHub action item automatically includes custom fields, which are displayed under 'Integration action custom fields', as illustrated via the image below.
The Associated Custom Fields available are different depending on the action chosen. The associated custom fields are as follows:
Create branch - New branch name, New branch URL
Create Pull Request - New PR URL, PR Status, PR title, PR message, PR type
Create a Release - Tag name, Release message, This is a pre-release, Generate release notes
Lastly, enter the name of your GitHub repository. To do this, click Custom Settings > CREATE.
Edit a GitHub integration and action
To edit your integration, click on your GitHub connection on the Integration Connections page to edit it. The Edit GitHub panel will appear, as seen below.
The integration name, image URL, and any other fields can be edited as needed. In addition to editing the integration details, you can edit any action item within the integration itself by clicking the small cog icon next to the trigger details:
Clicking the cog will open an edit form for the integration action where all the default
and custom settings are stored, as seen in the image below:
When you have finished editing, you can click Save or Discard to abandon any changes that have been made.
Use your integration
Once the integration is configured, save the task.
Next, head over to your runbook and add a new task. In the Task Type field, search for your integration connection and select it.
Once you are satisfied with the tasks that have been added, start your runbook or task by clicking the Play icon located in the right upper-hand corner of your runbook to execute your integration.
The GitHub task in Cutover will execute your action item in GitHub.