Working with GitHub integration

This section describes how to set up a connection, connect a project to a GitHub repository, configure progress mapping, push a task to GitHub, work from both systems, maintain the connection, and, if needed, remove the integration. For more details, limitations, and frequently asked questions, refer to About issue tracking with GitHub. 

On this page:

1. Set up the GitHub Issues connection

2. Connect a project to a GitHub repository

3. Configure progress mapping

4. Push one or more tasks to GitHub

5. Work from either system

6. Maintain the connection

7. Remove the issue tracking integration

 Establish the organization-level GitHub connection that Level Access projects can use. 

To set up the GitHub Issues connection: 

1. Navigate to the organization level, and then to Tools & Integrations.

2. Select Issue tracking.

3. Select Add connection.

4. Select GitHub Issues.

5. Confirm Level Access workspaces that should have access. By default, all workspaces will be granted access to this connection. If you want to limit access to specific workspaces, unselect them from the Workspace access * dropdown.

6. Select Continue.

7. Select Connect to GitHub Issues. This step authorizes Level Access Platform to access your GitHub Issues account. You will be redirected to GitHub to complete the authorization.  

8. Sign in to GitHub. Grant repository access.

9. Return to Level Access. Upon success, a message is displayed. The GitHub connection appears with an Authorized status. If authorization fails or is denied, an error is shown.

Determine which GitHub repository receives Issues created from the Level Access project.

To connect a project to a repository:

1. View or edit a Level Access project.

2. In the Issue tracking software field, select GitHub Issues.

3. Select the existing GitHub Issues instance.

4. Search the available repositories.

5. Select a GitHub Issues repository.

6. Save the project.

Keep development status in GitHub aligned with remediation task progress in Level Access. From the project, configure how GitHub states map to Level Access task progress. 

Note: The available GitHub values are Open and Closed. Select the corresponding Level Access task progress for each.

To map your GitHub Issues and Level Access project progress:

1. Go to Projects/tasks. 
2. Find the project you want to map to and select the three-dot action menu.
3. Select Configure Progress Mapping. The Progress Mapping page is displayed. 
4. Select a GitHub Issues status on the left to trigger an automatic update to a Level Access Platform task progress on the right. Note that each GitHub Issues status can only be connected to one platform task progress. 
5. Select a Level Access Platform task progress on the left that will trigger an automatic update to a GitHub Issues status on the right.
6. Select Save.

To push a task to GitHub Issues: 

1. Navigate to one of the following entry points: 

• The project task list.
• Task Details.
• The Create Task workflow.

2. Select a task you want to push to GitHub Issues. 
3. Select Push to GitHub. A confirmation modal displays a preview and shows the connected repository. 
4. Select Push. Level Access creates a ticket in GitHub Issues. A success message is displayed. The Level Access task displays the following information: 
   1. Link to the issue in the Linked ticket column
   2. Status of the issue, in the External status column

Note: If the push fails, select Retry. 

To push tasks in bulk: 

1. Navigate to the workspace level, and then to one of the following entry points: 
   • The project task list.
   • Task Details.
   • The Create Task workflow.
2. Choose each task you want to push.
3. Select Push to GitHub. A pop-up will open. 
4. On the New issues tab, select the appropriate Task pushing options:
   • All tasks to the same project as the same issue type
   • All tasks to the same project as different issue types
   • Each task to a different project as the same issue type
   • Each task to a different project as different issue types
5. Select the GitHub Issue project. 
6. Under Push task(s) as issue type(s), select the option(s) you want. 
7. Select Push.

To push tasks in bulk to an existing issue: 

1. Switch to the Existing issues tab.
2. Select Existing issue. 
3. Enter the Issue ID for each task. 
4. Select Link to existing.

It may take a few minutes for a task to be successfully pushed or linked to GitHub Issues.

Note: Issue project and issue type are optional fields. If no project is selected, the issue is created at the repository level. If no issue type is selected, the issue is created without an issue type, and the corresponding field remains empty in GitHub.

1. Link the task and GitHub Issue. Refer to Push a task to GitHub. 

2. Open the GitHub Issue from the linked task in Level Access. To do so: 

   1. Display the project to list its tasks.

   2. Select the link in the Linked ticket column. The task is displayed in the configured GitHub repo. 

   3. Work with the task in GitHub. 

If the connection is not-authorized, re-authorize it. You can reauthorize the connection from the Project page only if you have an error (an interrupted or unauthorized connection). 

To reauthorize an issue tracking connection from the Project page (Issue Tracking roles only): 

1. Navigate to the workspace level. 

2. Under Find and Fix, select Projects and tasks. The Projects tab is displayed. 

3. Find the project you want to open and select View project. If the project has an error with the issue tracking connection, a notification is displayed.  
4. Select Edit issue tracking connection. The Edit connection page is displayed. 
5. Select Review error message, to learn more about the error. Select Close, to close the message. 
6. Select the Reauthorize option.
7. Select Save.

GitHub can be removed at two levels, from a Level Access project, or by removing the organization-level GitHub connection.

Note: Removing a GitHub issues connection will unsync any linked tasks and prevent any further syncing within an organization.

To remove a GitHub Issues connection from a project:

1. Navigate to the workspace level. 

2. Under Find and Fix, select Projects and tasks.   

3. Find the project.
4. From the three-dot action menu in the top right corner, select Edit. The Project details page is displayed. 
5. Scroll until reach the section Connect to issue tracking software (optional).
6. Select Remove. 

Note: After removal, the Level Access tasks remain, their GitHub relationships are removed, and synchronization stops for those links.

To remove the GitHub Issues connection at the organization level:

1. Navigate to the organizational level. 

2. Under Manage, select Tools & Integrations, and then select Issue tracking.   

3. Find the connection you want to remove and select the three-dot action menu.
4. Select Remove.
5. Select the checkbox to acknowledge that you want to remove he connection.
6. Select Remove connection.

A warning is displayed, if any projects are using the connection. When the connection is removed:

• Connected projects lose the GitHub integration.

• Linked tasks are unlinked.

• The GitHub webhook is removed.

• GitHub Issues are not documented as being deleted.