From 2924565fbb7ae4ef316ca6ea9fdf474c18e4e48d Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 9 Jun 2026 07:13:03 +0000 Subject: [PATCH] docs: update GitHub integration for Projects v2 + gh CLI auth --- configuration.mdx | 7 +- guides/github-linear.mdx | 121 +++++++++++++++++++--------- reference/environment-variables.mdx | 9 +-- 3 files changed, 92 insertions(+), 45 deletions(-) diff --git a/configuration.mdx b/configuration.mdx index 9a81ab1..8c1dc57 100644 --- a/configuration.mdx +++ b/configuration.mdx @@ -70,13 +70,12 @@ All three credential variables are required to enable the Jira connector. `JIRA_ ### GitHub -Both credential variables are required to enable the GitHub connector. `GITHUB_REPOS` is optional — omitting it covers all repositories in your org. +`GITHUB_TOKEN` enables the GitHub connector; `GITHUB_PROJECT_IDS` picks which Projects (v2) boards Meridian reads. Run `meridian setup` to obtain the token from the `gh` CLI and choose projects interactively. | Variable | Default | Description | |---|---|---| -| `GITHUB_TOKEN` | _(none)_ | A GitHub personal access token with `repo` scope. | -| `GITHUB_ORG` | _(none)_ | Your GitHub organisation name. | -| `GITHUB_REPOS` | _(all org repos)_ | Comma-separated list of `org/repo` slugs to scope issue lookups, e.g. `your-org/api,your-org/web`. Leave empty to search all org repos. | +| `GITHUB_TOKEN` | _(none)_ | A GitHub OAuth token (from `gh auth token`) or a classic PAT with the `repo`, `read:org`, and `read:project` scopes. | +| `GITHUB_PROJECT_IDS` | _(none — no sync)_ | Comma-separated GitHub Projects v2 node IDs (each starts with `PVT_`), e.g. `PVT_kwHOAB123,PVT_kwHOCD456`. | ### Linear diff --git a/guides/github-linear.mdx b/guides/github-linear.mdx index f93d1c6..3ae1f58 100644 --- a/guides/github-linear.mdx +++ b/guides/github-linear.mdx @@ -10,35 +10,82 @@ Meridian supports two additional issue trackers alongside Jira: GitHub Issues an ## 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. + 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. - ## Prerequisites - - - A GitHub account with access to your organisation's repositories - - A personal access token (PAT) with at least the `repo` scope + 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. - ## Create a GitHub personal access token - - - - Click your avatar in the top-right corner of GitHub, then choose **Settings**. - - - Scroll to the bottom of the left sidebar and click **Developer settings**. - - - Select **Personal access tokens → Fine-grained tokens** (recommended) or **Tokens (classic)**. Click **Generate new token**. + ## Prerequisites - 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. - - - Copy the token value before navigating away — GitHub only shows it once. - - + - 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`. + + + + + + Install the [GitHub CLI](https://cli.github.com/) and run: + + ```bash + gh auth login + ``` + + + ```bash + 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. + + + + + + + Go to [github.com/settings/tokens/new](https://github.com/settings/tokens/new) and create a **classic** personal access token. + + + 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 + + + Copy the token value before navigating away — GitHub only shows it once. + + + Each Project v2 has a node ID like `PVT_kwHO...`. List yours with: + + ```bash + 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 - Open the Meridian env file: + 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 meridian config edit @@ -50,13 +97,10 @@ Meridian supports two additional issue trackers alongside Jira: GitHub Issues an # ~/.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 + GITHUB_PROJECT_IDS=PVT_xxx,PVT_yyy ``` - If `GITHUB_REPOS` is omitted, Meridian fetches open issues from all repositories in the organisation that your token can access. + `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 @@ -75,32 +119,37 @@ Meridian supports two additional issue trackers alongside Jira: GitHub Issues an ```bash sqlite3 ~/.meridian/meridian.db \ - "SELECT task_key, title FROM pm_tasks WHERE provider='github' LIMIT 10;" + "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`. - ## Filter to specific repositories + ## Pick different projects later - Set `GITHUB_REPOS` to a comma-separated list of `owner/repo` strings: + Re-run `meridian setup` to bring the project picker back up, or edit `GITHUB_PROJECT_IDS` directly: ```bash - GITHUB_REPOS=myorg/api,myorg/web,myorg/infra + GITHUB_PROJECT_IDS=PVT_kwHOAB123,PVT_kwHOCD456 ``` - 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. + 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 - 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. + 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). - 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. + 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. - Both `GITHUB_TOKEN` and `GITHUB_ORG` are required. Run `meridian config edit` and confirm neither is commented out. + `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. + + + 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. diff --git a/reference/environment-variables.mdx b/reference/environment-variables.mdx index 2f9f4b9..5b55058 100644 --- a/reference/environment-variables.mdx +++ b/reference/environment-variables.mdx @@ -46,13 +46,12 @@ All three credential variables must be set for the Jira connector to activate. T ## GitHub -Both credential variables must be set to enable the GitHub connector. Meridian fetches open issues and pull requests from the specified organisation and links them to sessions alongside Jira tickets. +`GITHUB_TOKEN` is required to enable the GitHub connector; `GITHUB_PROJECT_IDS` selects which Projects (v2) Meridian reads from. Open issues assigned to you on those boards are pulled into `pm_tasks` via the GraphQL API, with each issue's Project Status field mapped to a `status_category`. Run `meridian setup` to obtain the token through the `gh` CLI and pick projects interactively. | Variable | Default | Description | |---|---|---| -| `GITHUB_TOKEN` | *(none)* | A GitHub personal access token with at least the `repo` scope. Create one at [github.com/settings/tokens](https://github.com/settings/tokens). | -| `GITHUB_ORG` | *(none)* | The GitHub organisation name to sync, e.g. `your-org`. | -| `GITHUB_REPOS` | *(all org repos)* | Comma-separated list of `org/repo` slugs to sync, e.g. `your-org/api,your-org/web`. When empty, all repositories in the organisation are included. | +| `GITHUB_TOKEN` | *(none)* | A GitHub OAuth token (extracted from `gh auth token` by `meridian setup`) or a classic personal access token with the `repo`, `read:org`, and `read:project` scopes. Create a PAT at [github.com/settings/tokens](https://github.com/settings/tokens). | +| `GITHUB_PROJECT_IDS` | *(none — no sync)* | Comma-separated GitHub Projects v2 node IDs (each starts with `PVT_`), e.g. `PVT_kwHOAB123,PVT_kwHOCD456`. When empty, no GitHub tasks are synced. List your project IDs with `gh api graphql -f query='{ viewer { projectsV2(first: 10) { nodes { id title } } } }'`. | --- @@ -98,7 +97,7 @@ JIRA_PROJECT_KEYS=KAN,ENG # ── GitHub ──────────────────────────────────────────────────────────────────── GITHUB_TOKEN=ghp_your_personal_access_token -GITHUB_ORG=your-org +GITHUB_PROJECT_IDS=PVT_xxx,PVT_yyy # ── Linear ──────────────────────────────────────────────────────────────────── LINEAR_API_KEY=lin_api_your_key_here