How to set up the GitHub integration in Vaiz

The GitHub integration connects your repositories to Vaiz tasks. You can link pull requests, branches and commits to a task, see their activity right in the task, and create branches without leaving Vaiz. Vaiz can also link pull requests, branches and commits for you when they mention a task key such as APP-123.

Step 1. Connect GitHub to your space

Click the space icon in the top-left corner, select the space you want to connect, and choose App center.

In the App Center, click GitHub.

On the GitHub integration page, click Connect.

Review the setup information and click Confirm. You need to be an admin or owner of the GitHub organization you connect.

If you are not signed in to GitHub, you will be redirected to the GitHub sign-in page. Sign in to continue.

On GitHub, select the organization where you want to install the Vaiz app.

Choose which repositories Vaiz can access: All repositories or Only select repositories. Review the permissions and click Install.

GitHub redirects you back to Vaiz. Click Confirm to finish connecting the account.

If the connection is successful, you will see a confirmation message. Click Back to App to finish.

Step 2. Check the integration settings

After the connection is complete, the GitHub account appears on the integration page with the Connected status.

Below the account, the integration page shows the available features:

• Repositories: GitHub repositories available for linking to tasks. The list is synced from the GitHub app installation. To add or remove repositories, change the repository access in the GitHub app settings.
• PR Comments & Activity: comments and updates from linked pull requests appear in the Vaiz task.
• Task Activity to PRs: task status changes in Vaiz are posted as comments on linked pull requests.
• Auto-link by task key: pull requests, branches and commits that mention a task key are linked to the task automatically.
• Create Branches: create new branches in connected repositories directly from tasks.

PR Comments & Activity, Task Activity to PRs and Auto-link by task key are on by default. Use the toggle next to each feature to turn it off.

Step 3. Link pull requests, branches and commits to a task

After GitHub is connected, every task has a Repository field. Linked pull requests, branches and commits appear in this field.

To add a link, click + in the Repository field. In the window that opens:

1. Choose the repository. Repositories are grouped by provider, so if you also use GitLab, its projects are listed in a separate group.
2. Open the PR, Branch or Commit tab.
3. Start typing to search, then click the item you want to link.

Hover over a linked item to see its details. Click it to open it in GitHub, copy its link or name, or unlink it from the task.

Link automatically by task key

You don't have to link everything by hand. When Auto-link by task key is on, Vaiz looks for task keys such as APP-123 in:

• the title, description and branch name of a pull request;
• the name of a pushed branch;
• the messages of pushed commits.

If a key matches a task in your space, Vaiz links the pull request, branch or commit to that task. For example, a branch named APP-123-login-form or a commit message APP-123 Fix the login form is linked to task APP-123.

A few things to keep in mind:

• The key must belong to a project in this space. Keys are not case-sensitive.
• If a pull request mentions several tasks, it is linked to each of them.
• Closed pull requests are not linked automatically.
• Existing links are never removed by auto-link.

Step 4. Create a branch from a task

You can create a branch for a task without opening GitHub.

1. In the task, click + in the Repository field.
2. Open the Create branch tab.
3. Choose the repository and the base branch.
4. Check the branch name. By default, it is the task key, so the new branch is linked to the task.
5. Click Create.

The new branch is created in GitHub and linked to the task.

Step 5. Follow pull request activity

When PR Comments & Activity is on, the task shows what happens to its linked pull requests: when a pull request is opened, gets new commits, is marked as ready for review or as a draft, is merged, closed or reopened. Comments from the pull request also appear in the task.

When Task Activity to PRs is on, Vaiz posts a comment on each linked pull request when the task status changes, so reviewers can see the task progress on GitHub.

Step 6. Manage the integration

You can manage connected GitHub accounts from the GitHub page in the App Center.

• To add another account, click Connect another account and repeat the connection flow.
• To manage an existing connection, click the three-dot menu next to the connected account.

From this menu, you can open the GitHub settings or disconnect the account from the current Vaiz space.

If you select Manage on GitHub, you will be redirected to the GitHub installation settings. There, you can update repository access, suspend the installation or uninstall the Vaiz GitHub app.

If you disconnect the account, links already added to tasks stay in place, but they no longer receive status updates or comments.