GitHub Integration

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

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".

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.

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'.

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".

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

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.

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:

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.

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.

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 from the Table/Kanban views allows you to sync multiple items to GitHub at once. You can do so by following these steps:

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.