72 lines
2.3 KiB
Markdown
72 lines
2.3 KiB
Markdown
# Jira Vein
|
|
|
|
Status: **live**
|
|
|
|
Connects soleprint to Jira Cloud. Fetches tickets, sprints, backlogs, and epics. Supports text and JSON output formats.
|
|
|
|
---
|
|
|
|
## What It Does
|
|
|
|
- Query your assigned tickets, project backlogs, and current sprints
|
|
- Fetch full ticket details with comments, attachments, and child work items
|
|
- Process entire epics: fetch the epic and all children, save to local storage
|
|
- Search with raw JQL
|
|
- Stream attachment content directly from Jira
|
|
|
|
## Configuration
|
|
|
|
Create a `.env` file in the vein directory or set environment variables:
|
|
|
|
```env
|
|
JIRA_URL=https://your-org.atlassian.net
|
|
JIRA_EMAIL=you@example.com
|
|
JIRA_API_TOKEN=your-api-token
|
|
API_PORT=8001
|
|
```
|
|
|
|
`JIRA_EMAIL` and `JIRA_API_TOKEN` are optional in config. They can be provided per-request via HTTP headers instead, allowing one vein instance to serve multiple users.
|
|
|
|
Generate an API token at [id.atlassian.net/manage-profile/security/api-tokens](https://id.atlassian.net/manage-profile/security/api-tokens).
|
|
|
|
## Endpoints
|
|
|
|
| Method | Path | Description |
|
|
|--------|------|-------------|
|
|
| GET | `/health` | Test connection, returns authenticated user |
|
|
| GET | `/mine` | Your assigned open tickets |
|
|
| GET | `/backlog?project=KEY` | Project backlog |
|
|
| GET | `/sprint?project=KEY` | Current sprint tickets |
|
|
| GET | `/ticket/{key}` | Full ticket detail with comments and children |
|
|
| POST | `/search` | Raw JQL query |
|
|
| POST | `/epic/{key}/process` | Fetch entire epic tree, save to files (streaming) |
|
|
| GET | `/epic/{key}/status` | Check if epic has been processed |
|
|
| GET | `/attachment/{id}` | Stream attachment content |
|
|
|
|
All list endpoints support `page`, `page_size`, and `text=true` for plain-text output.
|
|
|
|
## Authentication
|
|
|
|
Credentials resolve in order:
|
|
|
|
1. HTTP headers (`X-Jira-Email`, `X-Jira-Token`)
|
|
2. `.env` file values
|
|
|
|
## Text Mode
|
|
|
|
Pass `?text=true` to any query endpoint. Returns formatted plain text instead of JSON. Useful for piping into other tools or AI prompts.
|
|
|
|
## Epic Processing
|
|
|
|
The `/epic/{key}/process` endpoint streams progress as NDJSON. It fetches the epic, then each child ticket with a short delay between requests. All tickets are saved as JSON files to `artery/larder/jira_epics/{key}/`.
|
|
|
|
## Running Standalone
|
|
|
|
```bash
|
|
cd soleprint/artery/veins/jira
|
|
python run.py
|
|
# Runs on port 8001
|
|
```
|
|
|
|
Or through soleprint, where it is mounted under `/artery/jira/`.
|