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 product 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 Stories will be synced to a GitHub repository according to their label. 

Note: In a multi-repository configuration, every story in Craft.io must have a label assigned to it. A story 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 stories 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 stories instead. For more information about syncing a specific story, see ‘Sync a Single Story’ 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 stories by selected repositories, or all repositories at once.

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

  

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

  • All Product - Syncs the entire Craft.io product 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, ordered by their Epics. You can move them to different features 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 Story

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

Important: 

  • Closing a story in Github will immediately release the story in Craft.io, and vice versa.
  • Releasing a story in Craft.io will close the story 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?