Integrating GitHub with Forecast

⏱️ 5 minute read

Connect developers and code with the GitHub for Forecast integration. The integration with GitHub allows effortless management and syncing of software development between GitHub and Forecast creating transparency over commits and code issues for everyone who is involved or needs to be informed. Get instant access to the integration's features to attach pull requests and issues to a Forecast task, set tasks to done via merging a pull request, and automate the linking of branches to tasks. 

This article covers:

• GitHub Integration Data Flow
• Setting up the GitHub for Forecast Integration
• Syncing Forecast Users to GitHub Profiles
• Synchronizing Forecast projects to GitHub repositories
• Attaching GitHub Issues/Pull Requests to Forecast Tasks
• Disconnecting the GitHub integration

GitHub Integration Data Flow

The GitHub for Forecast integration allows users to manage everything from a single place and avoid duplicate work while keeping users, tasks, workflow, estimates, phase, and assigned team members up-to-date. Simply select the repository to connect to the project for 1-to-1 synchronization between a Forecast project and a GitHub repository. 

The following diagram outlines the integration's data flow:

Setting up the GitHub for Forecast Integration

The setup of the integration is easy and it includes enabling it from Forecast and configuring if all repositories should sync to Forecast or just some. As with all integrations in Forecast, this process may only be done by a user with Admin access to the account. 

To set up the GitHub for Forecast integration

1. Click Admin in the top bar. 
2. Select Integrations.
3. Click on GitHub.
4. Click Install.
5. Log into GitHub and then select whether All repositories should sync or just the selected ones. 
6. Click Activate, once the Forecast integration page reloads. 

Syncing Forecast Users to GitHub Profiles

Once the integration is set up, it is important to sync the profiles of Forecast users with their GitHub profiles. Profile syncing allows for tasks created by these users to appear as issues in GitHub. If a user is not synced between the two profiles, any actions they take on either platform will not be synced to the other platform. 

It is not possible to link a Guest User profile with GitHub. Any tasks created by Guest Users in Forecast will not appear in GitHub as issues. 

To sync Forecast user profiles to GitHub user profiles

1. Click Admin in the top bar.
2. Select Resources from the dropdown. 
3. Click on the user that needs to be synced.
4. Scroll down to the GitHub section.
5. Under 'GitHub user name', type in the name of the user in GitHub and select Search.
6. The user will display as an option below the empty text field. To sync the users between the two platforms, click on the correct user, and from the pop-up modal click on Link.

Synchronizing Forecast Projects to GitHub Repositories

Repositories from GitHub can be synced with projects in Forecast. The integration also grants the ability to sync the repository issues with the Forecast project and vice versa.  Essentially, this syncs issues from GitHub to Forecast as projects and tasks from Forecast to GitHub as issues. 

To sync a Forecast project to a GitHub repository

1. Click Projects in the top bar.
2. Select All Projects from the dropdown. 
3. Click on the project you wish to sync.
4. In the left side panel, click Settings.
5. Select Integrations.
6. Under the GitHub option, click on the dropdown and select the repository the project should sync to.
7. If it is necessary to bring over GitHub issues to this project and to send this project's tasks to GitHub as issues, click on Sync and click Okay when a modal is prompted. 

Attaching GitHub Issues/Pull Requests to Forecast Tasks

It is possible to manually attach GitHub issues to Forecast tasks. This ability also extends to pull requests from GitHub. 

To attach GitHub issues to Forecast tasks

1. Click Projects in the top bar.
2. Select All Projects from the dropdown.
3. Access any project that is already synced with a GitHub repository.
4. Click on any task to open the task modal.
5. Scroll to the section under the description that reads GitHub.
6. Click on Issues and select any of the issues that are presented. 

The task will now be attached to that issue from GitHub. A link will also be created, and by clicking on it the user will be taken to that issue in GitHub.

To attach pull requests from GitHub to Forecast tasks

1. Click Projects in the top bar.
2. Select All Projects from the dropdown.
3. Access any project that is already synced with a GitHub repository.
4. Click on any task to open the task modal.
5. Scroll to the section under the description that reads GitHub.
6. Click on Pull Request and select any of the pull requests available.

The task will now be attached to a pull request from GitHub. Pull requests can assist with setting the status of tasks in Forecast. If a pull request is merged with a description that contains any of the following keywords, followed by a valid task id, then that task will be moved to the first Done status column in its Forecast project:

• Close/close, Closes/closes, Closed/closed
• Fix/fix, Fixes/fixes
• Resolve/resolve, Resolves/resolves, Resolved/resolved

The same behavior applies when a "branch" in GitHub contains the task ID. If a new branch name contains a task ID (e.g T17), then that task will be linked to the branch, and pull requests belonging to that branch will automatically be attached to the task as well.

Disconnecting the GitHub Integration

If the GitHub integration is no longer needed, it may be disconnected. Disconnecting the integration will remove all links across the Forecast and GitHub platforms. Reconnecting the integration in the future is possible, however it may result in duplication across platforms. 

To disconnect the GitHub integration

1. Click Admin in the navigation ribbon. 
2. Select Integrations from the dropdown. 
3. Click on the GitHub icon under Project Management, devOps & code. 
4. Click Deactivate. 
   
5. The integration is deactivated and the sync across platforms is no longer active.