Jira
JiraService → JiraAdapter → Atlassian REST API v3
Business logic
Pagination handling
Response mapping
JQL construction
Auth injection
OAuth 2.0 token
API Token (Basic)
Request serialization
API version 3
your-domain.atlassian.net
/rest/api/3/
/rest/agile/1.0/
- Redirect → Atlassian authorize
- Exchange code for access_token
- Fetch accessible cloud resources
- Use cloud_id + Bearer token
Base64(email:api_token)
Authorization: Basic …
Direct domain URL
Simpler for server-to-server
What & Why
Jira is the backbone of engineering project management. The Octopus Jira integration exposes the full surface of Atlassian's REST API v3 — projects, issues, sprints, boards, users, and JQL search — through a single consistent adapter pattern.
The JiraAdapter handles the two dominant auth modes: OAuth 2.0 (Atlassian's three-legged flow that issues per-cloud access tokens) and API Token (Basic Auth with email + token, common for server-side automation). Both modes share the same method signatures so switching auth doesn't change calling code.
Pagination is handled uniformly via Atlassian's startAt / maxResults / total envelope. transition_issue is the key workflow method — it moves an issue through Jira's configured transitions (e.g. Backlog → In Progress → Done) by transition name, without requiring callers to know transition IDs. search_issues accepts raw JQL so any Jira query expressible in the UI is also available to agents.
Status Transitions via transition_issue
transition_issue(issue_key="PROJ-123", transition="In Progress")
// Jira resolves transition name → transition ID internally
Methods Reference
All ~24 methods grouped by category. Key params listed for each.
Projects
| Method | Description | Key Params |
|---|---|---|
list_projects | List all accessible Jira projects | limit, start_at |
get_project | Get full details for a single project | project_key |
create_project | Create a new Jira project | name, key, project_type, lead_account_id |
Issues
| Method | Description | Key Params |
|---|---|---|
list_issues | List issues in a project with optional JQL filter | project_key, status, assignee, limit, start_at |
get_issue | Get full details for a single issue | issue_key |
create_issue | Create a new issue | project_key, summary, issue_type, description, priority, assignee_id, labels |
update_issue | Update fields on an existing issue | issue_key, summary, description, priority, labels |
delete_issue | Delete an issue permanently | issue_key |
transition_issue | Move issue to a new status via workflow transition | issue_key, transition (name) |
assign_issue | Assign or unassign an issue | issue_key, assignee_id |
add_comment | Post a comment on an issue | issue_key, comment |
list_comments | List comments on an issue (paginated) | issue_key, limit, start_at |
get_comments | Get all comments for an issue | issue_key |
add_attachment | Upload a file attachment to an issue | issue_key, file_path, file_name |
get_attachments | List attachments on an issue | issue_key |
Sprints
| Method | Description | Key Params |
|---|---|---|
list_sprints | List sprints for a board | board_id, state (active/future/closed), limit |
get_sprint | Get sprint details | sprint_id |
create_sprint | Create a new sprint on a board | board_id, name, start_date, end_date, goal |
start_sprint | Activate a sprint (moves to active state) | sprint_id, start_date, end_date |
complete_sprint | Close an active sprint | sprint_id |
Boards
| Method | Description | Key Params |
|---|---|---|
list_boards | List all boards accessible to the user | limit, start_at, project_key |
get_board | Get board configuration | board_id |
get_board_issues | List issues currently on a board | board_id, sprint_id, limit, start_at |
Users
| Method | Description | Key Params |
|---|---|---|
list_users | List users in the Atlassian organization | limit, start_at |
get_user | Get user by account ID | account_id |
search_users | Search users by display name or email | query, limit |
Search
| Method | Description | Key Params |
|---|---|---|
search_issues | Run a JQL query against all accessible issues | jql, limit, start_at, fields |
CLI Examples
# List projects
constellation jira list-projects
# List issues in a project filtered by status
constellation jira list-issues --project PROJ --status "In Progress"
# Create a new bug issue
constellation jira create-issue --project PROJ --summary "Fix login bug" --type Bug --priority High
# Transition an issue to Done
constellation jira transition-issue --issue PROJ-123 --transition "Done"
# Assign an issue to a user
constellation jira assign-issue --issue PROJ-123 --assignee-id abc123def456
# Add a comment to an issue
constellation jira add-comment --issue PROJ-123 --comment "Fixed in branch feature/login-fix"
# Search issues with JQL
constellation jira search-issues --jql "project = PROJ AND sprint in openSprints() AND status = 'In Progress'"
# List sprints for a board
constellation jira list-sprints --board 42 --state active
# Create and start a sprint
constellation jira create-sprint --board 42 --name "Sprint 14" --start-date 2026-05-19 --end-date 2026-06-02
constellation jira start-sprint --sprint 108
# Search users
constellation jira search-users --query "jane.doe"
Auth Setup
OAuth 2.0 (Atlassian 3LO):
- Register an OAuth 2.0 app at developer.atlassian.com
- Set redirect URI to your Octopus callback endpoint
- Authorize scopes:
read:jira-work,write:jira-work,read:jira-user,manage:jira-project - Complete the 3LO flow:
/auth/jira/authorize→ Atlassian consent →/auth/jira/callback - Octopus stores the access token and cloud ID; all subsequent calls use Bearer auth
API Token (Basic Auth):
- Generate an API token at id.atlassian.com/manage-profile/security/api-tokens
- Pass credentials in the connection config:
base_url:https://your-domain.atlassian.netemail: your Atlassian account emailapi_token: the generated token
- Adapter constructs
Authorization: Basic base64(email:api_token)on every request