Skip to main content
Meridian fetches your open Jira tickets, stores them locally as pm_tasks, and uses them during session classification. Every time you close a coding or research session, Meridian’s classifier checks which ticket that work most likely belongs to and writes a ticket_links row to its database — no timesheets, no manual updates required. All you need is a Jira API token and three environment variables. Once classification is wired up, Meridian also drafts worklogs against the matched ticket every hour. On Jira, a worklog is posted via Jira’s native worklog REST API — the same primitive that powers Jira’s built-in time tracking, so each posted entry shows up in the ticket’s Work Log tab with the synthesised narrative as its comment and the rolled-up duration as Time Spent. Posting only happens after you approve the draft in the dashboard — see Review and approve worklogs for the shared draft → approve → post pipeline (it works the same way across Jira, Linear, and GitHub).

​
Prerequisites

  • A Jira Cloud account (Jira Data Center is not supported)
  • An API token from your Atlassian account
  • Meridian installed and the daemon running (meridian status to confirm)

​
Get a Jira API token

1

Open Atlassian account settings

Navigate to id.atlassian.com and sign in, then click your avatar in the top-right corner and choose Manage account.
2

Open the Security tab

Select the Security tab in the left sidebar.
3

Create a new token

Scroll to API tokens and click Create and manage API tokens → Create API token. Give it a descriptive label such as meridian-local and click Create.
4

Copy the token

Copy the token value immediately — Atlassian will not show it again. Paste it somewhere temporary before moving to the next step.

​
Configure Meridian

Set the following environment variables. The cleanest way is to open the Meridian env file directly: 
meridian config edit
This opens ~/.meridian/.env in your $EDITOR. Add or update the Jira block: 
# ~/.meridian/.env

JIRA_BASE_URL=https://your-org.atlassian.net
JIRA_EMAIL=you@your-org.com
JIRA_API_TOKEN=your-api-token-here

# Optional: restrict sync to specific project keys (comma-separated)
# JIRA_PROJECT_KEYS=KAN,ENG
Meridian only reads your Jira tickets and writes worklogs (Jira’s native time-tracking entries) against tickets you’ve matched. It never creates, modifies, closes, or deletes tickets themselves, and no worklog is posted until you approve it in the dashboard.

​
What “posting a worklog” means on Jira

When you approve a draft, Meridian calls Jira’s POST /rest/api/3/issue/{key}/worklog endpoint with:
  • Time spent — duration of the classified session window, rounded to the nearest minute.
  • Started — the session start in your local timezone.
  • Comment — the synthesised narrative of what you actually did during that window (built from screenpipe activity + matched code/commit context).
In Jira you’ll see a new entry under the ticket’s Work Log tab attributed to you, and the ticket’s Time Spent total will roll up by the worklog’s duration. Worklogs are idempotent on (task_key, window_start, window_end) — re-running the pipeline never double-posts. To enable posting at all, the same JIRA_EMAIL + JIRA_API_TOKEN you set above must be able to add worklogs on the relevant projects (the standard “Work on issues” permission in Jira). No extra scopes are needed beyond the API token already configured. Alternatively, re-run the installer’s credential walkthrough to be prompted interactively: 
./install.sh --skip-permissions

​
Apply and verify

1

Restart the daemon

meridian restart
The daemon re-reads ~/.meridian/.env on startup and refreshes the pm_tasks cache from Jira within the first poll cycle.
2

Run a health check

meridian doctor
Look for jira: connected in the output. A green status confirms Meridian can reach your Jira instance and has fetched at least one ticket.
3

Inspect the task cache (optional)

sqlite3 ~/.meridian/meridian.db \
  "SELECT task_key, title, status FROM pm_tasks LIMIT 10;"
You should see rows for your open issues.

​
Limit which projects are synced

By default Meridian fetches every open ticket assigned to you. To restrict it to one or more projects, set JIRA_PROJECT_KEYS to a comma-separated list of project keys: 
JIRA_PROJECT_KEYS=KAN,ENG
Only issues whose key prefix matches one of the listed values will be pulled into pm_tasks. This speeds up the initial cache load and keeps the classifier focused on relevant work.

​
Force-refresh the Jira task cache

The daemon refreshes pm_tasks automatically at startup. If you’ve just closed a sprint, reassigned tickets, or simply want to pull the latest data without restarting the daemon, run: 
python3 scripts/refresh_pm_tasks.py
You can also pass a custom JQL expression or point it at a different database: 
# Custom JQL
python3 scripts/refresh_pm_tasks.py --jql "project=KAN ORDER BY updated DESC"

# Custom DB path
python3 scripts/refresh_pm_tasks.py --db /path/to/meridian.db

# Combine both
python3 scripts/refresh_pm_tasks.py \
  --jql "project=ENG AND sprint in openSprints()" \
  --db ~/.meridian/meridian.db
The script reads your credentials from ~/.meridian/.env automatically — no extra configuration needed.

​
Troubleshooting

A 401 error means the credentials are incorrect. Double-check that:
  • JIRA_EMAIL matches the email address on your Atlassian account exactly.
  • JIRA_API_TOKEN is the token value itself, not a label or partial string.
  • JIRA_BASE_URL ends with .atlassian.net and has no trailing slash.
Regenerate the API token in Atlassian account settings if you’re unsure.
An empty pm_tasks table means the JQL query returned no issues. Check that:
  • Your account has at least one open issue assigned to it in the targeted projects.
  • If you set JIRA_PROJECT_KEYS, confirm the keys are correct (they are case-sensitive, e.g. KAN not kan).
  • The issue type is Task or Feature — the default JQL filters on those types.
Run python3 scripts/refresh_pm_tasks.py --jql "project=KAN ORDER BY updated DESC" to test with broader criteria.
All three Jira variables (JIRA_BASE_URL, JIRA_EMAIL, JIRA_API_TOKEN) must be set. Run meridian config edit and confirm none of them are commented out or missing.