jira

package module
v1.0.8 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 17, 2017 License: Apache-2.0 Imports: 12 Imported by: 0

README

Build Status GoDoc License

go-jira

simple command line client for Atlassian's Jira service written in Go

Install

Download

You can download one of the pre-built binaries for go-jira here.

Build

You can build and install with Go:

go get gopkg.in/Netflix-Skunkworks/go-jira.v1/cmd/jira

v1 vs v0 changes

Golang library import

For the new version of go-jira you should use:

import "gopkg.in/Netflix-Skunkworks/go-jira.v1"

If you have code that depends on the old apis, you can still use them with this import:

import "gopkg.in/Netflix-Skunkworks/go-jira.v0"
Configs per command

Instead of requiring a exectuable template to get configs for a given command now you can create a config to be applied to a command. So if you want to use template: table by default for yor jira list you can now do:

$ cat $HOME/.jira.d/list.yml
template: table

Where previously you needed something like:

# cat $HOME/.jira.d/config.yml
#!/bin/sh
case $JIRA_OPERATION in 
    list)
      echo "template: table";;
esac
Custom Commands

Now you can create your own custom commands to do common operations with jira. Please see the details Custom Commands section below for more details. If you want to create a command jira mine that lists all the issues assigned to you now you can modify your .jira.d/config.yml file to add a custom-commands section like this:

custom-commands:
  - name: mine
    help: display issues assigned to me
    script: |-
      {{jira}} list --query "resolution = unresolved and assignee=currentuser() ORDER BY created"

Then the next time you run jira help you will see your usage:

$ jira mine --help
usage: jira mine

display issues assigned to me

Flags:
      --help                 Show context-sensitive help (also try --help-long and --help-man).
  -v, --verbose ...          Increase verbosity for debugging
  -e, --endpoint=ENDPOINT    Base URI to use for Jira
  -u, --user=USER            Login name used for authentication with Jira service
      --unixproxy=UNIXPROXY  Path for a unix-socket proxy
  -k, --insecure             Disable TLS certificate verification
Incompatible command changes

Unfortunately during the rewrite between v0 and v1 there were some changes necessary that broke backwards compatibility with existing commands. Specifically the dups, blocks, add worklog and add|remove|set labels commands have had the command word swapped around:

  • jira DUPLICATE dups ISSUE => jira dup DUPLICATE ISSUE
  • jira BLOCKER blocks ISSUE => jira block BLOCKER ISSUE
  • jira add worklog => jira worklog add
  • jira add labels => jira labels add
  • jira remove labels => jira labels remove
  • jira set labels => jira labels set
Login process change

Previously jira used attempt to get a JSESSION cookies by authenticating with the webservice standard GUI login process. This has been especially problematic as users need to authenticate with various credential providers (google auth, etc). We now attempt to authenticate via the session login api. This may be problematic for users if admins have locked down the session-login api, so we might have to bring back the error-prone Basic-Auth approach. For users that are unable to authenticate via jira hopefully someone in your organization can provide me with details on a process for you to authenticate and we can try to update jira.

Configuration

go-jira uses a configuration hierarchy. When loading the configuration from disk it will recursively look through all parent directories in your current path looking for a .jira.d directory. If your current directory is not a child directory of your homedir, then your homedir will also be inspected for a .jira.d directory. From all of .jira.d directories discovered go-jira will load a <command>.yml file (ie for jira list it will load .jira.d/list.yml) then it will merge in any properties from the config.yml if found. The configuration properties found in a file closests to your current working directory will have precedence. Properties overriden with command line options will have final precedence.

The complicated configuration hierarchy is used because go-jira attempts to be context aware. For example, if you are working on a "foo" project and you cd into your project workspace, wouldn't it be nice if jira ls automatically knew to list only issues related to the "foo" project? Likewise when you cd to the "bar" project then jira ls should only list issues related to "bar" project. You can do this with by creating a configuration under your project workspace at ./.jira.d/config.yml that looks like:

project: foo

You will need to specify your local jira endpoint first, typically in your homedir like:

mkdir ~/.jira.d

cat <<EOM >~/.jira.d/config.yml
endpoint: https://jira.mycompany.com
EOM

Then use jira login to authenticate yourself as $USER. To change your username, use the -u CLI flag or set user: in your config.yml

Dynamic Configuration

If the .jira.d/config.yml file is executable, then go-jira will attempt to execute the file and use the stdout for configuration. You can use this to customize templates or other overrides depending on what type of operation you are running. For example if you would like to use the "table" template when ever you run jira ls, then you can create a template like this:

#!/bin/sh

echo "endpoint: https://jira.mycompany.com"
echo "editor: emacs -nw"

case $JIRA_OPERATION in 
    list)
      echo "template: table";;
esac

Or if you always set the same overrides when you create an issue for your project you can do something like this:

#!/bin/sh
echo "project: GOJIRA"

case $JIRA_OPERATION in
    create)
        echo "assignee: $USER"
        echo "watchers: mothra"
        ;;
esac
Custom Commands

You can now create custom commands for jira just by editing your .jira.d/config.yml config file. These commands are effectively shell-scripts that can have documented options and arguments. The basic format is like:

custom-commands:
  - command1
  - command2
Commands

Where the individual commands are maps with these keys:

  • name: string [required] This is the command name, so for jira foobar you would have name: foobar
  • help: string This is help message displayed in the usage for the command
  • hidden: bool This command will be hidden from users, but still executable. Sometimes useful for constructing complex commands where one custom command might call another.
  • default: bool Use this for compound command groups. If you wanted to have jira foo bar and jira foo baz you would have two commands with name: foo bar and name: foo baz. Then if you wanted jira foo baz to be called by default when you type jira foo you would set default: true for that custom command.
  • options: list This is the list of possible option flags that the command will accept
  • args: list This is the list of command arguments (like the ISSUE) that the command will accept.
  • aliases: string list: This is a list of alternate names that the user can provide on the command line to run the same command. Typically used to shorten the command name or provide alternatives that users might expect.
  • script: string [required] This is the script that will be executed as the action for this command. The value will be treated as a template and substitutions for options and arguments will be made before executing.
Options

These are possible keys under the command options property:

  • name: string [required] Name of the option, so name: foobar will result in --foobar option.
  • help: string The help messsage displayed in usage for the option.
  • type: string: The type of the option, can be one of these values: BOOL, COUNTER, ENUM, FLOAT32, FLOAT64, INT8, INT16, INT32, INT64, INT, STRING, STRINGMAP, UINT8, UINT16, UINT32, UINT64 and UINT. Most of these are primitive data types an should be self-explanitory. The default type is STRING. There are some special types:
    • COUNTER will be an integer type that increments each time the option is used. So something like --count --count will results in {{options.count}} of 2.
    • ENUM type is used with the enum property. The raw type is a string and must be one of the values listed in the enum property.
    • STRINGMAP is a string => string map with the format of KEY=VALUE. So --override foo=bar --override bin=baz will allow for {{options.override.foo}} to be bar and {{options.override.bin}} to be baz.
  • short: char The single character option to be used so short: c will allow for -c.
  • required: bool Indicate that this option must be provided on the command line. Conflicts with the default property.
  • default: any Specify the default value for the option. Conflicts with the required property.
  • hidden: bool Hide the option from the usage help message, but otherwise works fine. Sometimes useful for developer options that user should not play with.
  • repeat: bool Indicate that this option can be repeated. Not applicable for COUNTER and STRINGMAP types. This will turn the option value into an array that you can iterate over. So --day Monday --day Thursday can be used like {{range options.day}}Day: {{.}}{{end}}
  • enum: string list Used with the type: ENUM property, it is a list of strings values that represent the set of possible values the option accepts.
Arguments

These are possible keys under the command args property:

  • name: string [required] Name of the option, so name: ISSUE will show in the usasge as jira <command> ISSUE. This also represents the name of the argument to be used in the script template, so {{args.ISSUE}}.
  • help: string The help messsage displayed in usage for the argument.
  • type: string: The type of the argumemnt, can be one of these values: BOOL, COUNTER, ENUM, FLOAT32, FLOAT64, INT8, INT16, INT32, INT64, INT, STRING, STRINGMAP, UINT8, UINT16, UINT32, UINT64 and UINT. Most of these are primitive data types an should be self-explanitory. The default type is STRING. There are some special types:
    • COUNTER will be an integer type that increments each the argument is provided So something like jira <command> ISSUE-12 ISSUE-23 will results in {{args.ISSUE}} of 2.
    • ENUM type is used with the enum property. The raw type is a string and must be one of the values listed in the enum property.
    • STRINGMAP is a string => string map with the format of KEY=VALUE. So jira <command> foo=bar bin=baz along with a name: OVERRIDE property will allow for {{args.OVERRIDE.foo}} to be bar and {{args.OVERRIDE.bin}} to be baz.
  • required: bool Indicate that this argument must be provided on the command line. Conflicts with the default property.
  • default: any Specify the default value for the argument. Conflicts with the required property.
  • repeat: bool Indicate that this argument can be repeated. Not applicable for COUNTER and STRINGMAP types. This will turn the template value into an array that you can iterate over. So jira <command> ISSUE-12 ISSUE-23 can be used like {{range args.ISSUE}}Issue: {{.}}{{end}}
  • enum: string list Used with the type: ENUM property, it is a list of strings values that represent the set of possible values for the argument.
Script Template

The script property is a template that whould produce /bin/sh compatible syntax after the template has been processed. There are 2 key template functions {{args}} and {{options}} that return the parsed arguments and option flags as a map.

To demonstrate how you might use args and options here is a custom-test command:

custom-commands:
  - name: custom-test
    help: Testing the custom commands
    options:
      - name: abc
        short: a
        default: default
      - name: day
        type: ENUM
        enum:
          - Monday
          - Tuesday
          - Wednesday
          - Thursday
          - Friday
        required: true
    args:
      - name: ARG
        required: true
      - name: MORE
        repeat: true
    script: |
      echo COMMAND {{args.ARG}} --abc {{options.abc}} --day {{options.day}} {{range $more := args.MORE}}{{$more}} {{end}}

Then to run it:

$ jira custom-test
ERROR Invalid Usage: required flag --day not provided

$ jira custom-test --day Sunday
ERROR Invalid Usage: enum value must be one of Monday,Tuesday,Wednesday,Thursday,Friday, got 'Sunday'

$ jira custom-test --day Tuesday
ERROR Invalid Usage: required argument 'ARG' not provided

$ jira custom-test --day Tuesday arg1
COMMAND arg1 --abc default --day Tuesday

$ jira custom-test --day Tuesday arg1 more1 more2 more3
COMMAND arg1 --abc default --day Tuesday more1 more2 more3

$ jira custom-test --day Tuesday arg1 more1 more2 more3 --abc non-default
COMMAND arg1 --abc non-default --day Tuesday more1 more2 more3

$ jira custom-test --day Tuesday arg1 more1 more2 more3 -a short-non-default
COMMAND arg1 --abc short-non-default --day Tuesday more1 more2 more3

The script has access to all the environment variables that are in your current environment plus those that jira will set. jira sets environment variables for each config property it has parsed from .jira.d/config.yml or the command configs at .jira.d/<command>.yml. It might be useful to see all environment variables that jira is producing, so here is a simple custom command to list them:

custom-commands:
  - name: env
    help: print the JIRA environment variables available to custom commands
    script: |
      env | grep JIRA

You could use the environment variables automatically, so if your .jira.d/config.yml looks something like this:

project: PROJECT
custom-commands:
  - name: print-project
    help: print the name of the configured project
    script: "echo $JIRA_PROJECT"
Examples
  • jira mine for listing issues assigned to you
custom-commands:
  - name: mine
    help: display issues assigned to me
    script: |-
      if [ -n "$JIRA_PROJECT" ]; then
          # if `project: ...` configured just list the issues for current project
          {{jira}} list --template table --query "resolution = unresolved and assignee=currentuser() and project = $JIRA_PROJECT ORDER BY priority asc, created"
      else
          # otherwise list issues for all project
          {{jira}} list --template table --query "resolution = unresolved and assignee=currentuser() ORDER BY priority asc, created"
      fi
  • jira sprint for listing issues in your current sprint
custom-commands:
  - name: sprint
    help: display issues for active sprint
    script: |-
      if [ -n "$JIRA_PROJECT" ]; then
          # if `project: ...` configured just list the issues for current project
          {{jira}} list --template table --query "sprint in openSprints() and type != epic and resolution = unresolved and project=$JIRA_PROJECT ORDER BY rank asc, created"
      else
          # otherwise list issues for all project
          echo "\"project: ...\" configuration missing from .jira.d/config.yml"
      fi
Editing

When you run command like jira edit it will open up your favorite editor with the templatized output so you can quickly edit. When the editor closes go-jira will submit the completed form. The order which go-jira attempts to determine your prefered editor is:

  • editor property in any config.yml file
  • JIRA_EDITOR environment variable
  • EDITOR environment variable
  • vim
Templates

go-jira has the ability to customize most output (and editor input) via templates. There are default templates available for all operations, which may or may not work for your actual jira implementation. Jira is endlessly customizable, so it is hard to provide default templates that will work for all issue types.

When running a command like jira edit it will look through the current directory hierarchy trying to find a file that matches .jira.d/templates/edit, if found it will use that file as the template, otherwise it will use the default edit template hard-coded into go-jira. You can export the default hard-coded templates with jira export-templates which will write them to ~/.jira.d/templates/.

Writing/Editing Templates

First the basic templating functionality is defined by the Go language 'text/template' library. The library reference documentation can be found here, and there is a good primer document here. go-jira also provides a few extra helper functions to make it a bit easlier to format the data, those functions are defined here.

Knowing what data and fields are available to any given template is not obvious. The easiest approach to determine what is available is to use the debug template on any given operation. For eample to find out what is available to the "view" templates, you can use:

jira view GOJIRA-321 -t debug

This will print out the data in JSON format that is available to the template. You can do this for any other operation, like "list":

jira list -t debug
Authentication

By default go-jira will prompt for a password automatically when get a response header from the Jira service that indicates you do not have an active session (ie the X-Ausername header is set to anonymous). Then after authentication we cache the cloud.session.token cookie returned by the service session login api and reuse that on subsequent requests. Typically this cookie will be valid for several hours (depending on the service configuration). To automatically securely store your password for easy reuse by jira You can enable a password-source via .jira.d/config.yml with possible values of keyring or pass.

keyring password source

On OSX and Linux there are a few keyring providers that go-jira can use (via this golang module). To integrate go-jira with a supported keyring just add this configuration to $HOME/.jira.d/config.yml:

password-source: keyring

After setting this and issuing a jira login, your credentials will be stored in your platform's backend (e.g. Keychain for Mac OS X) automatically. Subsequent operations, like a jira ls, should automatically login.

pass password source

An alternative to the keyring password source is the pass tool (documentation here). This uses gpg to encrypt/decrypt passwords on demand and by using gpg-agent you can cache the gpg credentials for a period of time so you will not be prompted repeatedly for decrypting the passwords. The advantage over the keyring integration is that pass can be used on more platforms than OSX and Linux, although it does require more setup. To use pass for password storage and retrieval via go-jira just add this configuration to $HOME/.jira.d/config.yml:

password-source: pass

This assumes you have already setup pass correctly on your system. Specifically you will need to have created a gpg key like this:

$ gpg --gen-key

Then you will need the GPG Key ID you want associated with pass. First list the available keys:

$ gpg --list-keys
/home/gojira/.gnupg/pubring.gpg
-------------------------------------------------
pub   2048R/A307D709 2016-12-18
uid                  Go Jira <gojira@example.com>
sub   2048R/F9A047B8 2016-12-18

Then initialize the pass tool to use the correct key:

$ pass init "Go Jira <gojira@example.com>"

You probably want to setup gpg-agent so that you dont have to type in your gpg passphrase all the time. You can get gpg-agent to automatically start by adding something like this to your $HOME/.bashrc

if [ -f $HOME/.gpg-agent-info ]; then
    . $HOME/.gpg-agent-info
    export GPG_AGENT_INFO
fi

if [ ! -f $HOME/.gpg-agent.conf ]; then
  cat <<EOM >$HOME/.gpg-agent.conf
default-cache-ttl 604800
max-cache-ttl 604800
default-cache-ttl-ssh 604800
max-cache-ttl-ssh 604800
EOM
fi

if [ -n "${GPG_AGENT_INFO}" ]; then
    nc  -U "${GPG_AGENT_INFO%%:*}" >/dev/null </dev/null
    if [ ! -S "${GPG_AGENT_INFO%%:*}" -o $? != 0 ]; then
        # set passphrase cache so I only have to type my passphrase once a day
        eval $(gpg-agent --options $HOME/.gpg-agent.conf --daemon --write-env-file $HOME/.gpg-agent-info --use-standard-socket --log-file $HOME/tmp/gpg-agent.log --verbose)
    fi
fi
export GPG_TTY=$(tty)

Usage

usage: jira [<flags>] <command> [<args> ...]

Jira Command Line Interface

Flags:
      --help                 Show context-sensitive help (also try --help-long and --help-man).
  -v, --verbose ...          Increase verbosity for debugging
  -e, --endpoint=ENDPOINT    Base URI to use for Jira
  -k, --insecure             Disable TLS certificate verification
  -Q, --quiet                Suppress output to console
      --unixproxy=UNIXPROXY  Path for a unix-socket proxy
  -u, --user=USER            Login name used for authentication with Jira service

Commands:
  help [<command>...]
    Show help.


  version
    Prints version


  login
    Attempt to login into jira server


  logout
    Deactivate sesssion with Jira server


  list [<flags>]
    Prints list of issues for given search criteria

    -t, --template=TEMPLATE        Template to use for output
        --gjq=GJQ                  GJSON Query to filter output, see https://goo.gl/iaYwJ5
    -a, --assignee=ASSIGNEE        User assigned the issue
    -c, --component=COMPONENT      Component to search for
    -i, --issuetype=ISSUETYPE      Issue type to search for
    -l, --limit=LIMIT              Maximum number of results to return in search
    -p, --project=PROJECT          Project to search for
    -n, --named-query=NAMED-QUERY  The name of a query in the `queries` configuration
    -q, --query=QUERY              Jira Query Language (JQL) expression for the search
    -f, --queryfields=QUERYFIELDS  Fields that are used in "list" template
    -r, --reporter=REPORTER        Reporter to search for
    -S, --status=STATUS            Filter on issue status
    -s, --sort=SORT                Sort order to return
    -w, --watcher=WATCHER          Watcher to search for

  view [<flags>] <ISSUE>
    Prints issue details

    -b, --browse                 Open issue(s) in browser after operation
    -t, --template=TEMPLATE      Template to use for output
        --gjq=GJQ                GJSON Query to filter output, see https://goo.gl/iaYwJ5
        --expand=EXPAND ...      field to expand for the issue
        --field=FIELD ...        field to return for the issue
        --property=PROPERTY ...  property to return for issue

  create [<flags>]
    Create issue

    -b, --browse                 Open issue(s) in browser after operation
        --editor=EDITOR          Editor to use
    -t, --template=TEMPLATE      Template to use for output
        --noedit                 Disable opening the editor
    -p, --project=PROJECT        project to create issue in
    -i, --issuetype=ISSUETYPE    issuetype in to create
    -m, --comment=COMMENT        Comment message for issue
    -o, --override=OVERRIDE ...  Set issue property
        --saveFile=SAVEFILE      Write issue as yaml to file

  edit [<flags>] [<ISSUE>]
    Edit issue details

    -b, --browse                   Open issue(s) in browser after operation
        --editor=EDITOR            Editor to use
    -t, --template=TEMPLATE        Template to use for output
        --noedit                   Disable opening the editor
    -n, --named-query=NAMED-QUERY  The name of a query in the `queries` configuration
    -q, --query=QUERY              Jira Query Language (JQL) expression for the search to edit multiple issues
    -m, --comment=COMMENT          Comment message for issue
    -o, --override=OVERRIDE ...    Set issue property

  comment [<flags>] [<ISSUE>]
    Add comment to issue

    -b, --browse             Open issue(s) in browser after operation
        --editor=EDITOR      Editor to use
    -t, --template=TEMPLATE  Template to use for output
        --noedit             Disable opening the editor
    -m, --comment=COMMENT    Comment message for issue

  epic create [<flags>]
    Create Epic

    -b, --browse                 Open issue(s) in browser after operation
        --editor=EDITOR          Editor to use
    -t, --template=TEMPLATE      Template to use for output
        --noedit                 Disable opening the editor
    -p, --project=PROJECT        project to create epic in
    -n, --epic-name=EPIC-NAME    Epic Name
    -m, --comment=COMMENT        Comment message for epic
    -o, --override=OVERRIDE ...  Set epic property
        --saveFile=SAVEFILE      Write epic as yaml to file

  epic list [<flags>] <EPIC>
    Prints list of issues for an epic with optional search criteria

    -t, --template=TEMPLATE        Template to use for output
        --gjq=GJQ                  GJSON Query to filter output, see https://goo.gl/iaYwJ5
    -a, --assignee=ASSIGNEE        User assigned the issue
    -c, --component=COMPONENT      Component to search for
    -i, --issuetype=ISSUETYPE      Issue type to search for
    -l, --limit=LIMIT              Maximum number of results to return in search
    -p, --project=PROJECT          Project to search for
    -n, --named-query=NAMED-QUERY  The name of a query in the `queries` configuration
    -q, --query=QUERY              Jira Query Language (JQL) expression for the search
    -f, --queryfields=QUERYFIELDS  Fields that are used in "list" template
    -r, --reporter=REPORTER        Reporter to search for
    -S, --status=STATUS            Filter on issue status
    -s, --sort=SORT                Sort order to return
    -w, --watcher=WATCHER          Watcher to search for

  epic add <EPIC> <ISSUE>...
    Add issues to Epic


  epic remove <ISSUE>...
    Remove issues from Epic


  worklog list [<flags>] <ISSUE>
    Prints the worklog data for given issue

    -b, --browse             Open issue(s) in browser after operation
    -t, --template=TEMPLATE  Template to use for output
        --gjq=GJQ            GJSON Query to filter output, see https://goo.gl/iaYwJ5

  worklog add [<flags>] <ISSUE>
    Add a worklog to an issue

    -b, --browse                 Open issue(s) in browser after operation
        --editor=EDITOR          Editor to use
    -t, --template=TEMPLATE      Template to use for output
        --noedit                 Disable opening the editor
    -m, --comment=COMMENT        Comment message for worklog
    -T, --time-spent=TIME-SPENT  Time spent working on issue
    -S, --started=STARTED        Time you started work

  fields [<flags>]
    Prints all fields, both System and Custom

    -t, --template=TEMPLATE  Template to use for output
        --gjq=GJQ            GJSON Query to filter output, see https://goo.gl/iaYwJ5

  createmeta [<flags>]
    View 'create' metadata

    -t, --template=TEMPLATE    Template to use for output
        --gjq=GJQ              GJSON Query to filter output, see https://goo.gl/iaYwJ5
    -p, --project=PROJECT      project to fetch create metadata
    -i, --issuetype=ISSUETYPE  issuetype in project to fetch create metadata

  editmeta [<flags>] <ISSUE>
    View 'edit' metadata

    -b, --browse             Open issue(s) in browser after operation
    -t, --template=TEMPLATE  Template to use for output
        --gjq=GJQ            GJSON Query to filter output, see https://goo.gl/iaYwJ5

  subtask [<flags>] [<ISSUE>]
    Subtask issue

    -b, --browse                 Open issue(s) in browser after operation
        --editor=EDITOR          Editor to use
    -t, --template=TEMPLATE      Template to use for output
        --noedit                 Disable opening the editor
    -p, --project=PROJECT        project to subtask issue in
    -m, --comment=COMMENT        Comment message for issue
    -o, --override=OVERRIDE ...  Set issue property

  dup [<flags>] <DUPLICATE> <ISSUE>
    Mark issues as duplicate

    -b, --browse             Open issue(s) in browser after operation
        --editor=EDITOR      Editor to use
    -t, --template=TEMPLATE  Template to use for output
    -m, --comment=COMMENT    Comment message when marking issue as duplicate

  block [<flags>] <BLOCKER> <ISSUE>
    Mark issues as blocker

    -b, --browse             Open issue(s) in browser after operation
        --editor=EDITOR      Editor to use
    -t, --template=TEMPLATE  Template to use for output
    -m, --comment=COMMENT    Comment message when marking issue as blocker

  issuelink [<flags>] <OUTWARDISSUE> <ISSUELINKTYPE> <INWARDISSUE>
    Link two issues

    -b, --browse             Open issue(s) in browser after operation
        --editor=EDITOR      Editor to use
    -t, --template=TEMPLATE  Template to use for output
    -m, --comment=COMMENT    Comment message when linking issue

  issuelinktypes [<flags>]
    Show the issue link types

    -t, --template=TEMPLATE  Template to use for output
        --gjq=GJQ            GJSON Query to filter output, see https://goo.gl/iaYwJ5

  transition [<flags>] <TRANSITION> <ISSUE>
    Transition issue to given state

    -b, --browse                 Open issue(s) in browser after operation
    -t, --template=TEMPLATE      Template to use for output
        --noedit                 Disable opening the editor
    -m, --comment=COMMENT        Comment message for issue
    -o, --override=OVERRIDE ...  Set issue property

  transitions [<flags>] <ISSUE>
    List valid issue transitions

    -b, --browse             Open issue(s) in browser after operation
    -t, --template=TEMPLATE  Template to use for output
        --gjq=GJQ            GJSON Query to filter output, see https://goo.gl/iaYwJ5

  transmeta [<flags>] <ISSUE>
    List valid issue transitions

    -b, --browse             Open issue(s) in browser after operation
    -t, --template=TEMPLATE  Template to use for output
        --gjq=GJQ            GJSON Query to filter output, see https://goo.gl/iaYwJ5

  close [<flags>] <ISSUE>
    Transition issue to close state

    -b, --browse                 Open issue(s) in browser after operation
    -t, --template=TEMPLATE      Template to use for output
        --noedit                 Disable opening the editor
    -m, --comment=COMMENT        Comment message for issue
    -o, --override=OVERRIDE ...  Set issue property

  acknowledge [<flags>] <ISSUE>
    Transition issue to acknowledge state

    -b, --browse                 Open issue(s) in browser after operation
    -t, --template=TEMPLATE      Template to use for output
        --noedit                 Disable opening the editor
    -m, --comment=COMMENT        Comment message for issue
    -o, --override=OVERRIDE ...  Set issue property

  reopen [<flags>] <ISSUE>
    Transition issue to reopen state

    -b, --browse                 Open issue(s) in browser after operation
    -t, --template=TEMPLATE      Template to use for output
        --noedit                 Disable opening the editor
    -m, --comment=COMMENT        Comment message for issue
    -o, --override=OVERRIDE ...  Set issue property

  resolve [<flags>] <ISSUE>
    Transition issue to resolve state

    -b, --browse                 Open issue(s) in browser after operation
    -t, --template=TEMPLATE      Template to use for output
        --noedit                 Disable opening the editor
    -m, --comment=COMMENT        Comment message for issue
    -o, --override=OVERRIDE ...  Set issue property

  start [<flags>] <ISSUE>
    Transition issue to start state

    -b, --browse                 Open issue(s) in browser after operation
    -t, --template=TEMPLATE      Template to use for output
        --noedit                 Disable opening the editor
    -m, --comment=COMMENT        Comment message for issue
    -o, --override=OVERRIDE ...  Set issue property

  stop [<flags>] <ISSUE>
    Transition issue to stop state

    -b, --browse                 Open issue(s) in browser after operation
    -t, --template=TEMPLATE      Template to use for output
        --noedit                 Disable opening the editor
    -m, --comment=COMMENT        Comment message for issue
    -o, --override=OVERRIDE ...  Set issue property

  todo [<flags>] <ISSUE>
    Transition issue to To Do state

    -b, --browse                 Open issue(s) in browser after operation
    -t, --template=TEMPLATE      Template to use for output
        --noedit                 Disable opening the editor
    -m, --comment=COMMENT        Comment message for issue
    -o, --override=OVERRIDE ...  Set issue property

  backlog [<flags>] <ISSUE>
    Transition issue to Backlog state

    -b, --browse                 Open issue(s) in browser after operation
    -t, --template=TEMPLATE      Template to use for output
        --noedit                 Disable opening the editor
    -m, --comment=COMMENT        Comment message for issue
    -o, --override=OVERRIDE ...  Set issue property

  done [<flags>] <ISSUE>
    Transition issue to Done state

    -b, --browse                 Open issue(s) in browser after operation
    -t, --template=TEMPLATE      Template to use for output
        --noedit                 Disable opening the editor
    -m, --comment=COMMENT        Comment message for issue
    -o, --override=OVERRIDE ...  Set issue property

  in-progress [<flags>] <ISSUE>
    Transition issue to Progress state

    -b, --browse                 Open issue(s) in browser after operation
    -t, --template=TEMPLATE      Template to use for output
        --noedit                 Disable opening the editor
    -m, --comment=COMMENT        Comment message for issue
    -o, --override=OVERRIDE ...  Set issue property

  vote [<flags>] [<ISSUE>]
    Vote up/down an issue

    -b, --browse  Open issue(s) in browser after operation
    -d, --down    downvote the issue

  rank [<flags>] <FIRST-ISSUE> <after|before> <SECOND-ISSUE>
    Mark issues as blocker

    -b, --browse  Open issue(s) in browser after operation

  watch [<flags>] <ISSUE> [<WATCHER>]
    Add/Remove watcher to issue

    -b, --browse  Open issue(s) in browser after operation
    -r, --remove  remove watcher from issue

  labels add [<flags>] <ISSUE> <LABEL>...
    Add labels to an issue

    -b, --browse  Open issue(s) in browser after operation

  labels set [<flags>] <ISSUE> <LABEL>...
    Set labels on an issue

    -b, --browse  Open issue(s) in browser after operation

  labels remove [<flags>] <ISSUE> <LABEL>...
    Remove labels from an issue

    -b, --browse  Open issue(s) in browser after operation

  take [<flags>] <ISSUE> [<ASSIGNEE>]
    Assign issue to yourself

    -b, --browse   Open issue(s) in browser after operation
        --default  use default user for assignee

  assign [<flags>] <ISSUE> [<ASSIGNEE>]
    Assign user to issue

    -b, --browse   Open issue(s) in browser after operation
        --default  use default user for assignee

  unassign [<flags>] <ISSUE> [<ASSIGNEE>]
    Unassign an issue

    -b, --browse   Open issue(s) in browser after operation
        --default  use default user for assignee

  component add [<flags>]
    Add component

        --editor=EDITOR            Editor to use
    -t, --template=TEMPLATE        Template to use for output
        --noedit                   Disable opening the editor
    -p, --project=PROJECT          project to create component in
    -n, --name=NAME                name of component
    -d, --description=DESCRIPTION  description of component
    -l, --lead=LEAD                person that acts as lead for component

  components [<flags>]
    Show components for a project

    -t, --template=TEMPLATE  Template to use for output
        --gjq=GJQ            GJSON Query to filter output, see https://goo.gl/iaYwJ5
    -p, --project=PROJECT    project to list components

  issuetypes [<flags>]
    Show issue types for a project

    -t, --template=TEMPLATE  Template to use for output
        --gjq=GJQ            GJSON Query to filter output, see https://goo.gl/iaYwJ5
    -p, --project=PROJECT    project to list issueTypes

  attach create [<flags>] <ISSUE> [<ATTACHMENT>]
    Attach file to issue

    -b, --browse             Open issue(s) in browser after operation
        --saveFile=SAVEFILE  Write attachment information as yaml to file
    -f, --filename=FILENAME  Filename to use for attachment

  attach list [<flags>] <ISSUE>
    Prints issue details

    -b, --browse             Open issue(s) in browser after operation
    -t, --template=TEMPLATE  Template to use for output

  attach get [<flags>] [<ATTACHMENT-ID>]
    Fetch attachment

    -o, --output=OUTPUT  Write attachment to specified file name, '-' for stdout

  attach remove [<ATTACHMENT-ID>]
    Delete attachment


  export-templates [<flags>]
    Export templates for customizations

    -t, --template=TEMPLATE  Template to export
    -d, --dir=DIR            directory to write tempates to

  unexport-templates [<flags>]
    Remove unmodified exported templates

    -t, --template=TEMPLATE  Template to export
    -d, --dir=DIR            directory to write tempates to

  browse <ISSUE>
    Open issue in browser


  request [<flags>] <API> [<JSON>]
    Open issue in requestr

    -t, --template=TEMPLATE  Template to use for output
        --gjq=GJQ            GJSON Query to filter output, see https://goo.gl/iaYwJ5
    -M, --method=METHOD      HTTP request method to use

Documentation

Index

Constants

View Source 
const VERSION = "1.0.8"

Variables

This section is empty.

Functions

func AddIssueWorklog added in v1.0.0 

func AddIssueWorklog(ua HttpClient, endpoint string, issue string, wp WorklogProvider) (*jiradata.Worklog, error)

func CreateComponent added in v1.0.0 

func CreateComponent(ua HttpClient, endpoint string, cp ComponentProvider) (*jiradata.Component, error)

func CreateIssue added in v1.0.0 

func CreateIssue(ua HttpClient, endpoint string, iup IssueUpdateProvider) (*jiradata.IssueCreateResponse, error)

func DeleteSession added in v1.0.0 

func DeleteSession(ua HttpClient, endpoint string) error

func EditIssue added in v1.0.0 

func EditIssue(ua HttpClient, endpoint string, issue string, iup IssueUpdateProvider) error

func EpicAddIssues added in v1.0.7 

func EpicAddIssues(ua HttpClient, endpoint string, epic string, eip EpicIssuesProvider) error

func EpicRemoveIssues added in v1.0.7 

func EpicRemoveIssues(ua HttpClient, endpoint string, eip EpicIssuesProvider) error

func EpicSearch added in v1.0.7 

func EpicSearch(ua HttpClient, endpoint string, epic string, sp SearchProvider) (*jiradata.SearchResults, error)

func GetAttachment added in v1.0.8 

func GetAttachment(ua HttpClient, endpoint string, id string) (*jiradata.Attachment, error)

func GetFields added in v1.0.0 

func GetFields(ua HttpClient, endpoint string) ([]jiradata.Field, error)

func GetIssue added in v1.0.0 

func GetIssue(ua HttpClient, endpoint string, issue string, iqg IssueQueryProvider) (*jiradata.Issue, error)

func GetIssueCreateMetaIssueType added in v1.0.0 

func GetIssueCreateMetaIssueType(ua HttpClient, endpoint string, projectKey, issueTypeName string) (*jiradata.IssueType, error)

func GetIssueCreateMetaProject added in v1.0.0 

func GetIssueCreateMetaProject(ua HttpClient, endpoint string, projectKey string) (*jiradata.CreateMetaProject, error)

func GetIssueEditMeta added in v1.0.0 

func GetIssueEditMeta(ua HttpClient, endpoint string, issue string) (*jiradata.EditMeta, error)

func GetIssueLinkTypes added in v1.0.0 

func GetIssueLinkTypes(ua HttpClient, endpoint string) (*jiradata.IssueLinkTypes, error)

func GetIssueTransitions added in v1.0.0 

func GetIssueTransitions(ua HttpClient, endpoint string, issue string) (*jiradata.TransitionsMeta, error)

func GetIssueWorklog added in v1.0.0 

func GetIssueWorklog(ua HttpClient, endpoint string, issue string) (*jiradata.Worklogs, error)

https://docs.atlassian.com/jira/REST/cloud/#api/2/issue/{issueIdOrKey}/worklog-getIssueWorklog

func GetProjectComponents added in v1.0.0 

func GetProjectComponents(ua HttpClient, endpoint string, project string) (*jiradata.Components, error)

func GetSession added in v1.0.0 

func GetSession(ua HttpClient, endpoint string) (*jiradata.CurrentUser, error)

func IssueAddComment added in v1.0.0 

func IssueAddComment(ua HttpClient, endpoint string, issue string, cp CommentProvider) (*jiradata.Comment, error)

func IssueAddVote added in v1.0.0 

func IssueAddVote(ua HttpClient, endpoint string, issue string) error

func IssueAddWatcher added in v1.0.0 

func IssueAddWatcher(ua HttpClient, endpoint string, issue, user string) error

func IssueAssign added in v1.0.0 

func IssueAssign(ua HttpClient, endpoint string, issue, name string) error

func IssueAttachFile added in v1.0.8 

func IssueAttachFile(ua HttpClient, endpoint string, issue, filename string, contents io.Reader) (*jiradata.ListOfAttachment, error)

func IssueRemoveVote added in v1.0.0 

func IssueRemoveVote(ua HttpClient, endpoint string, issue string) error

func IssueRemoveWatcher added in v1.0.0 

func IssueRemoveWatcher(ua HttpClient, endpoint string, issue, user string) error

func LinkIssues added in v1.0.0 

func LinkIssues(ua HttpClient, endpoint string, lip LinkIssueProvider) error

func NewSession added in v1.0.0 

func NewSession(ua HttpClient, endpoint string, ap AuthProvider) (*jiradata.AuthSuccess, error)

func RankIssues added in v1.0.0 

func RankIssues(ua HttpClient, endpoint string, rrp RankRequestProvider) error

func RemoveAttachment added in v1.0.8 

func RemoveAttachment(ua HttpClient, endpoint string, id string) error
func Search(ua HttpClient, endpoint string, sp SearchProvider) (*jiradata.SearchResults, error)

func TransitionIssue added in v1.0.0 

func TransitionIssue(ua HttpClient, endpoint string, issue string, iup IssueUpdateProvider) error

Types

type AuthOptions added in v1.0.0 

type AuthOptions struct {
	Username string
	Password string
}

func (*AuthOptions) AuthParams added in v1.0.0 

func (a *AuthOptions) AuthParams() *jiradata.AuthParams

type AuthProvider added in v1.0.0 

type AuthProvider interface {
	ProvideAuthParams() *jiradata.AuthParams
}

type CommentProvider added in v1.0.0 

type CommentProvider interface {
	ProvideComment() *jiradata.Comment
}

type ComponentProvider added in v1.0.0 

type ComponentProvider interface {
	ProvideComponent() *jiradata.Component
}

type EpicIssuesProvider added in v1.0.7 

type EpicIssuesProvider interface {
	ProvideEpicIssues() *jiradata.EpicIssues
}

type HttpClient added in v1.0.0 

type HttpClient interface {
	Delete(url string) (*http.Response, error)
	Do(*http.Request) (*http.Response, error)
	GetJSON(url string) (*http.Response, error)
	Post(url, bodyType string, body io.Reader) (*http.Response, error)
	Put(url, bodyType string, body io.Reader) (*http.Response, error)
}

type IssueOptions added in v1.0.0 

type IssueOptions struct {
	Fields        []string `json:"fields,omitempty" yaml:"fields,omitempty"`
	Expand        []string `json:"expand,omitempty" yaml:"expand,omitempty"`
	Properties    []string `json:"properties,omitempty" yaml:"properties,omitempty"`
	FieldsByKeys  bool     `json:"fieldsByKeys,omitempty" yaml:"fieldsByKeys,omitempty"`
	UpdateHistory bool     `json:"updateHistory,omitempty" yaml:"updateHistory,omitempty"`
}

func (*IssueOptions) ProvideIssueQueryString added in v1.0.0 

func (o *IssueOptions) ProvideIssueQueryString() string

type IssueQueryProvider added in v1.0.0 

type IssueQueryProvider interface {
	ProvideIssueQueryString() string
}

type IssueUpdateProvider added in v1.0.0 

type IssueUpdateProvider interface {
	ProvideIssueUpdate() *jiradata.IssueUpdate
}

type Jira added in v1.0.0 

type Jira struct {
	Endpoint string     `json:"endpoint,omitempty" yaml:"endpoint,omitempty"`
	UA       HttpClient `json:"-" yaml:"-"`
}

func NewJira added in v1.0.0 

func NewJira(endpoint string) *Jira

func (*Jira) AddIssueWorklog added in v1.0.0 

func (j *Jira) AddIssueWorklog(issue string, wp WorklogProvider) (*jiradata.Worklog, error)

https://docs.atlassian.com/jira/REST/cloud/#api/2/issue/{issueIdOrKey}/worklog-addWorklog

func (*Jira) CreateComponent added in v1.0.0 

func (j *Jira) CreateComponent(cp ComponentProvider) (*jiradata.Component, error)

https://docs.atlassian.com/jira/REST/cloud/#api/2/component-createComponent

func (*Jira) CreateIssue added in v1.0.0 

func (j *Jira) CreateIssue(iup IssueUpdateProvider) (*jiradata.IssueCreateResponse, error)

https://docs.atlassian.com/jira/REST/cloud/#api/2/issue-createIssue

func (*Jira) DeleteSession added in v1.0.0 

func (j *Jira) DeleteSession() error

https://docs.atlassian.com/jira/REST/cloud/#auth/1/session-logout

func (*Jira) EditIssue added in v1.0.0 

func (j *Jira) EditIssue(issue string, iup IssueUpdateProvider) error

https://docs.atlassian.com/jira/REST/cloud/#api/2/issue-editIssue

func (*Jira) EpicAddIssues added in v1.0.7 

func (j *Jira) EpicAddIssues(epic string, eip EpicIssuesProvider) error

https://docs.atlassian.com/jira-software/REST/latest/#agile/1.0/epic-moveIssuesToEpic

func (*Jira) EpicRemoveIssues added in v1.0.7 

func (j *Jira) EpicRemoveIssues(eip EpicIssuesProvider) error

https://docs.atlassian.com/jira-software/REST/latest/#agile/1.0/epic-removeIssuesFromEpic

func (*Jira) EpicSearch added in v1.0.7 

func (j *Jira) EpicSearch(epic string, sp SearchProvider) (*jiradata.SearchResults, error)

https://docs.atlassian.com/jira-software/REST/latest/#agile/1.0/epic-getIssuesForEpic

func (*Jira) GetAttachment added in v1.0.8 

func (j *Jira) GetAttachment(id string) (*jiradata.Attachment, error)

https://docs.atlassian.com/jira/REST/cloud/#api/2/attachment-getAttachment

func (*Jira) GetFields added in v1.0.0 

func (j *Jira) GetFields() ([]jiradata.Field, error)

https://docs.atlassian.com/jira/REST/cloud/#api/2/field-getFields

func (*Jira) GetIssue added in v1.0.0 

func (j *Jira) GetIssue(issue string, iqg IssueQueryProvider) (*jiradata.Issue, error)

https://docs.atlassian.com/jira/REST/cloud/#api/2/issue-getIssue

func (*Jira) GetIssueCreateMetaIssueType added in v1.0.0 

func (j *Jira) GetIssueCreateMetaIssueType(projectKey, issueTypeName string) (*jiradata.IssueType, error)

https://docs.atlassian.com/jira/REST/cloud/#api/2/issue-getCreateIssueMeta

func (*Jira) GetIssueCreateMetaProject added in v1.0.0 

func (j *Jira) GetIssueCreateMetaProject(projectKey string) (*jiradata.CreateMetaProject, error)

https://docs.atlassian.com/jira/REST/cloud/#api/2/issue-getCreateIssueMeta

func (*Jira) GetIssueEditMeta added in v1.0.0 

func (j *Jira) GetIssueEditMeta(issue string) (*jiradata.EditMeta, error)

https://docs.atlassian.com/jira/REST/cloud/#api/2/issue-getEditIssueMeta

func (*Jira) GetIssueLinkTypes added in v1.0.0 

func (j *Jira) GetIssueLinkTypes() (*jiradata.IssueLinkTypes, error)

https://docs.atlassian.com/jira/REST/cloud/#api/2/issueLinkType-getIssueLinkTypes

func (*Jira) GetIssueTransitions added in v1.0.0 

func (j *Jira) GetIssueTransitions(issue string) (*jiradata.TransitionsMeta, error)

https://docs.atlassian.com/jira/REST/cloud/#api/2/issue-getTransitions

func (*Jira) GetIssueWorklog added in v1.0.0 

func (j *Jira) GetIssueWorklog(issue string) (*jiradata.Worklogs, error)

func (*Jira) GetProjectComponents added in v1.0.0 

func (j *Jira) GetProjectComponents(project string) (*jiradata.Components, error)

https://docs.atlassian.com/jira/REST/cloud/#api/2/project-getProjectComponents

func (*Jira) GetSession added in v1.0.0 

func (j *Jira) GetSession() (*jiradata.CurrentUser, error)

https://docs.atlassian.com/jira/REST/cloud/#auth/1/session-currentUser

func (*Jira) IssueAddComment added in v1.0.0 

func (j *Jira) IssueAddComment(issue string, cp CommentProvider) (*jiradata.Comment, error)

https://docs.atlassian.com/jira/REST/cloud/#api/2/issue/{issueIdOrKey}/comment-addComment

func (*Jira) IssueAddVote added in v1.0.0 

func (j *Jira) IssueAddVote(issue string) error

https://docs.atlassian.com/jira/REST/cloud/#api/2/issue-addVote

func (*Jira) IssueAddWatcher added in v1.0.0 

func (j *Jira) IssueAddWatcher(issue, user string) error

https://docs.atlassian.com/jira/REST/cloud/#api/2/issue-addWatcher

func (*Jira) IssueAssign added in v1.0.0 

func (j *Jira) IssueAssign(issue, name string) error

https://docs.atlassian.com/jira/REST/cloud/#api/2/issue-assign

func (*Jira) IssueAttachFile added in v1.0.8 

func (j *Jira) IssueAttachFile(issue, filename string, contents io.Reader) (*jiradata.ListOfAttachment, error)

https://docs.atlassian.com/jira/REST/cloud/#api/2/issue/{issueIdOrKey}/attachments-addAttachment

func (*Jira) IssueRemoveVote added in v1.0.0 

func (j *Jira) IssueRemoveVote(issue string) error

https://docs.atlassian.com/jira/REST/cloud/#api/2/issue-removeVote

func (*Jira) IssueRemoveWatcher added in v1.0.0 

func (j *Jira) IssueRemoveWatcher(issue, user string) error

https://docs.atlassian.com/jira/REST/cloud/#api/2/issue-addWatcher

func (*Jira) LinkIssues added in v1.0.0 

func (j *Jira) LinkIssues(lip LinkIssueProvider) error

https://docs.atlassian.com/jira/REST/cloud/#api/2/issueLink-linkIssues

func (*Jira) NewSession added in v1.0.0 

func (j *Jira) NewSession(ap AuthProvider) (*jiradata.AuthSuccess, error)

https://docs.atlassian.com/jira/REST/cloud/#auth/1/session-login

func (*Jira) RankIssues added in v1.0.0 

func (j *Jira) RankIssues(rrp RankRequestProvider) error

https://docs.atlassian.com/jira-software/REST/cloud/#agile/1.0/issue-rankIssues

func (*Jira) RemoveAttachment added in v1.0.8 

func (j *Jira) RemoveAttachment(id string) error

https://docs.atlassian.com/jira/REST/cloud/#api/2/attachment-removeAttachment

func (*Jira) Search added in v1.0.0 

func (j *Jira) Search(sp SearchProvider) (*jiradata.SearchResults, error)

https://docs.atlassian.com/jira/REST/cloud/#api/2/search-searchUsingSearchRequest

func (*Jira) TransitionIssue added in v1.0.0 

func (j *Jira) TransitionIssue(issue string, iup IssueUpdateProvider) error

https://docs.atlassian.com/jira/REST/cloud/#api/2/issue-doTransition

type LinkIssueProvider added in v1.0.0 

type LinkIssueProvider interface {
	ProvideLinkIssueRequest() *jiradata.LinkIssueRequest
}

type RankRequestProvider added in v1.0.0 

type RankRequestProvider interface {
	ProvideRankRequest() *jiradata.RankRequest
}

type SearchOptions added in v1.0.0 

type SearchOptions struct {
	Assignee    string `yaml:"assignee,omitempty" json:"assignee,omitempty"`
	Query       string `yaml:"query,omitempty" json:"query,omitempty"`
	QueryFields string `yaml:"query-fields,omitempty" json:"query-fields,omitempty"`
	Project     string `yaml:"project,omitempty" json:"project,omitempty"`
	Component   string `yaml:"component,omitempty" json:"component,omitempty"`
	IssueType   string `yaml:"issue-type,omitempty" json:"issue-type,omitempty"`
	Watcher     string `yaml:"watcher,omitempty" json:"watcher,omitempty"`
	Reporter    string `yaml:"reporter,omitempty" json:"reporter,omitempty"`
	Status      string `yaml:"status,omitempty" json:"status,omitempty"`
	Sort        string `yaml:"sort,omitempty" json:"sort,omitempty"`
	MaxResults  int    `yaml:"max-results,omitempty" json:"max-results,omitempty"`
}

func (*SearchOptions) ProvideSearchRequest added in v1.0.0 

func (o *SearchOptions) ProvideSearchRequest() *jiradata.SearchRequest

type SearchProvider added in v1.0.0 

type SearchProvider interface {
	ProvideSearchRequest() *jiradata.SearchRequest
}

type UserProvider added in v1.0.0 

type UserProvider interface {
	ProvideUser() *jiradata.User
}

type WorklogProvider added in v1.0.0 

type WorklogProvider interface {
	ProvideWorklog() *jiradata.Worklog
}

Source Files

View all Source files

Directories

Path Synopsis
cmd
jira

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.