Stefano Fiorini
100 lines
3.8 KiB
Markdown
100 lines
3.8 KiB
Markdown
---
|
|
name: atlassian
|
|
description: Interact with Atlassian Cloud Jira and Confluence through a portable task-oriented CLI for search, issue/page edits, comments, transitions, and bounded raw requests.
|
|
---
|
|
|
|
# Atlassian (Pi)
|
|
|
|
Portable Atlassian workflows for pi using the shared TypeScript CLI in `scripts/`.
|
|
|
|
## Requirements
|
|
|
|
- Node.js 20+
|
|
- `pnpm`
|
|
- Atlassian Cloud account access
|
|
- `ATLASSIAN_BASE_URL`
|
|
- `ATLASSIAN_EMAIL`
|
|
- `ATLASSIAN_API_TOKEN`
|
|
|
|
The `ATLASSIAN_*` values may come from the shell environment or a `.env` file in the installed skill's `scripts/` directory.
|
|
|
|
## First-Time Setup
|
|
|
|
Global install:
|
|
|
|
```bash
|
|
mkdir -p ~/.pi/agent/skills/atlassian
|
|
cp -R skills/atlassian/pi/* ~/.pi/agent/skills/atlassian/
|
|
cd ~/.pi/agent/skills/atlassian/scripts
|
|
pnpm install
|
|
```
|
|
|
|
Project-local install:
|
|
|
|
```bash
|
|
mkdir -p .pi/skills/atlassian
|
|
cp -R skills/atlassian/pi/* .pi/skills/atlassian/
|
|
cd .pi/skills/atlassian/scripts
|
|
pnpm install
|
|
```
|
|
|
|
Pi can also load this repo through settings or package installs as documented in [docs/PI.md](../../../docs/PI.md).
|
|
|
|
If you installed this repo from a local checkout with `./scripts/install-pi-package.sh`, the runtime stays in the checkout mirror at `pi-package/skills/atlassian/scripts`.
|
|
|
|
## Prerequisite Check (MANDATORY)
|
|
|
|
Run inside the skill runtime directory that matches your install style:
|
|
|
|
- local checkout package install: `pi-package/skills/atlassian/scripts`
|
|
- project-local copied install: `.pi/skills/atlassian/scripts`
|
|
- global copied install: `~/.pi/agent/skills/atlassian/scripts`
|
|
|
|
```bash
|
|
cd pi-package/skills/atlassian/scripts
|
|
node -e "require.resolve('commander');require.resolve('dotenv');console.log('OK: runtime dependencies installed')"
|
|
node -e 'require("dotenv").config({ path: ".env" }); const required = ["ATLASSIAN_BASE_URL", "ATLASSIAN_EMAIL", "ATLASSIAN_API_TOKEN"]; const missing = required.filter((key) => !(process.env[key] || "").trim()); if (missing.length) { console.error("Missing required Atlassian config: " + missing.join(", ")); process.exit(1); } console.log("OK: Atlassian config present")'
|
|
pnpm atlassian health
|
|
```
|
|
|
|
If any check fails, stop and return:
|
|
|
|
`Missing dependency/config: atlassian requires installed CLI dependencies and valid Atlassian Cloud credentials. Configure ATLASSIAN_* in the shell environment or scripts/.env, then retry.`
|
|
|
|
## Supported Commands
|
|
|
|
- `pnpm atlassian health`
|
|
- `pnpm atlassian jira-search --jql "..."`
|
|
- `pnpm atlassian jira-get --issue ABC-123`
|
|
- `pnpm atlassian jira-create ... [--dry-run]`
|
|
- `pnpm atlassian jira-update ... [--dry-run]`
|
|
- `pnpm atlassian jira-comment ... [--dry-run]`
|
|
- `pnpm atlassian jira-transitions --issue ABC-123`
|
|
- `pnpm atlassian jira-transition ... [--dry-run]`
|
|
- `pnpm atlassian conf-search --query "..."`
|
|
- `pnpm atlassian conf-get --page 12345`
|
|
- `pnpm atlassian conf-create ... [--dry-run]`
|
|
- `pnpm atlassian conf-update ... [--dry-run]`
|
|
- `pnpm atlassian conf-comment ... [--dry-run]`
|
|
- `pnpm atlassian conf-children --page 12345`
|
|
- `pnpm atlassian raw --product jira|confluence --method GET|POST|PUT --path ...`
|
|
|
|
## Usage Examples
|
|
|
|
- `pnpm atlassian jira-search --jql "project = ENG ORDER BY updated DESC" --max-results 10`
|
|
- `pnpm atlassian conf-comment --page 12345 --body-file comment.storage.html --dry-run`
|
|
- `pnpm atlassian raw --product jira --method GET --path "/rest/api/3/issue/ENG-123"`
|
|
|
|
## Safety Rules
|
|
|
|
- Default output is JSON; prefer that for agent workflows.
|
|
- Use `--dry-run` before any mutating command unless the user clearly wants the write to happen immediately.
|
|
- `raw` is for explicit edge cases only and does not allow `DELETE`.
|
|
- `--body-file` must stay inside the current workspace.
|
|
- Confluence write bodies should be storage-format inputs in v1.
|
|
|
|
## Notes
|
|
|
|
- Atlassian Cloud is the primary supported platform in v1.
|
|
- Package installs use the repo's `pi-package/skills/atlassian/` mirror so the installed skill directory name matches `atlassian`.
|