> ## Documentation Index
> Fetch the complete documentation index at: https://meridiona-mintlify-e1e3e247.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Tabs>
  <Tab title="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](https://cli.github.com/) 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`.

    <Tabs>
      <Tab title="With gh CLI (recommended)">
        <Steps>
          <Step title="Install and authenticate gh">
            Install the [GitHub CLI](https://cli.github.com/) and run:

            ```bash theme={null}
            gh auth login
            ```
          </Step>

          <Step title="Run meridian setup">
            ```bash theme={null}
            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.
          </Step>
        </Steps>
      </Tab>

      <Tab title="With a personal access token">
        <Steps>
          <Step title="Generate a classic token">
            Go to [github.com/settings/tokens/new](https://github.com/settings/tokens/new) and create a **classic** personal access token.
          </Step>

          <Step title="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
          </Step>

          <Step title="Copy the token">
            Copy the token value before navigating away — GitHub only shows it once.
          </Step>

          <Step title="Find your Project node IDs">
            Each Project v2 has a node ID like `PVT_kwHO...`. List yours with:

            ```bash theme={null}
            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.
          </Step>
        </Steps>
      </Tab>
    </Tabs>

    ## 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:

    ```bash theme={null}
    meridian config edit
    ```

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

    ```bash theme={null}
    # ~/.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

    <Steps>
      <Step title="Restart the daemon">
        ```bash theme={null}
        meridian restart
        ```
      </Step>

      <Step title="Check the connection">
        ```bash theme={null}
        meridian doctor
        ```

        Look for `github: connected` in the output. Meridian reports the connection status for every configured integration.
      </Step>

      <Step title="Confirm issues were fetched">
        ```bash theme={null}
        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`.
      </Step>
    </Steps>

    ## Pick different projects later

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

    ```bash theme={null}
    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

    <AccordionGroup>
      <Accordion title="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](https://github.com/settings/tokens).
      </Accordion>

      <Accordion title="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.
      </Accordion>

      <Accordion title="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.
      </Accordion>

      <Accordion title="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.
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="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

    <Steps>
      <Step title="Open Linear Settings">
        Click your avatar in the bottom-left corner of the Linear app, then choose **Settings**.
      </Step>

      <Step title="Navigate to API">
        In the Settings sidebar, click **API** under the **My account** section.
      </Step>

      <Step title="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**.
      </Step>

      <Step title="Copy the key">
        Copy the key value immediately — Linear only shows it once. It starts with `lin_api_`.
      </Step>
    </Steps>

    ## Set environment variables

    Open the Meridian env file:

    ```bash theme={null}
    meridian config edit
    ```

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

    ```bash theme={null}
    # ~/.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

    <Steps>
      <Step title="Restart the daemon">
        ```bash theme={null}
        meridian restart
        ```
      </Step>

      <Step title="Check the connection">
        ```bash theme={null}
        meridian doctor
        ```

        Meridian reports connection status for each configured integration. Look for `linear: connected`.
      </Step>

      <Step title="Confirm issues were fetched">
        ```bash theme={null}
        sqlite3 ~/.meridian/meridian.db \
          "SELECT task_key, title FROM pm_tasks WHERE provider='linear' LIMIT 10;"
        ```
      </Step>
    </Steps>

    ## Filter to specific teams

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

    ```bash theme={null}
    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

    <AccordionGroup>
      <Accordion title="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.
      </Accordion>

      <Accordion title="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.
      </Accordion>

      <Accordion title="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.
      </Accordion>
    </AccordionGroup>
  </Tab>
</Tabs>