Tools
Jira Workboard
By OpenClaw plugin from Cereb-ai/openclaw-jira-workboard-plugin
Install
npm install
npmConfiguration Example
{
"plugins": {
"entries": {
"jira-openclaw-plugin": {
"enabled": true,
"config": {
"atstToken": "<OAuth 2.0 3LO access token>",
"cloudId": "<Atlassian Cloud ID (UUID)>",
"proxy": "<HTTP proxy URL (optional)>"
}
}
}
}
}README
# @cereb/jira-openclaw-plugin
[](LICENSE)
[](package.json)
[](https://docs.openclaw.ai)
OpenClaw native plugin for Jira Cloud REST API v3 — exposes 14 named tools (one per Jira REST method), each invocable directly from an OpenClaw agent or the bundled `jira-tool` CLI. Replaces the legacy single-dispatcher `atlassian.*` tool.
## Features
- **14 named tools** for Jira Cloud REST v3 — search, get, comment (list / get / post), attachments (list / get / upload), transitions, create task / subtask, submit verdict, abandon, request help.
- **Two invocation paths** — call as an OpenClaw named tool, or use the bundled `jira-tool` CLI from OpenCode, a terminal, or CI.
- **Fail-fast on missing config** — clear error messages, never silent fallback.
- **Orchestrator-friendly** — `jira_create_task` / `jira_create_subtask` auto-format ADF `description` and lock the `plan` label; `jira_submit_verdict` atomically posts the verdict and transitions the ticket.
- **ADF round-tripping** — `jira_comment.body` is plain text (auto-wrapped to ADF); `jira_list_comments` / `jira_get_comment` outputs are plain text (auto-unwrapped from ADF).
## Tools
| tool | purpose | required args |
|---|---|---|
| `jira_search` | JQL search (default 30) | `jql` |
| `jira_get` | read single ticket (whitelisted fields, default excludes comment/worklog) | `issueIdOrKey` |
| `jira_list_comments` | list all comments (ADF → plain text + mentions) | `issueIdOrKey` |
| `jira_get_comment` | read one comment (ADF → plain text + mentions) | `issueIdOrKey`, `commentId` |
| `jira_comment` | post a comment (plain-text `body`, auto-wrapped to ADF) | `issueIdOrKey`, `body` |
| `jira_list_attachments` | list attachment metadata for a ticket | `issueIdOrKey` |
| `jira_get_attachment` | download one attachment's bytes | `attachmentId` |
| `jira_upload_attachment` | upload a file to a ticket | `issueIdOrKey`, `file` |
| `jira_transition` | transition ticket by target status (logical name) | `issueIdOrKey`, `targetStatus` |
| `jira_create_task` | create main task (locked template + `plan` label + assignee) | `project`, `summary`, `requirements`, `scope`, `acceptance_criteria` |
| `jira_create_subtask` | create subtask (locked template + label + assignee) | `project`, `parent`, `summary`, `requirements`, `scope`, `acceptance_criteria`, `labels` |
| `jira_submit_verdict` | submit PASS/FAIL verdict (atomic: post comment + transition) | `issueIdOrKey`, `verdict`, `summary` |
| `jira_abandon_task` | abandon a subtask during re-planning | `issueIdOrKey`, `reason` |
| `jira_request_help` | escalate main task to a human | `issueIdOrKey`, `question` |
Per-tool argument schemas, ADF builder guide, and the 避坑清单 live in [`skills/jira/SKILL.md`](skills/jira/SKILL.md).
## Installation
### From local source (development)
```bash
git clone https://github.com/Cereb-ai/openclaw-jira-workboard-plugin.git
cd openclaw-jira-workboard-plugin
npm install
npm run build
npm pack
openclaw plugins install "npm-pack:./$(ls cereb-jira-openclaw-plugin-*.tgz | head -1)" --force
systemctl --user restart openclaw-gateway.service # required to load the new plugin
```
### From npm (once published)
```bash
npm install -g @cereb/jira-openclaw-plugin
openclaw plugins install "@cereb/jira-openclaw-plugin"
systemctl --user restart openclaw-gateway.service
```
## Configuration
The plugin reads config in this order (highest priority first, CP-2955 env-first):
1. Per-call explicit argument (for tools that accept it)
2. Environment variables (`JIRA_ATST_TOKEN` preferred / `ATST_TOKEN` legacy, `JIRA_CLOUD_ID`, `JIRA_PROXY`)
3. `plugins.entries.jira-openclaw-plugin.config` in `~/.openclaw/openclaw.json` — **last-resort fallback**; missing file is silently treated as empty
Both the MCP (OpenClaw gateway) path and the CLI (`jira-tool`) path resolve via the same env-first ordering — one env block works for either path.
### Environment variables
| variable | required | default | description |
|---|---|---|---|
| `JIRA_ATST_TOKEN` | ✅ | — | OAuth 2.0 3LO access token (Bearer header). **Preferred name** — matches the K8s chart env injection. |
| `ATST_TOKEN` | ✅ (legacy alias) | — | OAuth 2.0 3LO access token. Used as fallback when `JIRA_ATST_TOKEN` is unset. |
| `JIRA_CLOUD_ID` | ✅ | — | Atlassian Cloud ID (UUID) |
| `JIRA_PROXY` | ❌ | (none — direct connection) | HTTP proxy URL (e.g. `http://proxy.example.com:8080`) |
| `JIRA_DEFAULT_ASSIGNEE_ACCOUNT_ID` | ❌ | — | Optional. Default assignee for `jira_create_task` / `jira_create_subtask`. |
Any missing required variable → fail-fast at startup with an actionable error pointing at the missing env var name and an `export` example.
### `~/.openclaw/openclaw.json` (optional, last-resort fallback)
Only consulted when the env vars above are empty. Useful for local-dev overrides; **not required** for the CLI to work.
```json
{
"plugins": {
"entries": {
"jira-openclaw-plugin": {
"enabled": true,
"config": {
"atstToken": "<OAuth 2.0 3LO access token>",
"cloudId": "<Atlassian Cloud ID (UUID)>",
"proxy": "<HTTP proxy URL (optional)>"
}
}
}
}
}
```
## Usage
**OpenClaw native tool** (default for agents):
```json
jira_search { jql: "project = <project-key> AND status != Done" }
jira_get { issueIdOrKey: "<issue-key>" }
```
**Standalone CLI** `jira-tool` (for OpenCode, terminal, CI):
```bash
jira-tool search '{"jql":"project = <project-key> AND status != Done"}'
jira-tool get '{"issueIdOrKey":"<issue-key>"}'
jira-tool submit_verdict '{"issueIdOrKey":"<issue-key>","verdict":"PASS","summary":"done"}'
```
Exit codes: `0` = success, `5` = business error, `2` = JSON parse error, `1` = missing args.
## Parameter typing (CP-3751)
Agents often guess a parameter's JSON type wrong (a numeric comment id
arrives as `10001` instead of `"10001"`, a page size arrives as `"10"`).
The tool schemas previously rejected those guesses outright, which burned
the runtime's circuit-breaker budget on a pure type mistake.
Three parameter classes now accept **string | number** and are normalized
before the Atlassian REST call:
| class | parameters | normalized to |
|---|---|---|
| id | `issueIdOrKey`, `commentId`, `attachmentId`, `parent`, `project`, `mentionAccountIds` members | trimmed `string` |
| pagination | `maxResults`, `startAt` | `integer` (numeric strings accepted) |
| array members | `fields`, `mentionAccountIds`, `labels`, `block.blocks`, `block.blockedBy` | `string[]` |
```json
jira_get_comment { issueIdOrKey: "WTO-71", commentId: 10001 } // number OK
jira_list_comments { issueIdOrKey: "WTO-71", maxResults: "10" } // numeric string OK
jira_get { issueIdOrKey: "WTO-71", fields: [10019] } // numeric member OK
```
`maxResults` above the 100 limit is **clamped** to 100 (not rejected); the
effective value is echoed back in `request.maxResults` and in `details`.
Content fields (`body`, `summary`, `question`, `requirements`, `scope`,
`acceptance_criteria`, `reason`, `description`, …) stay **strict** — an
object or array is rejected with an actionable error, never silently
`String()`-ed.
## Development
```bash
npm install
npm run typecheck # tsc --noEmit
npm run build # tsc -p tsconfig.json
npm test # vitest run
```
Validate the plugin manifest after `src/index.ts` changes:
```bash
npx openclaw plugins build --entry ./dist/index.js
npx openclaw plugins validate --entry ./dist/index.js
```
See [CONTRIBUTING.md](CONTRIBUTING.md) for code structure, how to add a new tool, and PR guidelines.
## Contributing
Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, testing, and PR workflow.
**Changing a tool's return shape?** Read [CONTRIBUTING.md § Changing a tool's return shape](CONTRIBUTING.md#changing-a-tools-return-shape) — the 九面 checklist (ⓐ-ⓘ) is the SOP for any field/contract change. PRs missing the核验表 = 不 merge.
## License
[MIT](LICENSE) © 2026 Leo Wang / Cereb
## Links
- **Repository**: https://github.com/Cereb-ai/openclaw-jira-workboard-plugin
- **Issues**: https://github.com/Cereb-ai/openclaw-jira-workboard-plugin/issues
- **OpenClaw docs**: https://docs.openclaw.ai
tools
Comments
Sign in to leave a comment