GitHub Integration

A Comprehensive Guide to Craft.io Integration with GitHub

Simon Wilson avatar
Written by Simon Wilson
Updated today

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

Syncing Craft.io to GitHub

Connecting Craft.io to GitHub

The first step of the configuration will connect Craft.io to GitHub. Click Integrations from the user menu at the lower left, and choose to connect to GitHub.

You will be prompted for GitHub credentials. This includes your GitHub Personal Access Token and URL:

Enter your GitHub personal access token and GitHub Enterprise URL, and click Next.

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

In the next step, you can choose to sync your Craft.io Workspace with one or more GitHub repositories.

For each GitHub repository, you will need to assign a Craft.io label tag. You can create a new label, or select from the list of existing labels.

Craft.io items will be synced to a GitHub repository according to their label. 

Note: In a multi-repository configuration, every item in Craft.io must have a label assigned to it. An item without a relevant label will not be synced.

Additional Integration Settings

In this step you will be asked to finalize the integration settings;

  • Select Craft.io team to sync with; While features and requirements are synced as GitHub issues regardless of the teams you choose - tasks, bugs, and improvements will be synced only for the selected team or teams you choose. 

  • Select how to sync GitHub Milestones; You can select if you want to sync GitHub Milestones as Craft.io releases, Craft.io sprints, or not at all:

Mapping between Craft.io and GitHub

The following items will be synced Through the two-way integration between Craft.io and GitHub. Note: Syncing will never delete any items on both sides.

Type Mapping

 Field Mapping

Congratulations! You are now ready for your first sync! 

You can synchronize the systems for the first time or you can do it later. You can also choose to skip this step and sync selected items instead. For more information about syncing a specific item, see ‘Sync a Single Item’ section below. 

Note: you can always return to this step by clicking Push button:

First time sync between Craft.io and GitHub

You can sync by selected repositories, or all repositories at once.

Note: On the first sync the GitHub project is synced into your Craft.io Workspace. The import is performed once. To enable automatic updates from GitHub to Craft.io, you will need to set up a webhook in GitHub. For more information see the section “Syncing GitHub Back to Craft.io” below.

  

Select the parts of your Workspace in Craft.io that you want to push to GitHub. The following options are available:

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

  • Releases - Allows you to select one or more Craft.io releases to be pushed to GitHub.

  • Sprint Backlog - Allows you to select one or more Craft.io sprint backlogs to be pushed to GitHub.

Note: Pushing your project, or part of it, may take a long time to complete. Please wait until the data has been transferred.
Note: 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 Editor, or by bulk action in the Search and Filter tool. For more about Search and Filtering, look Here

Syncing GitHub Back to Craft.io

The second step in synchronizing GitHub with Craft.io is to configure the settings in GitHub so that changes made in GitHub will be updated in Craft.io automatically.

From the user menu, select Integrations and click Sync GitHub back to Craft. You will see information on how to create a webhook in GitHub, as well as the webhook listener URL to use in the webhook configuration. This is a unique URL that contains your product ID. Copy the URL to your clipboard and continue to the webhook configuration in GitHub.

 

In GitHub, go to your repository Setting page and select ‘Webhooks’. Click ‘Add Webhook’ and follow the instructions to complete this step;

Important: In multi-repository configurations, steps 1 to 5 will need to be repeated for each repository.

Syncing a Single Item

You may at times want to update or send a single Craft.io item to GitHub. This can be a new item that you created or one that you have recently updated. You can do this from the GitHub section in the item's right panel:

Important: 

  • Closing an item in Github will immediately release the item in Craft.io, and vice versa.

  • Releasing an item in Craft.io will close the item in GitHub on sync, and vice versa.

Modifying Integration Settings 

You can always return and update your configuration from the 3 dots integration menu:

You can also choose to view a detailed log of the last sync and disconnect the GitHub integration.

Did this answer your question?