Connect to GitHub

Install the Taskie GitHub App on your team's repositories so pull requests, branches, commits and issues that mention a task ID show up in that task's Development section, and merging a pull request with a closing phrase completes the task.

The GitHub connection brings development work next to your tasks. A workspace admin installs the Taskie GitHub App once; from then on, every pull request, issue, branch or commit that mentions a task ID such as TASK-12 is listed in that task's Development section, and merging a pull request that contains a closing phrase completes the task.

This connection exists only at the workspace level and works for every member; there is no personal GitHub connection. Links are only ever made inside the workspace the connection belongs to, so the same ID in another workspace is never tied to these repositories.

Before you start

App Center
Find GitHub in the App Center, under Development & DevOps
  • You need to be an owner or admin of the Taskie workspace.
  • On GitHub, you need permission to install apps on the account or organization. If you are a regular member of the organization, GitHub sends your request to the organization owners instead of installing.
  • The GitHub connection counts as one of the workspace's integrations, and how many you can have depends on your plan. The app page shows how much of that limit you've used.
  • Taskie doesn't open your code files. From the events of the repositories you grant the app, it only uses pull request and issue titles and descriptions, branch names, commit messages and workflow run results.

Install the GitHub App

Taskie connects to GitHub through a GitHub App. You decide on GitHub which repositories the app can see, and you don't need to create any webhooks by hand.

GitHub card in the App Center
The GitHub card in the App Center opens the connection page
  1. From settings, open the App Center and click the GitHub card.
  2. On the app page, choose the Workspace tab and, under Create a workspace connection, click Connect.
  3. On GitHub, pick the account or organization that holds the repositories, choose whether the app can access all repositories or only selected ones, and confirm the installation.
  4. GitHub asks you to sign in once. This lets Taskie check that the installation really belongs to your account.
  5. You return to the GitHub page in the App Center and the connection card appears. The repository list is fetched in the background and shows up under Manage a moment later.

If the connection doesn't complete: if you are a member of the organization but not an owner, you'll see "Your request was sent to the organization owners. Once they approve it, click Connect again." If the app is already installed on the organization, only an owner of that organization can connect the existing installation. Each GitHub installation can be connected to only one Taskie workspace.

Manage the connection and its health

The connection card on the app page shows its state as Working, Needs attention or Disconnected, explains the problem (for example, the app was suspended or removed on GitHub) and shows the time of the last event. Manage opens a sheet with these sections:

  • Repositories: the repositories the app can see. You add or remove repositories in the app's settings on GitHub, and Taskie follows that list automatically. If a change seems late, click Resync.
  • What Taskie listens for: switches for Pull requests, Issues, Pipelines and workflow runs, Branch and commit pushes, Link tasks mentioned by ID and Move and complete tasks. Turning one off makes Taskie skip that kind of event or behavior.
  • Rules: four optional rules for comments and task completion, explained below.
  • Recent events: the latest events received from GitHub, each with its status (Processed, Skipped, Failed and so on) and the reason it was skipped. Put a failed event back in the queue with Retry; redelivering an event from the app's settings on GitHub also works.

Automatic linking with the task ID

Just write the task ID in your GitHub work. Taskie finds it in the branch name, the commit message, the pull request title and description, and the issue title and description, and links that item to the task. These forms are accepted:

  • TASK-12 — the task's display ID; lowercase (task-12) works too.
  • #TASK-12 or CU-TASK-12 — the same ID with a prefix.
  • IDs typed with non-Latin digits are recognized as well.

For example, a branch named feature/TASK-12-login or a commit with the message TASK-12 Fix login redirect is linked to task TASK-12 automatically. The ID must not be glued to a letter or digit before it, so xTASK-12 isn't read. Automatic linking only works for repositories the app can access, and it only finds tasks in the same workspace.

The task's Development section

Task details window
The task details window. Once GitHub is connected, a Development button joins sections such as Subtasks and Meetings here

When the workspace has an active GitHub or GitLab connection, each task window shows a Development button with the number of linked items. The section groups them as Pull & merge requests, Branches, Commits, Issues and Other links. The latest GitHub Actions result is shown next to a linked pull request or branch.

  • Work on this task: copy-ready strings with the task ID: Branch name, a New branch command (git checkout -b …), Commit message, and the Close on merge phrase (Fixes TASK-12).
  • Add link: paste the URL of a GitHub pull request, issue or commit to link it to the task by hand. Remove any link with Remove link.
  • Create branch and Create issue: on one of the connected repositories, create a branch with the suggested name from the repository's default branch, or an issue titled after the task. The new item is linked to the task right away, and a link back to the task is added at the end of the issue description.

Adding and removing links and creating branches or issues are available to people who can edit in that project. Branches and issues can only be created on repositories listed in the connection's Manage sheet.

Completing and moving tasks automatically

A plain mention of the ID only links the task. A task is completed automatically when a pull request is merged and its title or description has the task ID right after one of these closing keywords:

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

Case doesn't matter, and you can put a colon after the keyword (Fixes: TASK-12). You can list several tasks with commas or "and": Closes TASK-12, TASK-15 and TASK-18. Closing a pull request without merging it doesn't complete anything. A completed task moves to the project's final status.

Two optional rules under Rules widen this behavior. Both are off by default:

  • Complete tasks named after a closing keyword in a push to the default branch: a commit with the message Fixes TASK-12 pushed straight to the repository's default branch completes the task.
  • Complete a task when a merged branch is named after it, even without a closing keyword: merging a pull request from a branch such as TASK-12-login is enough.

Move a task with brackets

Write a status name in brackets right after the ID and the task moves to that status, for example TASK-12[In Review]. This is read in branch names, commit messages, and pull request and issue titles and descriptions. Don't put a space between the ID and the brackets. The name must match one of the project's statuses, but case doesn't matter; if no status has that name, the task is only linked.

Important: completing and moving tasks only happens while the Move and complete tasks switch is on. The project's own rules still apply: if the task is still waiting on another task, or the project's status workflow doesn't allow the move, the task stays where it is and only the link is recorded.

What Taskie sends to GitHub

  • One comment per link: the first time Taskie links a pull request or issue to a task, it leaves a short comment with the task ID and a link to the task. The rule Comment on a pull request, merge request or issue when Taskie links it to a task controls this and is on by default.
  • Task title: left out of that comment by default, because repositories can be public. Turn on Include the task title in that comment to add it.
  • New branches and issues: only when you create them yourself from the Development section.

Taskie changes nothing else on GitHub. For example, completing a task in Taskie doesn't close the pull request or issue.

Task activity and notifications

Added and removed links and state changes of a linked pull request or issue are recorded in the task's activity, labelled GitHub. The task's assignee and creator are also notified when a workflow run fails on a linked pull request or branch, when a linked issue is opened (except issues you created from Taskie), and when a merge completes the task. Choose how these notifications reach you in Set up notifications and reminders.

Disconnect

If the app is suspended or uninstalled on GitHub, the connection card in the App Center says so. To disconnect from Taskie's side, click Disconnect on the card; only a workspace owner or admin has this button. Disconnecting uninstalls the Taskie app from your GitHub account or organization and stops events, but the links already recorded on tasks stay. Active workspace connections are also listed in workspace settings, on the Integrations tab.

Common mistakes

  • Writing "Fixes" only in a commit message and expecting completion. The closing phrase must be in the title or description of the merged pull request, unless you turned on the default-branch push rule.
  • Merging a branch that is only named after the task. Without a closing keyword the task is just linked, unless the branch-name rule is on.
  • Putting a space between the ID and the status brackets. The correct form is TASK-12[Done].
  • Expecting links from a repository the app can't access. GitHub doesn't send events for it; add the repository in the app's settings on GitHub.

Next step: if your team also uses GitLab, see Connect to GitLab; the same IDs and the same Development section work there. To connect other systems, review Public API and webhooks.

Was this article helpful?