---
title: Connect an issue tracker so people can log time against issues
description: Connect Jira, GitHub, Linear or Asana, log hours against a real issue, and see which fields the tracker owns
order: 2
---

A tracker connection lets people attach a **Jira**, **GitHub**, **Linear** or **Asana** issue to a
time entry. Nothing syncs: an issue becomes a work item the first time someone logs hours against
it.

## Connect a tracker (admin)

**Workspace settings → Issue trackers** (admin only) lists one row per tracker. **Verify &
connect** calls the tracker before anything is written: a rejected credential fails the connect
and nothing is stored, and a token that passes is stored encrypted.

| Tracker | Credentials | Search | Issue scope |
| --- | --- | --- | --- |
| **Jira** | Site URL, the token's email, an API token from id.atlassian.com | Keys resolve directly in one lookup; other terms search summaries without an age cutoff | Project key, `PLAT` |
| **GitHub** | Organization login, fine-grained token that can read its issues | Full text over the organization's issues, pull requests filtered; keys read `owner/repo#123` | `owner/repo` |
| **Linear** | API key, bound to its own workspace | Full-text search | Team key, `ENG` |
| **Asana** | Personal access token; pick a workspace when the token sees several | Typeahead over titles; full search is a paid tier | Project gid, from its URL |

## Log time against an issue

Open **Add work item** from My week or My day. Recent items appear immediately. Search
starts at 3 characters after a short debounce; choose **Source** to query one tracker,
or **Filters → Project** to narrow the project context.

A saved issue can be selected directly. For an issue you have never logged against,
choose a project, add the temporary row, then enter time. The first log creates one work
item keyed on project, provider and issue id; later logs reuse it. Searching and selecting
alone create no work items or empty time entries.

Jira accepts exact keys such as `PLAT-999`. Saved tracker work remains searchable even
when its connection fails. An unavailable tracker is named alongside any successful
results; it is never presented as a successful empty search. Searches are rate-limited
per workspace and tracker and are not automatically retried or queued. Results are capped
at 20; narrow the source, project or text when necessary. SquadBear-only results offer
**Load more** when another page exists.

## Scope a project to a tracker

The project form under **Workspace settings → Projects** carries **Issue source** (the provider)
and **Issue scope** (the container from the table above - Northlake pins **Platform v2** to
`northlake/platform`). A scope narrows the picker to that container's issues and must match it
exactly, or the picker returns nothing; with no scope it searches the whole tracker. With a second
tracker connected the picker carries a **Source** select, so a GitHub issue stays reachable
from a project pinned to Jira.

## Link your account

Link your tracker identity under **My settings → Connected accounts**. Search results can
then identify issues assigned to you when the tracker provides assignee information.
The picker has no separate Assigned tab; the source and project filters narrow discovery.

## What the tracker owns

A work item stores the issue reference and title on its first log. No worklog is written
back to the tracker. Assignment is live discovery information, not a synchronized local
catalog. An issue-backed work item cannot be renamed, though its time category stays
editable. Disconnecting leaves recorded hours and saved issue references intact.

> [!AGENT]
> Search GitHub for issues about the rate limiter and log 3 hours against the one I pick for today.

## Related

- [Log your first week of time](/docs/time/quickstart/)
- [Timesheet mechanics](/docs/time/timesheets/)
- [Connect Claude to SquadBear](/docs/getting-started/connect-an-agent/)