gojira

gojira

Status badges populate once the GitHub Actions CI/CD workflows have run on the repository; on a fresh fork they render a neutral "no status" state until the first workflow run. The coverage figure is the first-party statement coverage reported by go test (see Testing and coverage).

A Go CLI and library for working with Jira Cloud from the command line. Its flagship gojira crawl recursively mirrors a Jira issue graph into Markdown — including the issue's hierarchy, development metadata (branches, commits, pull requests, builds, repositories), and human-labelled custom fields — and can export the discovered graph as JSON and D2. Beyond crawling, gojira also ships a gRPC server (gojira serve), a Model Context Protocol server for AI hosts (gojira mcp), and write operations to create and update issues, add comments, and run workflow transitions. The same engine is available as an embeddable Go library.

Pre-1.0 status. APIs may change between minor versions until v1.0 is tagged.

[!WARNING] Breaking changes in v0.2.0. Two changes break compatibility with v0.1.0:

1. Package layout — the reusable classify, client, and log packages moved under pkg/, so their import paths gained a /pkg/ segment (e.g. github.com/neumachen/gojira/pkg/client). The library facade github.com/neumachen/gojira is unchanged.
2. Protocol services — internal/grpcserver became internal/grpc and internal/mcpserver became internal/mcp, each behind an encapsulated Serve(ctx, cfg). The gojira.ServerConfig / gojira.LoadServerConfig accessors were removed — read Config.ServerAddress from a loaded Config instead.

See the v0.2.0 changelog for the full list. This is a pre-1.0 release; there is no migration shim, but no external consumers depend on the previous paths.

Install

Go install

go install github.com/neumachen/gojira/cmd/gojira@v0.2.0

Docker

# Pull (when published to a registry) or build locally:
docker build -t gojira:v0.2.0 .

A docker-compose.yml is provided for convenience; see "Docker Compose" below.

Shell completion

gojira can generate completion scripts for bash, zsh, fish, and PowerShell. Add the matching line to your shell's startup file:

# bash — ~/.bashrc
source <(gojira completion bash)

# zsh — ~/.zshrc (ensure `autoload -U compinit && compinit` runs first)
source <(gojira completion zsh)

# fish
gojira completion fish > ~/.config/fish/completions/gojira.fish

# PowerShell — add to $PROFILE
gojira completion pwsh | Out-String | Invoke-Expression

Completion works without any gojira configuration, so you can set it up before running gojira init.

Quick start

# 1. Generate a Jira Cloud API token at:
#      https://id.atlassian.com/manage-profile/security/api-tokens

# 2. Configure credentials. The simplest path is `gojira init`, which
#    writes a 0600 config file at ~/.config/gojira/config.yaml — see
#    "First run: gojira init" below. The CLI also reads env vars
#    directly: either export them or use a .env file.
gojira init   # interactive; or pass --site/--user/--token as flags
# alternative: env-only configuration
cp .env.example .env
$EDITOR .env   # fill in GOJIRA_SITE, GOJIRA_USER, GOJIRA_TOKEN

# 3. Crawl a single Jira issue and its reachable graph.
gojira crawl PROJ-123

# 4. The Markdown output appears under ./out by default.
ls out/PROJ-123/

Docker Compose

# After ./out is created by your first run, this works as a
# convenient wrapper:
docker compose run --rm gojira crawl PROJ-123

What gojira crawl does

Starting from one Jira issue key, the crawler:

1. Fetches the issue via the Jira Cloud REST API v3 (GET /rest/api/3/issue/{key}?expand=names).
2. Parses the issue's description from Atlassian Document Format into Markdown.
3. Renders an index.md for the issue under <output-dir>/<KEY>/index.md with metadata, description, relationships, the ## Development panel (pull requests, branches, commits, repositories, builds), and human-labelled custom fields.
4. Recursively follows links: subtasks, parents, issue links, hierarchy children (via JQL parent = "KEY" plus Epic Link), and Jira-flavoured links inside the description. Each discovered key is fetched and rendered the same way.
5. Recognizes GitHub pull request URLs as PR references even when no Jira key is present in the PR title or branch.
6. Writes a per-issue references/outbound.md summarising every outbound reference the issue produced.
7. Honours configurable caps on depth, issue count, time, and API concurrency.

CLI flags

The crawl subcommand accepts these flags. Each maps to an env var of the same name in uppercase with a GOJIRA_ prefix; the flag overrides the env var when both are set.

First run: gojira init

Every Jira-touching command (crawl, serve, create, update, comment, transitions, transition) requires some form of configuration before it will contact Jira. The simplest way to provide it is the gojira init subcommand, which scaffolds a config file with 0600 permissions (it contains your Jira API token).

gojira init writes the global config by default; pass --local to write a project-local file instead. The two flags are mutually exclusive, and --local never creates or modifies the global config.

• gojira init (or gojira init --global) — writes the global config at the XDG path ($XDG_CONFIG_HOME/gojira/config.yaml or, when XDG_CONFIG_HOME is unset, ~/.config/gojira/config.yaml).
• gojira init --local — writes a project-local ./gojira.yaml in the current working directory (similar in spirit to git init for the project's gojira config). The file is complete and self-sufficient: it carries every required field so it loads on its own, without any global config present.

# Global config (default; writes the XDG config.yaml):
gojira init \
  --site https://your.atlassian.net \
  --user you@example.com \
  --token <api-token>

# Project-local config (writes ./gojira.yaml, adds it to .gitignore):
gojira init --local \
  --site https://your.atlassian.net \
  --user you@example.com \
  --token <api-token>

Omitted required values are prompted for interactively. The token is read without echo on a real terminal (via golang.org/x/term) and falls back to a warned-echo read on non-terminals (CI pipes, etc.). The --output-dir and --server-address flags accept the documented defaults (./out and 127.0.0.1:50051) when omitted.

gojira init refuses to overwrite an existing config file unless you pass --force. The written YAML has the same shape as gojira.example.yaml and is consumed by the same loader the cascade below documents.

Security: do not commit ./gojira.yaml. The project-local file contains your Jira API token. gojira init --local writes it with 0600 permissions and, when a ./.gitignore is present, appends gojira.yaml to it (and prints what it did). When no .gitignore exists, it warns you to ignore the file yourself. Treat ./gojira.yaml like any other credentials file.

How a command finds its configuration

A guarded command will run iff any one of the following is true:

1. A config file is discovered through the cascade (see Config-file discovery below): an explicit --config value, $GOJIRA_CONFIG_FILE, ./gojira.yaml, or the XDG global config file.
2. The --config <path> flag was passed.
3. The --site, --user, and --token flags were ALL passed.
4. The required env vars are present: GOJIRA_CONFIG_FILE, or all three of GOJIRA_SITE, GOJIRA_USER, and GOJIRA_TOKEN.

If none of (1)-(4) hold, the command exits with a clear error pointing at gojira init. The init, help, and --version invocations are exempt from this guard so they remain usable from a no-config state.

Configuration

gojira supports three configuration surfaces — embedded defaults, one or two YAML config files (a global and an optional project-local file), and GOJIRA_* environment variables — plus the CLI flags documented above. They compose into one effective configuration through a documented cascade:

embedded defaults < XDG global config.yaml < local ./gojira.yaml < GOJIRA_* env vars < CLI flags

A value at any layer overrides the same value at every lower layer; a value absent at every layer keeps its embedded default.

When no --config flag and no $GOJIRA_CONFIG_FILE are given, gojira layers the global config (~/.config/gojira/config.yaml) and the project-local ./gojira.yaml field-by-field: the local file overrides the global on a per-field basis, and any field absent from the local file is inherited from the global config. This is true XDG-style layering with local-first precedence, so a project can pin just the handful of values it cares about (e.g. a different output.dir or crawl.concurrency) and inherit the rest of the global config unchanged.

An explicit --config <path> (or $GOJIRA_CONFIG_FILE) pins exactly that one file with no layering: gojira loads only that file and does not also read the global or local config. This is the escape hatch for CI, scripts, and any case where you want a fully deterministic single-file load.

Config-file discovery

There are two discovery modes, depending on whether the load is explicitly pinned or left to discovery:

Explicit single-file pin (first match wins, no layering). When either of the explicit candidates is set, gojira uses exactly that file and stops — it does NOT also read the global or local config:

1. --config <path> (CLI flag)
2. $GOJIRA_CONFIG_FILE

Both are explicit: when set but the file does not exist, gojira exits with a hard error so a misconfigured invocation fails fast.

Pure discovery (global + local layered). When neither explicit candidate is set, gojira layers the following files (each missing file is silently skipped; a fully absent chain falls through to defaults plus environment variables, not an error):

1. ./gojira.yaml — project-local (current working directory). Written by gojira init --local.
2. $XDG_CONFIG_HOME/gojira/config.yaml — XDG global, when XDG_CONFIG_HOME is set.
3. ~/.config/gojira/config.yaml — XDG global fallback.

In pure discovery, the global config (4 or 5, whichever exists) is loaded first and the local ./gojira.yaml (3) is layered on top field-by-field. Either may be absent; if both exist, local fields override global ones and global fills any gaps the local file leaves.

Behavior change in v0.2.0. Previously a ./gojira.yaml in pure discovery fully shadowed the global config (winner-takes-all). The two files are now merged: global is read first and local is layered over it per field. To restore the old single-file load semantics, point --config (or $GOJIRA_CONFIG_FILE) at the file you want.

A starter file lives at gojira.example.yaml. Copy it to one of the locations above, edit the values you care about, and delete the blocks you want to leave at their defaults. The file's first line embeds a yaml-language-server directive so editors like VS Code (with the YAML extension) and Neovim get autocomplete and live validation against the embedded JSON Schema at internal/config/config.schema.json.

Quick start with a config file:

# Copy the example and edit it.
cp gojira.example.yaml gojira.yaml
$EDITOR gojira.yaml

# Supply the secret out of band so it never lands in version control.
export GOJIRA_JIRA_API_TOKEN="$(security find-generic-password -s gojira -w)"

# Crawl. --config is optional; ./gojira.yaml is auto-discovered.
gojira crawl --config gojira.yaml PROJ-1

Canonical environment variables

The table below lists the canonical GOJIRA_* keys gojira reads. Every key here has a YAML equivalent under the corresponding section of gojira.yaml; pick whichever surface fits the deployment best.

Deprecated aliases (still honored)

The v0.1 flat GOJIRA_* keys documented under CLI flags continue to work; gojira resolves them to their canonical Phase 0 equivalents during load. When both the canonical key and its alias are set, the canonical key wins — set both only during a migration.

GOJIRA_OUTPUT_DIR, GOJIRA_LOG_LEVEL, and GOJIRA_LOG_FORMAT already use canonical names in v0.1 and need no migration.

Output layout

out/
└── PROJ-123/
    ├── index.md
    └── references/
        └── outbound.md

Each fetched issue lives at <KEY>/index.md. Outbound references discovered in that issue are summarised at <KEY>/references/outbound.md. The references/ directory keeps the per-issue reference index out of the issue's own rendered Markdown so a reader who wants the full graph view can find it, but a reader who just wants the issue content sees only index.md.

Library usage

The same engine is available as a Go library. Third-party programs can embed gojira in their pipelines without invoking the CLI binary:

package main

import (
    "context"
    "fmt"
    "os"

    "github.com/neumachen/gojira"
)

func main() {
    cfg, err := gojira.LoadConfig(map[string]string{
        "GOJIRA_SITE":       os.Getenv("GOJIRA_SITE"),
        "GOJIRA_USER":       os.Getenv("GOJIRA_USER"),
        "GOJIRA_TOKEN":      os.Getenv("GOJIRA_TOKEN"),
        "GOJIRA_OUTPUT_DIR": "./out",
    })
    if err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }

    summary, err := gojira.Crawl(
        context.Background(), cfg, []string{"PROJ-123"}, nil,
    )
    if err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
    fmt.Printf("fetched %d issues; %d PRs discovered\n",
        summary.Fetched, summary.PRsFound)
}

The library facade groups its capabilities into classification (Classify), configuration (LoadConfig and friends), fetch/render (GetIssue, FetchAndRender), crawl (Crawl, CrawlGraph), and write operations (CreateIssue, UpdateIssue, AddComment, ListTransitions, TransitionIssue), plus type aliases for Config, Summary, Sink, Event, and the graph model (GraphModel/GraphNode/GraphEdge). All are documented in gojira.go's package doc.

Observability and tracing

gojira crawl ships a verbose, structured, correlatable observability instrument designed for answering "where did the wall-clock go?" on a large crawl. It's measurement-first: enabling it does not change traversal, fetch logic, or on-disk output — only what is observed.

Levels

gojira extends slog's standard four levels (error, warn, info, debug) with a fifth, trace. The five levels carry intent-based meaning:

Select with --log-level trace or GOJIRA_LOG_LEVEL=trace. Use --log-format json to get machine-filterable JSON lines (one record per line).

Correlation attributes

Every traced log line carries structured attributes so a single grep/jq filter can reconstruct any subset of the run's work:

Measurement summary

At end of run, gojira crawl emits a single INFO crawl.measurement line with the per-phase wall-clock attribution:

{"msg":"crawl.measurement","total_api_time_ms":31872,"total_duration_ms":32114,"call_counts":{"fetch":48,"parse":48,"hierarchy_jql":12,"dev_status":48,"render":48,"store":48},"time_by_phase_ms":{"fetch":18204,"hierarchy_jql":7411,"dev_status":4012,"parse":612,"render":1031,"store":602}}

The same totals are also folded into the crawl.Summary returned to library callers as APICallCounts, APITimeByPhase, and TotalAPITime.

Filtering examples

# All response-stream traces for one issue:
gojira crawl PROJ-1417 --log-level trace --log-format json 2>&1 \
  | jq 'select(.trace_stream=="response" and .ticket_id=="PROJ-1417")'

# Only the per-phase measurement summary:
gojira crawl PROJ-1417 --log-level info --log-format json 2>&1 \
  | jq 'select(.msg=="crawl.measurement")'

# Reconstruct the fan-out tree (TRACE):
gojira crawl PROJ-1417 --log-level trace --log-format json 2>&1 \
  | jq 'select(.msg=="crawl.fanout") | "\(.discovered_from) -[\(.relation)]-> \(.ticket_id)"'

Credential redaction

Authorization, Cookie, Proxy-Authorization, Set-Cookie, and X-Atlassian-Token headers are ALWAYS redacted in trace output, even at --log-level trace. The raw token is never written to logs by design; the redaction is audited by a unit test (TestRoundTripper_RedactsAuthorizationEvenAtTrace).

gRPC service (gojira serve)

In addition to the one-shot crawl subcommand, gojira can run as a long-lived gRPC server that exposes its full capability surface — classification, issue fetch, recursive crawl, in-memory graph export, and write operations (create/update/comment/transitions) — to other front-ends such as a TUI or the gojira mcp bridge.

# Start the server (reads the same GOJIRA_* config as `crawl`).
export GOJIRA_SITE="https://your-site.atlassian.net"
export GOJIRA_USER="you@example.com"
export GOJIRA_TOKEN="<api-token>"
gojira serve --address 127.0.0.1:50051

The server is single-tenant: one Jira identity is loaded at startup from the same configuration cascade as crawl. It accepts concurrent clients (each RPC is isolated) and is intended for a loopback or otherwise trusted network — Phase 1 ships no TLS and no authentication.

Service gojira.v1.Gojira

The proto contract is defined in proto/gojira/v1/gojira.proto and the generated Go bindings live under gen/gojira/v1/.

Write operations

The CreateIssue, UpdateIssue, AddComment, and TransitionIssue RPCs let clients mutate Jira through the same single-tenant identity the server loaded at startup. Two design points are worth calling out:

• Dry-run. CreateIssue and UpdateIssue accept a dry_run flag. When set, the server builds and returns the exact JSON request body it would send to Jira (in dry_run_body) without performing the write — useful for previewing a mutation before committing to it.
• Extensible fields. Beyond the typed fields (summary, description, labels, parent), any Jira field — including tenant-specific custom fields — can be set through the raw_fields map (field id → raw JSON value). In the Go library this is the WithField / WithRawFields option; new fields never require a new method or signature change.

Errors carry Jira's detail: a 400 validation failure maps to gRPC InvalidArgument with the failing field names in the message; a 409 (e.g. an invalid workflow transition) maps to FailedPrecondition.

Issue deletion is intentionally unsupported — destructive removal is out of scope for this phase.

Server configuration

The server address can also be set in the YAML config file:

server:
  address: 127.0.0.1:50051

The server stops gracefully on SIGINT/SIGTERM.

Reference client

A minimal reference client ships at cmd/gojira-client for smoke-testing a running server. It is a reference tool, not a production front-end.

go run ./cmd/gojira-client -address 127.0.0.1:50051 -classify PROJ-1147
go run ./cmd/gojira-client -address 127.0.0.1:50051 -key PROJ-1147 -format markdown
go run ./cmd/gojira-client -address 127.0.0.1:50051 -crawl PROJ-1147
go run ./cmd/gojira-client -address 127.0.0.1:50051 -create-project PROJ -create-type Task -create-summary "New task" -dry-run
go run ./cmd/gojira-client -address 127.0.0.1:50051 -comment PROJ-1147 -comment-text "Looks good"
go run ./cmd/gojira-client -address 127.0.0.1:50051 -transitions PROJ-1147
go run ./cmd/gojira-client -address 127.0.0.1:50051 -transition PROJ-1147 -to-status "In Progress"

Regenerating the proto bindings

The generated code under gen/ is committed. To regenerate after editing the proto contract, run buf:

./scripts/gen-proto.sh   # runs `buf lint` then `buf generate`

MCP server (gojira mcp)

gojira mcp runs gojira as a Model Context Protocol server over the stdio transport so AI hosts (Claude Desktop, Cursor, Zed, …) can use gojira's tools directly. The host launches gojira mcp as a subprocess and speaks JSON-RPC over its stdin/stdout. stdout is reserved for the protocol stream; all logs go to stderr.

# Run from your AI host's mcpServers config (see below); for a manual
# smoke, you can drive a one-shot handshake yourself:
gojira mcp --config ~/.config/gojira/config.yaml < your-jsonrpc-frames

gojira mcp is guarded by the same require-config check as crawl/serve (see First run) and additionally requires mcp.mode to be set — it exits 1 with a clear message when mcp.mode is unset or not one of self|bridge.

Modes

The mode is set via mcp.mode in the config file or GOJIRA_MCP_MODE in the environment. It is required for gojira mcp and only for gojira mcp (crawl/serve continue to load configs without an mcp: section).

• self — gojira does the Jira work in-process via the library facade. The simplest mode; no extra server to run.
• bridge — gojira forwards each tool call to a running gojira serve gRPC server at server.address (default 127.0.0.1:50051, override with GOJIRA_SERVER_ADDRESS or --address). This is the "one shared gRPC backend, many ephemeral MCP processes" topology: a single long-running gojira serve is the upstream, and every AI host spawns its own short-lived gojira mcp subprocess that bridges to it.

Tools

The following MCP tools are always available (read-only):

• classify — classify an input as Jira key, Jira URL, GitHub PR URL, or external URL
• get_issue — fetch a single Jira issue with its outbound references
• crawl — recursively crawl Jira issues from one or more start keys; returns a summary on completion (emits MCP progress notifications per fetched issue when the host supplies a progress token)
• get_graph — crawl in-memory and return the discovered issue graph as {nodes, edges} (no files written)
• list_transitions — list workflow transitions available for an issue

The mutating tools are gated behind mcp.allow_writes: true (default false). When allow_writes is false, the write tools are absent from tools/list — an AI cannot mutate Jira until the operator explicitly opts in:

• create_issue
• update_issue
• add_comment
• transition_issue

Host configuration

Add an entry to your AI host's MCP servers configuration. The exact file location varies by host (Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json on macOS; Cursor and Zed have their own per-app paths) but the schema is the same:

{
  "mcpServers": {
    "gojira": {
      "command": "gojira",
      "args": ["mcp"],
      "env": {
        "GOJIRA_SITE": "https://your.atlassian.net",
        "GOJIRA_USER": "you@example.com",
        "GOJIRA_TOKEN": "your-api-token",
        "GOJIRA_MCP_MODE": "self"
      }
    }
  }
}

For bridge mode, set "GOJIRA_MCP_MODE": "bridge" and ensure a gojira serve instance is running on the host; add "GOJIRA_SERVER_ADDRESS": "127.0.0.1:50051" (or your chosen address) if you do not use the default. The env block in the host config is not the only configuration channel — gojira init (or a hand-written ~/.config/gojira/config.yaml) is equivalent, and the same require-config guard described in First run applies: at least one of a discovered config file, --config, the --site/--user/--token trio, or the equivalent GOJIRA_* env vars must be present.

To expose the mutating tools to the host, add "GOJIRA_MCP_ALLOW_WRITES": "true" to the env block (or set mcp.allow_writes: true in your config file). Default is off.

Known limitations (v0.2.0)

• Jira Cloud only. Jira Server / Data Center is out of scope for the entire product.
• Comments are not yet rendered (the field is fetched but the current renderer ignores it; landing in v0.2).
• The Jira Dev Status API used for development metadata is semi-undocumented. It has been stable for ~10 years because Atlassian's UI uses it, but no SLA is offered. Disable with --include-dev-status=false to opt out.
• The gRPC service (gojira serve) is single-tenant and ships without TLS or authentication; run it only on a loopback or trusted network. Streaming issue content over the wire, multi-tenancy, per-request config overrides, and TLS/auth are deferred to Phase 2.
• gRPC write operations (CreateIssue/UpdateIssue/AddComment/ TransitionIssue) use the server's single startup identity; per-request credentials are deferred to a later phase. Issue deletion is not supported.
• Observability and tracing (--log-level trace) is opt-in; default info already shows the end-of-run measurement summary. Cross-process tracing (e.g. OpenTelemetry export across the gRPC boundary) is out of scope for this release.

Roadmap

Future releases anticipated:

• A terminal UI (TUI) front-end over the gRPC API, as a gRPC client. (The MCP server already shipped — see MCP server.)
• Phase 2 service work: streaming rendered issue content over the wire, multi-tenant identities, per-request configuration overrides, and TLS/authentication.
• gojira fetch — targeted single-issue (or small-list) retrieval without recursive expansion. The same renderer; just no JQL parent search and no descent into linked issues.
• Write operations: create issues, update fields, post comments.
• JQL search: list issues matching a query and crawl the result set.
• Improved customisation: per-field rendering options, per-tenant field-name overrides.

No timelines committed. Direction only.

Testing and coverage

The entire suite runs under the standard Go toolchain — go test, table- driven tests, golden files, httptest fakes, and bufconn for the gRPC service. There is no third-party test runner; assertions use a mix of stretchr/testify and the standard testing package.

# Run everything (the same command CI runs):
go test ./... -count=1

# With the race detector:
go test ./... -count=1 -race

# First-party statement coverage (attributes cross-package coverage so the
# library facade, exercised only by integtest/, is counted correctly):
go test ./... -count=1 -coverpkg=./... -coverprofile=cover.out
go tool cover -func=cover.out | tail -1

The current first-party coverage is 77.6% of statements (excluding the generated gen/ protobuf bindings). The core paths — the library facade, crawl orchestration, rendering, parsing, and configuration cascade — sit at 80–100%; the lowest-covered first-party packages are the MCP bridge write path and the Dev Status error branches.

Project documentation

• docs/jira-markdown-crawler-design.md — the package-boundary design mini-doc.
• docs/engineering-principles.md — the rule book contributors and AI agents follow.
• docs/releasing.md — how gojira's build identity is stamped and how a maintainer cuts a release.

License

MIT