• What is GitHub?
• What do I get?
• Getting Started
• GitHub Authentication
• Why do Flying Donut require write permissions to the GitHub
• Manual Configuration
• Commit Message
• User Identification
• GitHub Issues
• Import GitHub Issues
• Issues User Identification

GitHub is a powerful collaboration, code review, and code management for open source and private projects. GitHub offers online source code hosting for Git projects, with powerful collaboration, code review, and issue tracking.

With this integration, GitHub will post the commits and the commit comments to a Flying Donut project. You will be able to see which commit is part of which task (or card) with a quick link to the GitHub commit.

You will also be able to apply the Flying Donut workflow via the commit messages. For example you can may update the time left of a task to 5 hours from within the commit message by typing #1556 -left 5h.

Enabling integration with GitHub Issues allows you apply Scrum to your issues. All linked issues and milestones are tracked in real time and updates appear in both Flying Donut and GitHub.

1. Navigate to your project and locate its settings. If you have admin permissions, you will see the integrations tab. Click on the enable button to enable the GitHub integration. Only project administrators (or owners) are allowed to setup GitHub integration.

   

2. Click on the Details button to see the GitHub configuration details. You will see:

   • an option to login to GitHub and proceed with automatic GitHub configuration/integration.
   • an option to create endpoints to be used for manual configuration.

   We recommend the automatic configuration.

   

1. Login to GitHub. When setting up a GitHub integration for the first time, you will be presented with a GitHub consent page that lists the permissions that Flying Donut is requesting. If you are not signed in to GitHub, you will be asked to do so. Once you give the required consent you will be able to select the repository you want to link with the project.

   

2. Configure new repo. Once you have given the required consent you will be presented with a list of the GitHib repositories you have access to. Click on the Create Webhook button once you have selected the repository.

   

3. Linked. You are done. The project is linked with the repository. If you wish to undo then unlink the project and click on the Logout from GitHub button.

   

When setting up a GitHub integration for the first time, you will be presented with a GitHub consent page that lists the permissions that Flying Donut is requesting.

Unfortunately, the only way that Flying Donut can accees and configure of your public and private repositories is with GitHub's "repo" scope, which provides all of the other permissions listed above.

We don't use all of them. Of this list, the only permissions Flying Donut use are the ones to read repo data (to get a list of your public and private repositories) and the write permission to your webhooks on GitHub.

1. Generate a new Payload URL. If you wish to configure GitHub manually you click on the Generate a new Payload URL button.

   

2. Use the Key. Once you generate the key you will have the configuration options available to configure the GitHub webhook. Go through the GitHub instructions on how to setup webhooks for more details.

   

3. Setup webhook in GitHub. In GitHub, set up the project webhook to complete the integration. When setting up the required webhook paste the generated Payload URL and theSecret. Select application/json for the Content Type. Flying Donut also requires you to select the following individual events:

   1. Push
   2. Commit Comment

   

1. Card & Tasks. Once you have linked the Flying Donut project with a GitHub repository you will get updates on the latest commits on your cards and tasks. When clicking on the git hash you will be redirected to the GitHub commit page.

   

   

2. Commit Message. You just tag your commits with Card/Task IDs, and GitHub automatically comments on your card or task with the commit message. And, most importantly, you will be able to apply the Flying Donut workflow via the commit messages. The Card/Task IDs identifiers are the ones at the upper left #{id}

   

   Task. Flying Donut understands the following commands in the commit message in regards to the Task:

   • -todo: Move the task to To Do
   • -doing: Move task to Doing. Use it when a task is in Done and you need to move it back to Doing
   • -done: Move the task to Done
   • -left: Update the time left. Example of supported syntax is: -left 5h 20m or the equivalent -left 5:20
   • -spent: Aggregate the time spent. Example of supported syntax is: -spent 5h 20m or the equivalent -spent 5:20
   You can combine the -left and -spent to update the task in a single commit. For example: #532 -left 2h -spent 8hwill move the task to Doing, update the time left, and update the time spent. When using#{id} by default the task moves to Doing when in To Do.

   
   Card.

   • -done: Move the tasks of the card to Done. The card will move into Done state

   Examples
   If in a single commit you have multiple tasks that should be updated then you just add all of them in the commit message. An example of a commit message that could someone could use is:
   

   Refactored database for the needs of: #3224 -done #3236 -left 15h

   Or a more verbal one:
   

   #3224 is -done and I -spent 12h. Started working on #3236. I already -spent 3h but I it was underestimated. I think it has -left 15h

1. Make sure you have verified email. Flying Donut uses the email address you set in your local Git configuration to associate commits with your Flying Donut account. To see the email address you have in your local git type:
   

   $ git config user.email # your_email@example.com

   You have to have your_email@example.com added and verified in your Flying Donut account.

   For detailed description on how to configure your commit email in GitHub read Setting your email in Git

2. Add your email to your account. In case the git email is not added to your Flying Donut account then add it in the account settings and verify it. Then you will be able to apply the Flying Donut workflow via the commit messages.

When linking a GitHub repository and Flying Donut project, we create custom labels that will give you a reflection on what is going on in Flying Donut. All labels created by Flying Donut have an fd: prefix.

Linked cards will have an indication at the top left. Clicking at the GitHub issue number will open up a new tab with the issue at GitHub. A card linked to a GitHub issue displays the labels of the issue in readonly mode.

Setting any of the approval statuses (e.g. approve) of a linked cards will close the issue in GitHub.

When you include an auto-linked backlog bucket you will have an indication next to its name. Clicking at the link will open up a new tab with the issues in GitHub.

Once you have linked a project will have the option to import existing GitHub issues to Flying Donut.

You will be presented with all the issues in GitHub sorted by date. You may select individual issues one by one all at once with a click at the check box at the left top.

At the bottom of the page you have the option to move to the next or previous page and continue with the selection of issues. Then import issues you selected selected.

At this point we don't provide user identification for the GitHub Issues.