Skip to content

README.md

134 lines · 6.8 KB · Markdown

@kody/jira

Intent

Provide reusable, headless Jira Cloud helpers so Kody agents can list sites and projects, read and search issues, add comments, and apply transitions on the caller's Jira Cloud site — not a shared platform workspace. Auth is a bring-your-own Atlassian OAuth 2.0 (3LO) app and/or an Atlassian API token plus account email. Mutations support dryRun. Multi-account uses jira / jira-*. No personal project keys are hard-coded.

This listing is meant to be forked. After you fork, connect your Jira Cloud site and run ./smoke-test on your copy. Do not treat the live @kody/jira connection as yours.

Share this listing as https://kody.codes/@kody/jira.

This official OAuth/API-token package is the preferred invoke path. Setup is harder: bring your own Atlassian OAuth 2.0 (3LO) app or an API token plus account email. For a faster first win, connect Atlassian MCP in Get started and use @kody/atlassian-mcp.

What it does

  • List Jira Cloud sites granted to an OAuth token, or confirm an API-token site
  • Search projects the caller can browse
  • Read one issue or search issues with caller-supplied JQL
  • Preview issue create, comment, or transition with dryRun: true
  • Call an unwrapped Jira Cloud REST v3 path through ./request

Do not use this package for Jira Data Center, Confluence, Bitbucket, or Jira Service Management-specific APIs.

Prerequisites / setup

There is no built-in Jira platform app. Pick one lane (or both). Do not paste tokens, emails, or client secrets into chat.

Lane A — Atlassian API token + email (fastest)
  1. Create a token at Atlassian account API tokens.
  2. Save the Atlassian account email and API token (do not paste values here):
https://kody.codes/account/secrets/new?name=jiraEmail&description=Atlassian%20account%20email%20used%20with%20a%20Jira%20Cloud%20API%20token%20(Basic%20auth%20username).&scope=user
https://kody.codes/account/secrets/new?name=jiraApiToken&description=Atlassian%20API%20token%20for%20Jira%20Cloud%20REST%20(Basic%20auth%20password).&scope=user
  1. In the account secrets UI, approve host {your-site}.atlassian.net on both secrets (for example acme.atlassian.net).
  2. Call helpers with site: "acme" (the *.atlassian.net subdomain) and auth: "token" if an OAuth connection named jira also exists.

For a second account named jira-work, save jiraEmail-work and jiraApiToken-work the same way, then pass account: "jira-work".

Lane B — OAuth 2.0 (3LO)
  1. Create an OAuth 2.0 integration at the Atlassian developer console.
  2. Authorization → OAuth 2.0 (3LO) → register redirect URI exactly https://kody.codes/connect/oauth.
  3. Permissions → add Jira API scopes read:jira-user, read:jira-work, and write:jira-work.
  4. Open this prefilled connect URL while signed in to Kody. Paste the client ID and client secret into the Kody form only:
https://kody.codes/connect/oauth?provider=jira&authorizeUrl=https%3A%2F%2Fauth.atlassian.com%2Fauthorize&tokenUrl=https%3A%2F%2Fauth.atlassian.com%2Foauth%2Ftoken&apiBaseUrl=https%3A%2F%2Fapi.atlassian.com&flow=confidential&scopes=offline_access%20read%3Ajira-user%20read%3Ajira-work%20write%3Ajira-work&allowedHosts=auth.atlassian.com%2Capi.atlassian.com&dashboardUrl=https%3A%2F%2Fdeveloper.atlassian.com%2Fconsole%2Fmyapps%2F&extraAuthorizeParams=%7B%22audience%22%3A%22api.atlassian.com%22%2C%22prompt%22%3A%22consent%22%7D&providerSetupInstructions=Create%20an%20OAuth%202.0%20(3LO)%20app%20at%20https%3A%2F%2Fdeveloper.atlassian.com%2Fconsole%2Fmyapps%2F.%20Enable%20Authorization%20%E2%86%92%20OAuth%202.0%20(3LO).%20Register%20redirect%20URI%20exactly%20https%3A%2F%2Fkody.codes%2Fconnect%2Foauth.%20Under%20Permissions%2C%20add%20the%20Jira%20API%20scopes%20read%3Ajira-user%2C%20read%3Ajira-work%2C%20and%20write%3Ajira-work.%20Paste%20the%20client%20id%20and%20client%20secret%20into%20this%20Kody%20form.%20Do%20not%20paste%20them%20into%20chat.

Decoded:

  • Redirect / callback: https://kody.codes/connect/oauth
  • Authorize: https://auth.atlassian.com/authorize
  • Token: https://auth.atlassian.com/oauth/token
  • API base: https://api.atlassian.com
  • Flow: confidential
  • Scopes: offline_access read:jira-user read:jira-work write:jira-work
  • Extra authorize params: audience=api.atlassian.com, prompt=consent
  • Hosts: auth.atlassian.com, api.atlassian.com
  1. Run ./smoke-test. If the token can access more than one site, pass site or cloudId on later calls.

To connect a second Atlassian account, change provider to jira-work (or another jira-* name) in that URL, then pass account: "jira-work" on every helper.

Reconnect later at https://kody.codes/connect/oauth?provider=jira.

Auth model
KindUsed by this package?
Built-in Jira OAuthNo. There is no jira platform app.
BYO Atlassian OAuth 2.0 (3LO)Yes — integration name jira or jira-*.
Atlassian API token + emailYes — secrets jiraEmail + jiraApiToken (or jiraEmail-work + jiraApiToken-work).
API key / raw token pasted into chatNever.

Default helper input: omit account (jira). Helpers try the OAuth integration named jira first, then the API-token secrets. Pass auth: "oauth" or auth: "token" to pin a lane. Pass site for the API-token lane and whenever more than one OAuth site is granted.

OAuth calls use https://api.atlassian.com/ex/jira/{cloudId}/rest/api/3. API-token calls use https://{site}.atlassian.net/rest/api/3.

Agents: see AGENTS.md for import paths, smoke checks, and mutation guards.

Done when

  • OAuth jira is connected and/or jiraEmail + jiraApiToken are saved with the correct hosts approved
  • Smoke test returns ok: true (live /myself when credentials exist; no email)
  • Mutating helpers refuse unless confirm: true; dryRun: true never writes

Branding

community-icon.svg is the official Jira app logomark (blue tile #1868db with the white stacked mark) taken from Atlassian's public logo package (@atlaskit/logo → Jira icon). Paths are unmodified except for explicit fill colors so the mark stays legible at 56 pixels. Jira® is a trademark of Atlassian Pty Ltd. This package is not affiliated with or endorsed by Atlassian.

Docs