go-atlassian

README

Go-Atlassian

Go-Atlassian is a Go SDK and CLI for Atlassian products (Jira and Confluence) that provides:

• Jira REST API client (jira/) - wrapper around go-jira with additional utilities
• Confluence REST API client (confluence/) - page reading, writing, and Storage Format IR
• Report engine (report/) - configurable report definitions with Dashforge Dashboard IR output
• omniroadmap provider (omniroadmap/) - omniroadmap-core provider.Provider adapter for Jira Product Discovery (JPD) Ideas
• XML parser (xml/) - parse Jira XML exports when API access is unavailable
• JQL builder (root package) - programmatically construct JQL queries
• CLI tool (cmd/gojira/) - command-line interface optimized for AI agents and humans
• MCP server (cmd/gojira-mcp/) - Model Context Protocol server for AI assistants like Claude

Installation

# Install the CLI
go install github.com/grokify/go-atlassian/cmd/gojira@latest

# Install the MCP server (for AI assistants)
go install github.com/grokify/go-atlassian/cmd/gojira-mcp@latest

# Use as a library
go get github.com/grokify/go-atlassian

Quick Start

CLI Usage

# Set credentials via environment variables
export JIRA_URL=https://your-instance.atlassian.net
export JIRA_USER=your-email@example.com
export JIRA_TOKEN=your-api-token

# Search issues with JQL
gojira search --jql "project = FOO AND status = Open"

# Get a specific issue
gojira get ISSUE-123

# Get issue with full API JSON (all fields)
gojira get ISSUE-123 --raw

# Get comments for an issue
gojira comments ISSUE-123

# Show statistics by field
gojira stats --jql "project = FOO" --by status --format table

# Update an issue
gojira patch ISSUE-123 --set priority=High --add-label urgent

# Export issues to XLSX
gojira export --jql "project = FOO" --xlsx report.xlsx

# Output formats
gojira search --jql "assignee = currentUser()" --table  # Human-readable
gojira search --jql "project = FOO" --json              # Machine-readable (default)
gojira search --jql "project = FOO" --toon              # Token-optimized for LLMs

# Create issues from YAML files
gojira create -f story.yaml
gojira create -f story.yaml --dry-run  # Preview without creating

MCP Server (for AI Assistants)

The MCP server enables AI assistants like Claude to interact with Jira:

{
  "mcpServers": {
    "jira": {
      "command": "gojira-mcp",
      "env": {
        "JIRA_BASE_URL": "https://company.atlassian.net",
        "JIRA_USERNAME": "user@example.com",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

Available tools: jira_get_issue, jira_search, jira_create_issue, jira_update_issue, jira_add_comment, jira_get_transitions, jira_transition_issue, jira_get_comments, jira_get_projects

See MCP Server documentation for details.

Library Usage

import "github.com/grokify/go-atlassian/jira"

// Create client with basic auth
client, err := jira.NewClientFromBasicAuth(
    "https://your-instance.atlassian.net",
    "your-email@example.com",
    "your-api-token",
    false,
)
if err != nil {
    log.Fatal(err)
}

// Search issues
issues, err := client.IssueAPI.SearchIssues("project = FOO", false)
if err != nil {
    log.Fatal(err)
}

for _, issue := range issues {
    im := jira.NewIssueMore(&issue)
    fmt.Printf("%s: %s [%s]\n", im.Key(), im.Summary(), im.Status())
}

JQL Builder

import "github.com/grokify/go-atlassian"

// Build JQL programmatically
jql := jira.JQL{
    ProjectsIncl: [][]string{{"FOO"}},
    StatusesIncl: [][]string{{"Open", "In Progress"}},
}
query := jql.String() // "project = 'FOO' AND status IN ('Open', 'In Progress')"

Package Structure

Package	Description	Dependencies
root	JQL builder, config, constants	None (lightweight)
go-atlassian/jira	Jira REST API client	go-jira SDK
go-atlassian/confluence	Confluence REST API client with Storage Format IR	go-atlassian/jira
go-atlassian/report	Configurable report engine with Dashforge Dashboard IR output	go-atlassian/jira
go-atlassian/omniroadmap	omniroadmap-core provider.Provider adapter for Jira Product Discovery (JPD) Ideas	go-atlassian/jira, omniroadmap-core
go-atlassian/core	Shared types for issue creation	yaml.v3
go-atlassian/mcpserver	MCP server implementation	JSON-RPC
go-atlassian/xml	XML export parser	None
go-atlassian/web	URL helpers	None

Documentation

Full documentation is available at grokify.github.io/go-atlassian:

• CLI Reference - All commands and flags
• MCP Server - Setup for AI assistants
• SDK Guide - Using Go-Atlassian as a library
• AI Agents Guide - Integration with LLMs
• JQL Examples - Common query patterns

Use Cases

1. Programmatically construct JQL queries
2. Generate Markdown reports from JQL results
3. Parse Jira XML exports when API access is unavailable
4. Automate Jira operations via CLI (ideal for AI agents)

URL Formats

Accessing a list of issues by JQL is avialable via the UI and API:

• UI: https://{jira_host}/issues/?jql=
• API: https://{jira_host}/rest/api/2/search?jql=

REST API Authentication: Basic Auth

The API auth can be provided by Basic Auth using an personsal API Token.

• Docs: https://developer.atlassian.com/cloud/jira/platform/basic-auth-for-rest-apis/
• Token Page: https://id.atlassian.com/manage-profile/security/api-tokens

Note on Hours Per Day and Days Per Week

This module supports custom hoursPerDay and daysPerWeek settings per Jira.

This is described here and set in the UI via the screenshot below,

Ref: https://community.atlassian.com/t5/Jira-Software-questions/What-it-JIRA-counting-as-a-quot-day-quot-in-Time-Tracking/qaq-p/1703409

Also of note is that the hours per day can be set to a decimal value, such as 8.5, but the UI may not show it:

Ref: https://community.atlassian.com/t5/Jira-questions/change-quot-Working-hours-per-day-quot-by-a-decimal-value/qaq-p/583095

Additional Discussion on Jira XML

General Discussion

General discussion including using Jira XML to:

1. export comments and issue link types
2. create CSV for flexible reporting and import

Ref: https://community.atlassian.com/t5/Jira-questions/JIRA-Issue-XML-Export-What-is-it-good-for/qaq-p/603308

Global Config

Working Hours Per Day and Working Days Per Week are global values and cannot be set on a per-project basis.

Ref: https://community.atlassian.com/t5/Jira-Software-questions/Time-Tracking-Hours-Is-it-still-a-global-change/qaq-p/1337399

JQL Examples

Goal	Example
Query by key	key = ABC-123
Query by parent	parent = ABC-123
Query by linked issue	issue in linkedIssues (ABC-123)
Query by reporter	reporter = "foo@bar.com"

https://community.atlassian.com/t5/Jira-questions/How-to-search-all-linked-issues-with-issues-from-specific/qaq-p/1027269

Backlog

Downloading the project backlog view appears to be challenging. Here is some info on attempts to do this.

• What is the equivalent JQL query for a scrum board backlog
• How can I export the Backlog to csv or Excel or TXT?

Roughly:

project = <project_name> AND resolution = Unresolved AND status!=Closed AND (Sprint not in openSprints() OR Sprint is EMPTY) AND type not in (Epic, Sub-Task) ORDER BY Rank ASC

Agile Life Cycle Stages

Stage is a common way to understand the stages of development given that many companies can use different statuses and workflows.

Stage the following stages (from Asana) and will provide a grouping capability for implementation-specific workflows into these standard meta statuses for consistent and canonical understanding of the process.

Not all the stages need to be used, however, the stages that are used can be understood in a canonical way.

image courtesy of Asana

An alternate, but related agile methodology is avialable from eSparkBiz:

image courtesy of eSparkBiz

As well as from BISS:

image courtesy of BISS

This is described as "The 5 Stages of the Agile Software Development Lifecycle" by Mendix.

image courtesy of Mendix