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 reads the GitHub Projects (v2) you select and ingests the open issues assigned to you in each one via the GraphQL API. Each issue is stored in pm_tasks alongside any Jira or Linear tasks you’ve configured, with its Project Status field (Todo / In Progress / Done) mapped to Meridian’s status_category so it shows in the correct dashboard column. When Meridian classifies a coding session — say, an hour in VS Code on a feature branch — it matches that work against these tasks and writes a ticket_links row with the best-matching issue key.

Use this connector if you track work in GitHub Projects (boards) rather than only on Issues alone. You pick which projects to sync at install time, so personal projects, org projects, or both can be combined.

Prerequisites

• A GitHub account with access to at least one Project (v2) containing issues assigned to you
• Either the gh CLI installed and authenticated (recommended), or a personal access token (PAT) with the repo, read:org, and read:project scopes

Get a token

The easiest path is to let meridian setup reuse the gh CLI’s existing browser login — no PAT to manage. Fall back to a PAT only if you can’t install gh.

With gh CLI (recommended)

1. Install and authenticate gh

   Install the GitHub CLI and run:

   gh auth login
   
2. Run meridian setup

   meridian setup
   

   When the installer reaches the GitHub step it will:

   1. Detect your gh login and, if needed, open the browser to grant the extra read:project scope.
   2. Call gh auth token and write the result to GITHUB_TOKEN in ~/.meridian/.env.
   3. List your personal and organisation Projects and prompt you to pick which ones to sync. The selected node IDs are saved to GITHUB_PROJECT_IDS.

   No PAT is ever created.

With a personal access token

1. Generate a classic token

   Go to github.com/settings/tokens/new and create a classic personal access token.

2. Enable the required scopes

   Meridian needs three scopes:

   • repo — post worklog and task-update comments on issues
   • read:org — list the organisations you belong to
   • read:project — read the Projects v2 boards and their items
3. Copy the token

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

4. Find your Project node IDs

   Each Project v2 has a node ID like PVT_kwHO.... List yours with:

   gh api graphql -f query='{
     viewer {
       projectsV2(first: 10) { nodes { id title } }
       organizations(first: 10) {
         nodes { login projectsV2(first: 10) { nodes { id title } } }
       }
     }
   }'
   

   Or open the project in GitHub and copy the ID from the URL via the API explorer.

Set environment variables

If you ran meridian setup with gh available, GITHUB_TOKEN and GITHUB_PROJECT_IDS are already written for you. To configure them manually, open the env file:

meridian config edit

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

# ~/.meridian/.env

GITHUB_TOKEN=ghp_your_personal_access_token
GITHUB_PROJECT_IDS=PVT_xxx,PVT_yyy

GITHUB_PROJECT_IDS is a comma-separated list of Projects v2 node IDs. If it is empty, no GitHub tasks are synced — Meridian needs an explicit project list (there is no longer an “all repos in an org” mode).

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, status_category FROM pm_tasks WHERE provider='github' LIMIT 10;"
   

   The status_category column reflects each issue’s Project Status field — todo, in_progress, or done.

Pick different projects later

Re-run meridian setup to bring the project picker back up, or edit GITHUB_PROJECT_IDS directly:

GITHUB_PROJECT_IDS=PVT_kwHOAB123,PVT_kwHOCD456

Only issues that appear on those project boards and are assigned to you are pulled into pm_tasks. This is the supported way to scope which repositories’ work Meridian sees.

Troubleshooting

401 or 403 errors on startup

Check that your token has not expired and has all three scopes: repo, read:org, read:project. If you’re using a gh CLI token, re-run gh auth refresh -h github.com -s read:project to add the projects scope. PATs can be regenerated at github.com/settings/tokens.

pm_tasks is empty for GitHub

Confirm that at least one entry in GITHUB_PROJECT_IDS is a valid Projects v2 node ID (they start with PVT_) and that the project contains issues assigned to your account. Re-run meridian setup to use the interactive picker, or list available IDs with the gh api graphql query shown above.

meridian doctor shows github: not configured

GITHUB_TOKEN is the only strictly required variable, but without GITHUB_PROJECT_IDS no tasks will sync. Run meridian config edit and confirm both are present and uncommented.

Issues show up in the wrong dashboard column

Meridian maps the Project’s Status field to status_category. Make sure each issue has a Status set on the board — items with no Status default to todo. The exact option names (Todo, In Progress, Done) are matched case-insensitively.

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.