Jira

Manage Jira issues using wrapper scripts around the go-jira CLI. Credentials are handled by go-jira (~/.jira.d/config.yml + OS keychain). Scripts never touch secrets directly.

Configuration

Configured automatically by the setup script. Manual setup:

# 1. Install go-jira
brew install go-jira

# 2. Create config
mkdir -p ~/.jira.d
cat > ~/.jira.d/config.yml << 'EOF'
endpoint: https://your-org.atlassian.net
user: you@example.com
password-source: keyring
EOF
chmod 600 ~/.jira.d/config.yml

# 3. Store token in keychain
security add-generic-password -a "api-token:you@example.com" -s "go-jira" -w "YOUR_TOKEN"

# 4. Optional: set defaults
cat > ~/.boring/jira/defaults << 'EOF'
JIRA_PROJECT=PROJ
JIRA_ASSIGNEE=your-username
EOF

# 5. Optional: default labels (applied to every new ticket)
echo "label1 label2 label3" > ~/.boring/jira/default-labels

Cloud tokens: https://id.atlassian.com/manage-profile/security/api-tokens Server/DC PAT: Profile → Personal Access Tokens

Scripts

All scripts are in the scripts/ directory relative to this skill.

Project metadata (ALWAYS check first)

Before creating issues or transitioning, fetch the available types and transitions:

scripts/jira-meta.sh types                        # issue types for default project
scripts/jira-meta.sh types --project KEY           # issue types for specific project
scripts/jira-meta.sh transitions PROJ-123          # available transitions for an issue
scripts/jira-meta.sh statuses                      # all statuses in the project
scripts/jira-meta.sh priorities                    # available priorities
scripts/jira-meta.sh fields                        # all fields
scripts/jira-meta.sh refresh                       # force refresh cached data

Results are cached for 24h in ~/.boring/jira/cache/. The create script validates issue types against this cache and shows valid options on mismatch.

Create issue

scripts/jira-create.sh --type Bug --summary "[Service] Title" \
    [--description "text"] [--project KEY] [--assignee id] \
    [--priority High] [--labels "l1 l2"] [--parent KEY]

Applies default labels from ~/.boring/jira/default-labels automatically. Returns the issue key.

Writing issue descriptions

Issues describe problems, not solutions. Do not include fix details, code changes, or implementation plans. The fix is unknown at the time of filing — that comes later during investigation.

A good issue description contains:

1. What is broken — the observable symptom (error message, wrong output, crash, empty response)
2. Why it happens — the root cause or chain of events leading to the failure
3. Impact — who or what is affected, how severely, under what conditions
4. How to reproduce — exact steps, commands, or inputs that trigger the issue
5. Expected vs actual behavior — what should happen vs what does happen

Do not include:

• Fix proposals, code patches, or implementation suggestions
• "The fix is to change X to Y" — that belongs in a PR, not a ticket
• Workarounds (unless explicitly asked to document them)

Example — BAD:

jenkins_post uses -f flag. Fix: remove -f from curl command in _api.sh line 20.

Example — GOOD:

Jenkins trigger and abort operations fail silently on HTTP errors. When the server returns 4xx/5xx, the script exits before reaching its error handling code, producing no error message. This happens because curl -f causes a non-zero exit under set -e, killing the process during command substitution. Affected scripts: jenkins-trigger.sh, jenkins-abort.sh. To reproduce: trigger a build on a non-existent job path.

View issue

scripts/jira-view.sh PROJ-123
scripts/jira-view.sh PROJ-123 --comments

Transition issue

scripts/jira-transition.sh PROJ-123 --list               # list available transitions
scripts/jira-transition.sh PROJ-123 "In Progress"         # transition by name
scripts/jira-transition.sh PROJ-123 "Review"
scripts/jira-transition.sh PROJ-123 "Mark as in production"

Add comment

scripts/jira-comment.sh PROJ-123 "Comment text"

Update fields

scripts/jira-update.sh PROJ-123 --summary "[Svc] New title"
scripts/jira-update.sh PROJ-123 --description "Updated" --priority High
scripts/jira-update.sh PROJ-123 --assignee username

Manage labels

scripts/jira-labels.sh PROJ-123 set label1 label2
scripts/jira-labels.sh PROJ-123 add new-label
scripts/jira-labels.sh PROJ-123 remove old-label

Assign issue

scripts/jira-assign.sh PROJ-123                    # assign to default from config
scripts/jira-assign.sh PROJ-123 --me               # assign to self
scripts/jira-assign.sh PROJ-123 john.doe            # assign to specific user
scripts/jira-assign.sh PROJ-123 --unassign          # remove assignment

List issues (JQL)

scripts/jira-list.sh --assignee me --status "In Progress"
scripts/jira-list.sh --status "In Progress,In code review" --type Bug
scripts/jira-list.sh --project PROJ --limit 20
scripts/jira-list.sh --jql "project = PROJ AND created >= -7d ORDER BY priority DESC"

Search issues

scripts/jira-search.sh "memory leak" --project PROJ
scripts/jira-search.sh "NPE" --limit 10

Raw API access

scripts/jira-api.sh GET "/rest/api/3/myself"
scripts/jira-api.sh GET "/rest/api/3/issue/PROJ-123"
scripts/jira-api.sh POST "/rest/api/3/issue" '{"fields":{...}}'
scripts/jira-api.sh PUT "/rest/api/3/issue/PROJ-123" '{"fields":{"summary":"New"}}'

Workflow example

S=scripts

# Create and start working
ISSUE=$($S/jira-create.sh --type Bug --summary "[Service] NPE in processor" --description "Stack trace...")
$S/jira-transition.sh $ISSUE "Start progress"

# ... fix and push PR ...
$S/jira-transition.sh $ISSUE "Review"

# ... after merge & deploy ...
$S/jira-transition.sh $ISSUE "Mark as in production"
$S/jira-comment.sh $ISSUE "Deployed to production"