Github

Description

Integration allows you to:

- receive in the comments to the card messages that contain links to the commit'y related to this card;

- automatically move cards to the selected column if a branch is created in the repository;

- automatically move the cards to the selected column if the branch related to the card merges into the specified repository branch;

- automatically move cards when opening or merging Pull Request;

- automatically move cards by Review events: `changes requested` and` approved`;

- automatically move cards by `deployment` events;

- automatically move the cards specified in the description by pull request;

- creating multiple integrations for one GitHub repository;

- adding a name for each integration to distinguish between integrations for the same repository;

- limiting the application of integration events to a specific space in Kaiten

Setup

GitHub repository setup

1. Open the menu. In the Spaces section, hover over the space whose events you want to integrate into your calendar. Click on the three dots to the right of the space name, then in the Space Settings drop-down menu

2. In the window that opens, go to the GitHub section. In the settings will be specified GitHub Secret and Webhook URL for your company. These parameters must be entered in the settings of your repository on GitHub

3. Go to GitHub. Section Settings → Webhooks → Add Webhooks.

   

4. In the window that opens, enter the GitHub Secret and Webhook URL from Kaiten. In the Which events would you like to trigger this webhook section, select the desired events.

Comments with links to commit’s in the cards

Install Webhook according to the steps above.

Now, if the commit’s will contain #XXX, where XXX is your card number, the link to commit will be added to the card as a comment.

To make a comment appear in several cards, add the necessary cards numbers separated by commas: #XXX,YYY,XXX (without spaces and additional #).

Automatic Card Movements

The card can be moved automatically: when a branch is created, in the name of which there is an ID of the card, when Pull Request is opened / merged, when Review events occur or when deployment occurs.

1. Configure the webhook as specified in GitHub repository setup;

2. Open the space settings (gear icon to the right of the name of the workspace. There are no icon if you are not the administrator of the space);

3. In the settings, go to GitHub;

4. Under the description of the webhook there is a section “Integration with repositories”, there click on the button “Create”;

5. The name of the repository is, for example, kaiten in the line https://github.com/kaiten-hq/kaiten

For branch created events, you need to specify a column to move.

For the rest of the events PR opened,PR merged, Review changes requested,Review approved it is necessary, in addition to the column, to indicate the branch to which the Pull Request will be opened.

Now, if you create a branch in your project with a name, for example, branch-XXXX, where XXXX is the id of your card, then the card will move to the column specified for the branch created event. How to call a branch - it does not matter, as long as there is an ID card there.

Moving Multiple Cards in One Pull Request

You need to make setup from the section “Automatic card movements”.

Now, if you specify additional cards in a special format in the description of the Pull Request, then they will be moved in accordance with the settings for the created branch.

Special format is a keyword and a list of ID cards separated by commas. In addition to the ID, you can specify a link to the card in full hq.kaiten.io/space/1/card/XXX or the abbreviated format /c/XXX.

Keywords close, closes, closed, fix, fixes, fixed, resolve, resolves, resolved

For example, if you specify in the description of the PR fixes: 1, 2, 3; resolved hq.kaiten.io/space/1/4, /c/5, 6, then the cards with ID from 1 to 6 will move.

Card Movement during Deployment

It is necessary to make setup from the section “Automatic card movements”.

Additionally, for the private repository, you must specify the “Personal Access Token”.

Creating a token:

1. In the upper right-hand corner of any page on GitHub, click on your profile icon, then click “Settings”;

2. On the left, in the sidebar, click “Developer settings;

3. On the left, in the sidebar, click “Personal access tokens”;

4. Click “Generate new token”;

5. Select access level repo;

6. Click “Generate token”;

7. Insert the resulting token into the “Personal Access Token” field.

If the owner of the token loses access rights to the repository, then deployment events will not be processed.

Upon successful deployment to the specified environment (in the settings of the “Environment” field), we analyze all the commits added after the previous deployment to the specified branch (the “Branch” field). We find commits that relate to pull requests merged into a branch and extract id cards from them. Further, we move all found not archived cards in the corresponding column.

Example of integration settings

On the example of a card with ID 100:

When creating a branch, for example, fix-branch100, the card will move to the “Work / To Do” column;

When you open a PR to the development branch, the card will move to the “Work / Doing” column;

After passing Review in the approved status, the card will move to the “Work / Approved” column;

After merging with the development branch, the card will move to the “Work / Done” column.

Action Draft PR opened for the integration with GitHub

1. New settings for draft-pr

2. Conversion from draft-pr to regular is now processed as opening PR