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 and uses them as classification targets when it processes each app session. You can enable one, the other, or both at the same time.

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 your organisation’s repositories
• A personal access token (PAT) with at least the repo scope

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 → Fine-grained tokens (recommended) or Tokens (classic). Click Generate new token.

   For a classic token, enable the repo scope. For a fine-grained token, grant Read-only access to Issues and Repository metadata for the repositories Meridian should monitor.

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

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

If GITHUB_REPOS is omitted, Meridian fetches open issues from all repositories in the organisation that your token can access.

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.

Troubleshooting

401 or 403 errors on startup

Check that your token has not expired and has the correct scopes. Classic tokens need the repo scope; fine-grained tokens need read access to Issues. 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 team IDs (comma-separated)
# LINEAR_TEAM_IDS=TEAM1,TEAM2

If LINEAR_TEAM_IDS is omitted, Meridian fetches open issues from all teams 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 IDs in Linear under Settings → Teams — each team has an identifier shown in its URL and settings page.

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.