jt

README

jt

Tiny command-line tool for creating JIRA issues with a summary, description and optionally a parent.

Installation

If you have go install locally, compile and install with:

go install github.com/leosunmo/jt/cmd/jt

Otherwise download a release from the releases page and put it in your path.

Usage

Create a config file under ~/.config/jt/config.yaml with some default values. Here's an example with all supported values:

url: https://example.atlassian.net
email: me@example.com
defaultProjectKey: PRJ
defaultIssueType: Task
defaultComponentNames:
  - Team A
  - Development
DefaultParentIssueTypes:
  - Epic
  - Initiative

Then you can create an issue with:

# Create issue with only a summary
jt My new issue

# Create issue with a summary and a description
jt My new issue -m "With a description!"

# Or create an issue with $EDITOR
jt
# The first line is the issue summary/title
#
# The description is everything after a blank line
# which can be multiline.

If you want to add the issue to a parent Epic or Initiative, use -p:

jt -p ABC-12345 Add a feature

Setting up JIRA API access

The first time you run it, it will prompt for an access token for JIRA. You can generate one at https://id.atlassian.com/manage-profile/security/api-tokens.

It will be stored in your system's keyring, so you won't have to enter it again until you restart or lock your keychain.

gitcommit-style vim highlighting

Add this to your .vimrc to get gitcommit-style highlighting for the summary and description:

" jt syntax highlighting
au BufReadPost *.jt set syntax=gitcommit

auto-completion and in-line search for parent issues

The provided completion script for zsh allows you to not only get completion for available flags, but also to search easily for parent issues with descriptions.

jt -p <TAB>
PROJ-12345 [Initiative]: Initiative A
PROJ-12344 [Initiative]: Initiative B
PROJ-12343 [Epic]: Epic A
PROJ-12342 [Epic]: Epic B

# You can also search for a specific description by typing it after `-p`
jt -p image<TAB>
```bash
PROJ-12340 [Initiative]: Immutable Docker Images 
PROJ-12341 [Initiative]: Image Storage Project
PROJ-12338 [Epic]: Scan Images
PROJ-12339 [Epic]: Optimize Go image

# Or search for a specific issue key
jt -p PROJ-123<TAB>
PROJ-12346 [Initiative]: Initiative C
PROJ-12347 [Initiative]: Initiative D
PROJ-12348 [Epic]: Epic C
PROJ-12349 [Epic]: Epic D

To enable zsh completion, run the following:

source <(jt --completion)

Note: Currently only zsh is supported. If you want to add support for another shell, feel free to open a PR.

TODO

• Add support for creating sub-Tasks with Tasks as parents. Currently we don't know what type the issue passed to -p is.

Documentation

Index

• Constants
• Variables
• func GetToken() (string, error)
• func OpenInEditor(s string, d string) (string, string, error)
• func SetToken(key string) (string, error)
• type Attrs
• type Component
• type Components
• type Content
• type ContentBlock
• type CreateIssueRequest
• type CreatedIssueResponse
• type Description
• type Field
• type Fields
• type Issue
• type IssueConfig
• type Issuetype
• type JQLSearchRequest
• type JQLSearchResponse
• type JTConfig
  • func ReadConfig(configPath string) (JTConfig, error)
• type JiraClient
  • func NewJiraClient(conf JiraConfig) *JiraClient
  • func (jc JiraClient) NewJIRAIssue(conf IssueConfig) (string, error)
  • func (jc JiraClient) SearchJiraIssues(jqlReq JQLSearchRequest) ([]Issue, error)
• type JiraConfig
• type Parent
• type Project

Constants

const (
	IssueTypeBug        = "Bug"
	IssueTypeTask       = "Task"
	IssueTypeStory      = "Story"
	IssueTypeEpic       = "Epic"
	IssueTypeSubTask    = "Sub-task"
	IssueTypeInitiative = "Initiative"
)

const (
	DefaultConfigLocation = "~/.config/jt/config.yaml"
)

const (
	DefaultEditor = "vim"
)

Variables

var (
	ErrEmptySummary = fmt.Errorf("aborting, summary empty")
)

Functions

func GetToken

func GetToken() (string, error)

func OpenInEditor

func OpenInEditor(s string, d string) (string, string, error)

OpenInEditor opens the user's default editor and returns the contents of the file.

func SetToken

func SetToken(key string) (string, error)

Types

type Attrs

type Attrs struct {
}

type Component

type Component struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	Description string `json:"description"`
}

type Components

type Components struct {
	ID   string `json:"id,omitempty"`
	Name string `json:"name,omitempty"`
}

type Content

type Content struct {
	Type    string         `json:"type,omitempty"`
	Content []ContentBlock `json:"content,omitempty"`
}

type ContentBlock

type ContentBlock struct {
	Type string `json:"type,omitempty"`
	Text string `json:"text,omitempty"`
}

type CreateIssueRequest

type CreateIssueRequest struct {
	Fields Fields `json:"fields,omitempty"`
	Update struct {
		Labels []string `json:"labels,omitempty"`
	} `json:"update"`
}

type CreatedIssueResponse

type CreatedIssueResponse struct {
	ID         string `json:"id"`
	Key        string `json:"key"`
	Self       string `json:"self"`
	Transition struct {
		Status          int `json:"status"`
		ErrorCollection struct {
			ErrorMessages []string `json:"errorMessages"`
			Errors        struct{} `json:"errors"`
		} `json:"errorCollection"`
	} `json:"transition"`
	ErrorMessages []string          `json:"errorMessages"`
	Errors        map[string]string `json:"errors"`
}

type Description

type Description struct {
	Version int       `json:"version,omitempty"`
	Type    string    `json:"type,omitempty"`
	Content []Content `json:"content,omitempty"`
}

type Field

type Field string

const (
	FieldSummary     Field = "summary"
	FieldDescription Field = "description"
	FieldProject     Field = "project"
	FieldIssuetype   Field = "issuetype"
	FieldComponents  Field = "components"
	FieldParent      Field = "parent"
)

type Fields

type Fields struct {
	Components  []Components `json:"components,omitempty"`
	Issuetype   Issuetype    `json:"issuetype,omitempty"`
	Parent      *Parent      `json:"parent,omitempty"`
	Project     Project      `json:"project,omitempty"`
	Description *Description `json:"description,omitempty"`
	Summary     string       `json:"summary,omitempty"`
}

type Issue

type Issue struct {
	ID     string `json:"id"`
	Key    string `json:"key"`
	Self   string `json:"self"`
	Fields Fields `json:"fields,omitempty"`
}

type IssueConfig

type IssueConfig struct {
	Summary        string
	Description    string
	ProjectKey     string
	IssueType      string
	ComponentNames []string
	ParentIssueKey string
}

type Issuetype

type Issuetype struct {
	ID          string `json:"id,omitempty"`
	Name        string `json:"name,omitempty"`
	Description string `json:"description"`
	Subtask     bool   `json:"subtask"`
}

type JQLSearchRequest

type JQLSearchRequest struct {
	JQL            string  `json:"jql"`
	IncludedFields []Field `json:"fields"`
	NextPageToken  string  `json:"nextPageToken,omitempty"`
}

type JQLSearchResponse

type JQLSearchResponse struct {
	Issues        []Issue `json:"issues"`
	NextPageToken string  `json:"nextPageToken,omitempty"`
}

type JTConfig

type JTConfig struct {
	// URL is the URL of the JIRA instance.
	URL string `yaml:"url"`
	// Email is the JIRA user email. Used as a username for authenticating.
	Email string `yaml:"email"`
	// Default project key is the JIRA project that will be used for issues. This is the short version of a project name, example: PRJ.
	DefaultProjectKey string `yaml:"defaultProjectKey"`
	// Default issue type is the issue type that will be used for issues.
	DefaultIssueType string `yaml:"defaultIssueType"`
	// Default component names are the default components that will be added to issues.
	DefaultComponentNames []string `yaml:"defaultComponentNames"`
	// Default parent issue types are the issue types that will be searched for when querying for parent issues.
	DefaultParentIssueTypes []string `yaml:"defaultParentIssueTypes"`
}

func ReadConfig

func ReadConfig(configPath string) (JTConfig, error)

ReadConfig reads config file from the default location.

type JiraClient

type JiraClient struct {
	// contains filtered or unexported fields
}

func NewJiraClient

func NewJiraClient(conf JiraConfig) *JiraClient

func (JiraClient) NewJIRAIssue

func (jc JiraClient) NewJIRAIssue(conf IssueConfig) (string, error)

NewJIRAIssue creates a new JIRA issue using the JIRA REST API v3. The function returns the key of the created issue and an error if the issue could not be created. https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/#api-rest-api-3-issue-post

func (JiraClient) SearchJiraIssues

func (jc JiraClient) SearchJiraIssues(jqlReq JQLSearchRequest) ([]Issue, error)

SearchJiraIssues searches for JIRA issues using the JIRA REST API v3. The function returns a slice of JQLSearchResponse and an error if the search request failed.

type JiraConfig

type JiraConfig struct {
	URL   string
	Email string
	Token string
}

type Parent

type Parent struct {
	Key string `json:"key,omitempty"`
}

type Project

type Project struct {
	ID  string `json:"id,omitempty"`
	Key string `json:"key,omitempty"`
}