Creating GitHub integrations
Adding a GitHub integration enables your organization to create tickets when incidents are created in IBM Cloud Pak® for AIOps, discover details about similar tickets, and assess the risk of implementing proposed changes. Once a GitHub integration is set up and running, you can select it from the Notifications area of your Promote alerts to an incident policies.
- About this task
- Prerequisites
- Best practices
- Creating a GitHub integration
- Editing a GitHub integration
- Deleting a GitHub integration
About this task
Create one or more integrations by defining the integration details that are outlined here. Provide the URL and personal access token of your GitHub server, the GitHub repository, username, and the repository owner or organization. Optionally, specify field-mapping information for the incident details sent to GitHub when incidents are created. A default template is provided.
Prerequisites
You need the following information to create a GitHub integration:
- URL of your GitHub server
- Personal access token for your GitHub server
- GitHub username
- GitHub Owner or organization
- GitHub repository
Best practices
- When creating multiple GitHub connectors, use a different username and token to facilitate speedier data collection. There is a rate limit for GitHub API calls of about 5000/hr per individual and 15000/hr at enterprise level.
- Use a personal access token that does not expire.
- When Historical data collection is selected (see step 9), select a start date close to the date that will be used for AI training. Selecting a date further back might result in more API calls to GitHub, especially if there is a large volume of issues.
Creating a GitHub integration
To create a GitHub integration, complete the following steps:
-
Log in to IBM Cloud Pak for AIOps console.
-
Expand the navigation menu (four horizontal bars), then click Define > Integrations.
-
On the Integrations page, click Add integration.
-
From the list of available integrations, find and click the GitHub tile.
-
On the side-panel, review the instructions and when ready to continue, click Get started.
-
On the Add integration page, define the general integration details:
-
Name: The display name of your integration. You cannot use spaces or special characters in the display name. Use only alphanumeric characters.
-
Description (optional): Optionally, enter a description of the integration.
-
URL of GitHub server: Enter the URL of the GitHub server, for example
https://api.github.com/
. If you have any restrictive egress network policies in place, ensure that the policies are updated to allow for this outbound integration. -
Personal access token for GitHub server: This token is used to authenticate your requests to access GitHub APIs. The owner of the token must have write access to the repository.
Figure. Add Github integration Important: The selected scope of your GitHub repository must be "repo" with Full control of private repositories. To configure this in your GitHub repository, navigate to your profile > Settings > Developer settings > Personal access tokens.
-
Username: Enter your GitHub username.
-
Owner or organization: Enter the GitHub repository owner or organization.
-
Repository: Enter the GitHub repository.
Figure. Add Github integration
-
-
Click Next.
-
You can use the default issue template as-is, or customize it to include different information. A title is required or the issue cannot be created. In addition to the fields included by default, you can also specify 'state' and 'assignees' for the incident. Incident 'priority' must be set in the label, otherwise the priority will be appended and not replaced.
The owner of the token must have push access to the repository to set 'labels' and 'assignees' for new issues. Changes to 'labels' and 'assignees' are silently dropped if the user does not have push access to the repository.
Figure. Customize GitHub issue template Note:
$string(URL_PREFIX)
reads from theURL_PREFIX
environment variable to create the URL. The value for this variable ishostname
. -
Define how ticket data is collected:
-
Data collection: toggle to Off or On. The default is On. Note, if the rate limit for GitHub API calls is reached, an alert is sent to notify users that the connector is sleeping until the reset time from GitHub.
-
Mode: choose between Live or Historical. Live is the frequency at which data is sampled for GitHub issues in minutes (1-60 minutes). The default value is 1. For Historical, select a start date to retrieve closed GitHub issues since their last updated time.
Figure. Collect and synchronize operations data
Once the historical data is collected, you can train the data in AI model management using similar tickets training.
-
-
Click Done. You are redirected to the GitHub integration page.
Your new integration is listed in the table on the page. The integration has an initial status of Initializing. After a few minutes, the status changes to Running if your integration is successful. Once the integration is running, you can select GitHub as a ticketing option in your Promote alerts to an incident policies.
Editing a GitHub integration
After you create your integration, you can edit the integration. For example, if you want to customize the mappings in the issue template. To edit an integration, complete the following steps:
-
Log in to IBM Cloud Pak for AIOps console.
-
Expand the navigation menu (four horizontal bars), then click Define > Integrations.
-
Click the GitHub integration type on the Manage integrations tab of the Integrations page.
-
On the GitHub integration page, click the name of the integration that you want to edit. Alternatively, you can click the options menu (three vertical dots) for the integration and click Edit. The integration configuration opens.
-
Edit your integration as required. Click Save when you are done editing.
Your integration is now edited.
Deleting a GitHub integration
If you no longer need your integration and want to delete it entirely, you can delete the integration from the console.
To delete an integration, complete the following steps:
-
Log in to IBM Cloud Pak for AIOps console.
-
Expand the navigation menu (four horizontal bars), then click Define > Integrations.
-
Click the GitHub integration type on the Manage integrations tab of the Integrations page.
-
On the GitHub integrations page, click the Delete icon for the integration that you want to delete.
-
Enter the name of the integration to confirm that you want to delete your integration. Then, click Delete.
Your integration is deleted in IBM Cloud Pak for AIOps.