1. Help Center
  2. Integrations
  3. Project Management, DevOps and Code

GitHub

Sync and track issues and pull requests.

Setup

  1. Go to the GitHub integration page and click Install. Follow the on-screen instructions and give the integration to the repositories that you wish to integrate with from Forecast.
  2. Once you have completed the Install step above, you will be redirected back to the integration page. Click Activate and follow the on-screen instructions. Once you are redirected back to the integration page, the GitHub integration is now enabled.

If you ever need to change which repositories the integration has access to, you do not need to go through this flow again. Instead go to applications, under your GitHub settings, and click Configure for the Forecast app.

Sync Users

Once you are done with the initial setup you should sync all of your team members that currently have a GitHub account and require access to it from their Forecast account. Team members can do this individually or it can be done by a system Admin. The steps below will guide you.

Step 1: If you are an Admin go to the the Admin panel, click on the People tab and find the team member you wish to sync with GitHub. If you are not an Admin and you have a GitHub account and wish to connect it simply go to your profile by clicking My Profile.


Step 2: 
Once you are in your own or a team members profile scroll all the way down to the section that reads GitHub.

Step 3: Click on the search bar and search for the name that your team member or yourself have registered with on GitHub. Once you have found the correct one, click on it and your team member is now synced with GitHub.

githubgif1

Step 4: To ensure that your team member is synced, look for the GitHub icon next to their name in the people tab or make sure that you can see their GitHub name under their profile's GitHub integration.

Features and functionality

There are three distinct features in the GitHub integration:

  • Attaching of pull requests and issues to a task in Forecast
  • 1-to-1 synchronization between a Forecast project and a GitHub repository
  • Setting tasks to done via. merging a pull request

In order to use either, you must first navigate to the settings page of the project for which you want to use either of these features. Under Integrations you will see a section labelled GitHub and a dropdown of the repositories which you gave the integration access to during the setup of the integration. Depending on which of the features you want to activate, do the following:

  • To attach pull requests or issues to tasks in a project in Forecast, the repository of that pull request or issue must be added here.
  • To enable the 1-to-1 synchronization between project and repository, the repository must first be added and then the Sync toggle for that repository selected. As soon as this is toggled, the integration will start creating Forecast tasks from GitHub issues and vice versa. If the sync is later disabled for this project, the issues and tasks will not be deleted and subsequent re-synchronization will cause them to be created again in the other system. This synchronization also created comments and milestones in the same manner.
  • If a pull request merged with a description that contains any of the following keyword, followed by a valid task id, then that task is moved to the first Done status column in it's Forecast project.
    • Close/close, Closes/closes, Closed/closed
    • Fix/fix, Fixes/fixes
    • Resolve/resolve, Resolves/resolves, Resolved/resolved
    Examples: Closes T17, resolves T17, Fix T17

Attaching pull requests and issues

After you have added repositories in the project settings, you can attach pull requests and issues in any task for that project. You do this in the task modal, by clicking either the PULL REQUEST or ISSUES button down in the GitHub section. Once you attach something to the Forecast task, a link is created so that you can easily navigate to the attached item from the Forecast task.

issues

Likewise, a link to the Forecast task will also be present in GitHub.

Project to Repository synchronization

Once a Forecast project has been linked to a GitHub repository, an initial synchronization is started which ensures that all Forecast tasks are in GitHub as issues and vice versa. Tasks and issues created past the point of synchronization are created in the other system in real-time and a synchronization job runs every night in case a change in either system is somehow missed. Milestones and comments are also synchronized in this system.

The data is mapped in the following way:

Forecast Task GitHub
Name Title
Description Description
Status State (Done = Closed, To do or In progress = Open)
Milestone Milestone
Assigned Assigned
Labels Labels