GitHub Integration

A Comprehensive Guide to Craft.io Integration with GitHub

Shira Lang avatar
Written by Shira Lang
Updated over a week ago

Craft.io allows you to set up two-way synchronization with GitHub.
The following instructions will take you, step by step through the setup.


1. Connecting Craft.io with GitHub

The first step of the configuration is to connect Craft.io to GitHub. Click Integrations from the Settings menu at the top right corner, and choose to connect to GitHub.

You will be prompted to enter your GitHub credentials. This includes your GitHub Personal Access Token and Enterprise URL (optional). Enter your credentials and click 'Next'.


Note: To generate your personal access token in GitHub, go to Settings/Developer Settings/Personal Access Token (Classic), select: Generate New Token with scope: 'repo', 'admin:repo hook' and 'project', and click "Generate Token".

1.1. Connecting Craft.io with GitHub Repositories

In the next step, you can choose to sync your Craft.io Workspace with a single or multiple GitHub repositories.

Single repository: if you want to sync all Craft items to a single repository, you can skip the labels step.


Multi repositories: for Craft.io to push items to the relevant GitHub repository, you will need to assign a label tag to each repository. You can create a new label, or select from the list of existing labels.


2. Integration Settings

Choose Craft Teams to Sync with - In Craft.io you can assign a work item to a Team or a specific Assignee under a Team (these can be defined in the Team Manager). For Task and Bug work items to sync to GitHub, they'll need to be assigned to an individual or team, using the Assignee field. Please choose the Teams you wish to be available to choose from.

Import Options - For syncing from GitHub to Craft.io. You can choose between pulling all new tickets created in GitHub (they will be imported automatically as the webhook is triggered), and pulling only items with a specific tag. Note: the second option only works with a single repository connection. If you set up multiple repositories, only the first repository will identify the tags, and the rest of the repositories will include all items.

Export Options - For syncing from Craft.io to GitHub. Here you can choose between pushing any item created in Craft.io, and pushing only items with a specific label. In the initial integration step, the labels make the connection between the Workspace and the repositories. However, in this step, the labels tell Craft.io whether to push an item to GitHub or not. Items without the labels pre-defined in this step, could not be synced.

Sync Milestones to Quarter - If you wish to sync between GitHub Milestone field and Craft.io Quarter field - keep toggeled on.

Select your preferences and click 'Next'.


3. Setting up a Webhook

You've now completed setting up the initial connection and preferences for syncing between Craft.io and GitHub. While you can start pushing data from Craft.io to GitHub, you will need to set up a Webhook, which will allow GitHub to push data back to Craft.io.

Although you can go back to this stage later, we recommend completing the Webhook setup during the initial integration setting.

Follow the instructions on this screen, and make sure to set up a Webhook for each of the repositories you're connecting to Craft:

Update 12/2023: In step #4, please choose "Send me everything".


4. Data Mapping between Craft.io and GitHub

The following data will be synced through the two-way integration. Please note the comments section below.

Type Mapping

Name in Craft

Name in GitHub

Comments

Epic

N/A

Feature

Issue

Requirement

Issue

Task

Issue

Only when assigning the item in Craft to a Team or a specific Assignee under a Team that was selected in the integration settings

Bug

Issue

Only when assigning the item in Craft to a Team or a specific Assignee under a Team that was selected in the integration settings

Story

N/A

In Craft.io, work items must have a parent-child relationship. Since GitHub has only one type of item without a parent, when an issue is synced to Craft for the first time, a new Epic is created to serve as its parent.


Field Mapping

Name in Craft

Name in GitHub

Comments

Title

Title

Description

Description

Comment

Comment

Dev Status

Status

Updating the 'Status' field in GitHub doesn't trigger the Webhook, as it's set on a Project level. Make sure to make a change in the Title or Description fields, to trigger the webhook and update the item in Craft. You can later change these fields back

Sprint

Iteration

Updating the 'Iteration' field in GitHub doesn't trigger the Webhook, as it's set on a Project level. Make sure to make a change in the Title or Description fields, to trigger the webhook and update the item in Craft. You can later change these fields back

Quarter

Milestone

Optional - need to be toggled on in the integration settings

Label

Label


5. Import your GitHub Issues to Craft.io

Now that the 2-way integration setup is completed, any new issues created in GitHub, or updates made to existing issues, will automatically trigger the webhook to push them to Craft.io. Assuming that you have more existing issues that may not be updated and triggering the webhook, you can perform a manual import, to start building your product backlog in Craft.

When you perform a manual sync from GitHub to Craft, you can choose which tool holds the latest data and should override the other tool's data. In case you don't have a backlog in Craft yet, choose the second option: 'Override Craft items with GitHub items'.
If you already started building in Craft, choose between options 1 and 3: 'Override GitHub items with Craft items' or 'Sync according to the last updates'.

Next, choose which repositories to sync from, and click 'Sync'.

In the final step, select the parts of your Craft Workspace you wish to push to GitHub. The following options are available:

  • All Workspace - Syncs the entire Craft.io Workspace to GitHub.

  • Quarters - This allows you to select one or more Craft.io Quarters to be pushed to GitHub.

  • Sprint Backlog - This allows you to select one or more Craft.io Sprints to be pushed to GitHub.

Note: You may take this step of the syncing during the initial setup, or come back to it later by clicking on Settings > Integrations > 3-dots menu > Sync.


Pushing your project, or part of it, may take some time to complete. Please wait until the data has been transferred.

All GitHub issues are created in Craft.io under the GitHub Theme feature. You can move them to different Products across Craft.io using drag and drop in the Product Backlog / Spec Editor views, or by using each item's menu.


6. Continuous Syncing from Craft.io to GitHub

Once you have created your new Craft.io product backlog, prioritized your features, and built your roadmaps, it's time to start pushing items to GitHub and track the items' delivery progress.

Every sync from Craft to GitHub should be done manually - whether it's a new item or updates made to an existing one.

Important! Whether you choose to sync a single item or to perform a bulk sync to multiple items, remember to take the following actions before clicking on 'Sync':

1. Add the relevant label to identify the repository the item should be pushed to;

2. Add the relevant label(s) if you set Craft to export only items with certain labels;

3. For Tasks and Bugs - add a specific person or a team to the Assignee field.

Single item sync

The first way to sync an item to GitHub is by double-clicking on the item to open the Item’s properties panel. Then click on the ‘GitHub’ tab. Then click 'Sync item'.

Bulk syncing of multiple items

Bulk syncing from the Table/Kanban views allows you to sync multiple items to GitHub at once. You can do so by following these steps:

  1. Select as many items as you want to sync by checking the box next to their names

  2. Navigate to the toolbar at the bottom of the screen

  3. Click on the GitHub icon to sync all the items at once


For any assistance with setting up the Craft.io - GitHub integration, or with syncing items between the tools, please contact our team at support@craft.io.

Did this answer your question?