EnglishENPolskiPL
Start free
Documentation

Connect an issue tracker so people can log time against issues

Connect Jira, GitHub, Linear or Asana, log hours against a real issue, and know what does and doesn't sync

Issue-tracker integrations exist for one reason: so people can attach a real tracker issue to a time entry — found by a search picker, not typed from memory. SquadBear speaks to four trackers: Jira, GitHub, Linear and Asana. Nothing is mirrored or synced; an issue only becomes a work item the moment someone logs hours against it.

Connect a tracker (admin)

Admin → Integrations (admin only) shows one card per tracker. Each card has a Connect button that opens a short credential form. SquadBear verifies the credentials against the tracker before saving — wrong credentials come back as a rejection, not a silent failure — and the token is always stored encrypted.

What each tracker needs:

  • Jira — the Site URL (https://yourcompany.atlassian.net), the email your Atlassian API token belongs to, and an API token (create one at id.atlassian.com under Security → API tokens).
  • GitHub — the organization login whose issues you want to search, and a fine-grained personal access token with read access to that organization's issues (GitHub → Settings → Developer settings → Personal access tokens → Fine-grained).
  • Linear — a single API key (a Linear personal API key, from your Linear API settings). Linear needs nothing else — the key is bound to its own workspace.
  • Asana — a personal access token (from your Asana developer settings). Asana is two-step: paste the token and, if it can see more than one workspace, SquadBear asks which workspace to bind the connection to before it finishes. A token that sees exactly one workspace connects in a single step.

Once a tracker is connected its card shows what it's connected to; Disconnect on the same card removes the stored credentials.

Log time against an issue

On My week, the Work items panel's Search tab searches the connected tracker as you type (3+ characters, debounced). How search behaves per tracker:

  • Jira — a key-shaped query (PLAT-123) is looked up directly; anything else matches issue summaries updated in the last 90 days.
  • GitHub — full-text search across the organization's issues (pull requests are filtered out). Results are keyed owner/repo#123.
  • Linear — Linear's own full-text issue search. Results carry the ENG-123 badge.
  • Asana — Asana's typeahead (its full search endpoint is a paid-tier feature). Asana work items have no key, so results show just the work item title — no key badge.

Picking an issue drops it onto the grid as a work item named after the issue, and logs your hours against it. The first time anyone logs against an issue, SquadBear creates one work item for it behind the scenes; logging against that same issue again — this week, next month, from anyone on the project — reuses that one work item, so per-issue totals accumulate instead of splitting across duplicates.

For Jira, if the tracker is unreachable or a key doesn't turn up in search, typing a key still offers "use PLAT-999 as issue key" — logging never blocks on the tracker being up. Linear and Asana issues must be picked from search results: Linear's ENG-123 key changes when an issue moves team, and Asana has no key at all, so both are logged by their stable id, which you can't type from memory.

Scope a project to a tracker

Once a tracker is connected, a project's create/edit form gains an issue-tracker scope — a provider plus a container — that narrows that project's picker to just its own issues. The container means something different per tracker:

  • Jira — a project key, e.g. PLAT.
  • GitHub — an owner/repo, e.g. northlake/platform.
  • Linear — a team key, e.g. ENG.
  • Asana — a project gid (the number from the project's URL).

A project with no scope searches the whole connected tracker.

The Work items panel's Assigned tab lists issues the tracker has assigned to you — but only once your tracker account is linked to your employee record. Linking is self-serve through a connected agent (or an admin can link it for you); until then the tab shows a per-tracker "Link your account" prompt. The identity each tracker matches on is its own: a Jira/Atlassian account id, a GitHub login, a Linear user id, or an Asana user gid.

What stays in sync

Only an issue's key (where it has one) and its cached title come from the tracker, refreshed the next time someone logs against it. Nothing flows the other way — no worklog is ever written back, and status and assignee aren't stored beyond the live query the Assigned tab runs each time you open it. A tracker-mirrored work item can't be renamed (it mirrors the issue), though its time category stays editable like any work item. Disconnecting hides the pickers and Assigned tab; every hour already logged keeps its issue reference and stays on the timesheet exactly as logged.

Troubleshooting

  • "Rejected the credentials / token" — the stored credentials no longer work (revoked token, changed password, removed access). Open the tracker's card and reconnect with a fresh token; existing entries are untouched.
  • "Rate limit hit; try again shortly" — the tracker is throttling requests (GitHub's issue search is the most tightly capped, and the limit is shared across everyone in the workspace). Wait a few seconds and search again; SquadBear never auto-retries, so nothing is queued up behind it.
  • Search returns nothing for a scoped project — check the project's container matches the tracker exactly (a Jira project key, an owner/repo, a Linear team key, an Asana project gid). A GitHub organization typo surfaces here too, as empty results.

Worked example

Northlake connects GitHub with the northlake org and a fine-grained token, then sets Platform v2's scope to northlake/platform. Backend developer Tomasz opens My week, searches "rate limit" in the Work items panel, picks issue northlake/platform#212 and logs 3h against it. Logging against that same issue next week lands on the same work item, so its running total keeps growing rather than starting over.