Connect Meridian to GitHub Issues or Linear Issues

Pull open GitHub or Linear issues into Meridian so coding sessions are automatically classified against the right tickets, with no manual tracking needed.

Meridian supports two additional issue trackers alongside Jira: GitHub Issues and Linear. Both work the same way under the hood — Meridian fetches your open issues into the local pm_tasks table, uses them as classification targets when it processes each app session, and once classification matches a session to an issue it can also draft a worklog against that issue. You can enable one, the other, or both at the same time.

Neither GitHub nor Linear exposes a native time-tracking / worklog API, so on these trackers Meridian records a worklog as a structured comment on the matched issue: a single Markdown line of the form **⏱ Worklog — 1h 30m** · 2026-06-02 09:00, followed by the synthesised narrative of what you did, followed by an HTML-comment machine marker (meridian-worklog v1 …) carrying the exact UTC window and seconds so the entry can be parsed back out later. Worklogs are still gated by approval in the dashboard’s Worklogs view — the same draft → approve → post pipeline as Jira, just with a different final hop. See Review and approve worklogs.

GitHub Issues

What Meridian does with GitHub Issues

Meridian fetches open issues from your GitHub organisation’s repositories using the GitHub REST API. Each issue is stored in pm_tasks alongside any Jira or Linear issues you’ve configured. When Meridian classifies a coding session — say, an hour in VS Code on a feature branch — it matches that work against your open issues and writes a ticket_links row with the best-matching issue key.

Prerequisites

• A GitHub account with access to the organisation (or personal) issues you want to track
• A personal access token (PAT) with write access to issue comments — Meridian needs this to post worklog comments after you approve them

Create a GitHub personal access token

1. Open GitHub Settings

   Click your avatar in the top-right corner of GitHub, then choose Settings.

2. Navigate to Developer settings

   Scroll to the bottom of the left sidebar and click Developer settings.

3. Generate a new token

   Select Personal access tokens → Tokens (classic) or Fine-grained tokens. Click Generate new token.

   • Classic token (simplest) — enable the repo scope. This single scope covers both reading issues and posting worklog comments, on personal and org-owned repos.
   • Fine-grained token — grant Issues: Read and write on every repository Meridian should monitor (read-only is not enough; Meridian needs write access to add the worklog comment when you approve a draft).
4. Copy the token

   Copy the token value before navigating away — GitHub only shows it once.

Set environment variables

Open the Meridian env file:

meridian config edit

Add the GitHub block to ~/.meridian/.env:

# ~/.meridian/.env

GITHUB_TOKEN=ghp_your_personal_access_token
GITHUB_ORG=your-org-name   # org slug OR your own username

# Optional: limit to specific repos (comma-separated owner/repo pairs)
# GITHUB_REPOS=your-org/api,your-org/web

GITHUB_ORG is the issue owner Meridian should sync — an organisation slug or your own GitHub username (for personal repos). Meridian fetches open issues assigned to you under that owner. If GITHUB_REPOS is omitted, every repository under the owner that your token can read is included.

Apply and verify

1. Restart the daemon

   meridian restart
   
2. Check the connection

   meridian doctor
   

   Look for github: connected in the output. Meridian reports the connection status for every configured integration.

3. Confirm issues were fetched

   sqlite3 ~/.meridian/meridian.db \
     "SELECT task_key, title FROM pm_tasks WHERE provider='github' LIMIT 10;"
   

Filter to specific repositories

Set GITHUB_REPOS to a comma-separated list of owner/repo strings:

GITHUB_REPOS=myorg/api,myorg/web,myorg/infra

Only open issues from those repositories will be pulled into pm_tasks. This is useful when your organisation has many repositories but you only actively work in a subset.

What “posting a worklog” means on GitHub

GitHub has no native time-tracking API, so when you approve a worklog draft Meridian posts it as a comment on the matched issue via POST /repos/{owner}/{repo}/issues/{number}/comments. The comment looks like:

**⏱ Worklog — 1h 30m** · 2026-06-02 09:00

Wired the new worklog provider router and migrated existing rows to default to `jira`. Wrote the comment formatter and idempotency check.

<!-- meridian-worklog v1 window=2026-06-02T09:00:00Z/2026-06-02T10:00:00Z seconds=5400 -->

In your tracker you will see:

• A new comment on the issue authored by the token’s user, with the time-spent line and the synthesised narrative.
• The same comment surfaced on any Project (v2) board the issue belongs to — Project cards already show issue comments, so no extra setup is needed.
• A hidden machine marker on the last line that Meridian (and any other tool) can grep for to reconstruct the exact window and seconds later. Worklogs are idempotent on (task_key, window_start, window_end) — re-running the pipeline never double-posts.

The same repo (classic) or Issues: Read and write (fine-grained) scope you configured above is all that’s needed — no separate Projects scope is required.

Troubleshooting

401 or 403 errors on startup, or when a worklog tries to post

Check that your token has not expired and has the correct scopes. Classic tokens need the repo scope; fine-grained tokens need Issues: Read and write (read-only will let issues sync but worklog comments will fail with 403). Regenerate the token in GitHub Settings if needed.

pm_tasks is empty for GitHub

Confirm that GITHUB_ORG matches your organisation’s login name exactly (case-sensitive). If GITHUB_REPOS is set, verify each entry uses the full owner/repo format. Your token must have access to at least one repository in the org.

meridian doctor shows github: not configured

Both GITHUB_TOKEN and GITHUB_ORG are required. Run meridian config edit and confirm neither is commented out.

Linear

What Meridian does with Linear

Meridian fetches your open Linear issues via the Linear GraphQL API and stores them in pm_tasks. Session classification then uses these issues as candidates — when you spend time in a code editor or design tool, Meridian links that session to the most relevant Linear issue it can find.

Prerequisites

• A Linear account with access to one or more teams
• A Linear API key

Create a Linear API key

1. Open Linear Settings

   Click your avatar in the bottom-left corner of the Linear app, then choose Settings.

2. Navigate to API

   In the Settings sidebar, click API under the My account section.

3. Create a personal API key

   Under Personal API keys, click Create key. Give it a descriptive label such as meridian-local and click Create key.

4. Copy the key

   Copy the key value immediately — Linear only shows it once. It starts with lin_api_.

Set environment variables

Open the Meridian env file:

meridian config edit

Add the Linear block to ~/.meridian/.env:

# ~/.meridian/.env

LINEAR_API_KEY=lin_api_your_key_here

# Optional: restrict to specific teams (comma-separated team keys or ids)
# LINEAR_TEAM_IDS=ENG,DESIGN

Meridian sends the key raw in Linear’s Authorization header — there is no Bearer prefix (that prefix is for OAuth tokens; personal API keys go in as-is). If LINEAR_TEAM_IDS is omitted, Meridian fetches the issues assigned to you across every team your account belongs to.

Apply and verify

1. Restart the daemon

   meridian restart
   
2. Check the connection

   meridian doctor
   

   Meridian reports connection status for each configured integration. Look for linear: connected.

3. Confirm issues were fetched

   sqlite3 ~/.meridian/meridian.db \
     "SELECT task_key, title FROM pm_tasks WHERE provider='linear' LIMIT 10;"
   

Filter to specific teams

Set LINEAR_TEAM_IDS to a comma-separated list of team identifiers:

LINEAR_TEAM_IDS=ENG,DESIGN

Only issues belonging to those teams will be pulled into pm_tasks. Find your team identifiers in Linear under Settings → Teams — each team has a short key (e.g. ENG) and an internal id; either works.

What “posting a worklog” means on Linear

Linear has no worklog, time-entry, or “time spent” field in its GraphQL schema. So when you approve a worklog draft, Meridian creates a structured comment on the matched issue via the commentCreate mutation:

mutation {
  commentCreate(input: { issueId: "<issue-uuid>", body: "**⏱ Worklog — 1h 30m** · …" }) {
    success
    comment { id url }
  }
}

Meridian first resolves the issue UUID from its human identifier (e.g. ENG-123) and then posts the comment. In Linear you will see:

• A new comment on the issue authored by the API key’s user, with the ⏱ Worklog — 1h 30m time-spent line followed by the synthesised narrative.
• The comment counts toward Linear’s issue activity feed and is visible in every view that surfaces comments (issue detail, Inbox, Slack mirror if you have it enabled).
• A hidden machine marker on the last line carrying the exact UTC window and seconds, so the entry can be parsed back out programmatically. Worklogs are idempotent on (task_key, window_start, window_end) — re-running the pipeline never double-posts.

The personal API key you configured above is the only credential required. Meridian uses the key’s viewer (the user who created it) as the comment author, so worklog comments are attributed to you.

Troubleshooting

Authentication errors on startup

Confirm that LINEAR_API_KEY starts with lin_api_ and has not been revoked. Regenerate the key in Linear Settings → API if needed.

pm_tasks is empty for Linear

Check that your account is a member of at least one team with open issues. If LINEAR_TEAM_IDS is set, verify the IDs match the identifiers shown in Linear Settings — they are case-sensitive.

meridian doctor shows linear: not configured

LINEAR_API_KEY is the only required variable for Linear. Run meridian config edit and confirm it is present and uncommented.