Key Results from GitHub

Overview

If you have projects stored in GitHub issues, you may have key results based on progress made towards these projects. In this case, you can automate the tracking of progress towards the Key Result based on data from GitHub issues. The GitHub data connector for WorkBoard enables you to pull in counts of issues based on custom filters. Issues can be filtered based on key properties like Project, Status, Date and Labels.

Requirements

The GitHub data connector requires no additional configuration for out-of-the-box use for all users by default. However, enterprise admins often place restrictions on which applications users can access. As a result, the app may require an IT admin to grant approval before it will work with your instance.

Add a GitHub Key Result

Hover over your Objective and click the Kebab.
Select Edit Settings.
Select Add another Key Result.
Select Advanced Options.
Choose Pull data from external applications.
Pick GitHub from the list of integrations.
Sign in using OAuth or a Personal Access Token.
OAuth → for most customers, the default GitHub URL will be the correct URL for your site. However, if your company leverages a custom domain for your GitHub repository you will need to input that custom URL here.
PAT → Rather than allowing access by OAuth, some users may prefer to create and manage application-specific access by leveraging Personal Access Tokens (PAT). To use PAT for authentication change the dropdown to PAT and enter in your custom URL and Personal Access Token. For information on how to create a PAT see the GitHub documentation on creating Personal Access Tokens. Similarly to OAuth, the default url for most customers will the pre-filled value, if your organization uses a custom domain for GitHub, you will need to alter the API url to the correct value here.
Once signed in, select the Organization and Repository that you want to pull a list of issues from. Currently, WorkBoard does not support pulling a list of issues from multiple Organizations or Repositories.
(Optional) Use the dropdown to select additional filters to limit issues by.
Select the timeframe by which to filter issues by certain due dates. If selecting a Custom timeframe, select the date range of your choice.
(Optional) For real-time validation of data before connecting, select Preview results.
Choose Connect to set up GitHub integration.
Fill out or edit the remaining Key Result details such as Start Value, Result Value, Target Value, Committed Result, Unit of Measurement and how to Calculate Overall Progress.
Choose your Update Cadence, which determines when or how often WorkBoard will sync with GitLab to pull the latest value for your Key Result.
Note: Update cadence has the same options you would find for Key Results updated by a person (i.e., Daily, Weekly, Monthly, and Quarterly).

Synchronize Data from GitHub

WorkBoard will pull data for the KR directly from GitHub following the cadence specified. The Business Result Owner also has the ability to “sync data now” to pull data in real-time.

There are two ways to sync data for your Key Results.

Force a Sync on a Single GitHub Key Result:

Select Key Result to go to the Key Results Details page.
Choose the Kebab menu in the upper right-hand corner.
Select Sync Integration Data.

Force a Sync for all Key Result Integrations:

From the My Objectives Page, select the Kebab icon in the upper right-hand corner.
Select Sync Integration Data.