jira demo

Let's start by temporarily changing $HOME to avoid cluttering the real one:

export HOME=~/src/canonical/demos

Make sure we have $GOPATH set and that $GOPATH/bin is in our $PATH:

export GOPATH=$HOME/go
export PATH=$GOPATH/bin:$PATH

Now we install golang:

sudo apt install golang

And finally install the jira CLI tool:

go install github.com/ankitpokhrel/jira-cli/cmd/jira@latest

go: downloading github.com/ankitpokhrel/jira-cli v1.4.0
go: downloading github.com/kr/text v0.2.0
go: downloading github.com/spf13/cobra v1.7.0
go: downloading github.com/spf13/viper v1.14.0
go: downloading github.com/zalando/go-keyring v0.2.1
go: downloading github.com/briandowns/spinner v1.19.0
go: downloading github.com/fatih/color v1.13.0
go: downloading github.com/mitchellh/go-homedir v1.1.0
go: downloading github.com/AlecAivazis/survey/v2 v2.3.6
go: downloading github.com/google/shlex v0.0.0-20191202100458-e7afc7fbc510
go: downloading github.com/pkg/browser v0.0.0-20210911075715-681adbf594b8
go: downloading github.com/cli/safeexec v1.0.1
go: downloading github.com/gdamore/tcell/v2 v2.5.3
go: downloading github.com/mattn/go-isatty v0.0.16
go: downloading github.com/rivo/tview v0.0.0-20221217182043-ccce554c3803
go: downloading github.com/godbus/dbus/v5 v5.1.0
go: downloading github.com/mattn/go-colorable v0.1.13
go: downloading github.com/atotto/clipboard v0.1.4
go: downloading github.com/charmbracelet/glamour v0.6.0
go: downloading github.com/mgutz/ansi v0.0.0-20200706080929-d51e80ef957d
go: downloading github.com/kballard/go-shellquote v0.0.0-20180428030007-95032a82bc51
go: downloading github.com/kentaro-m/blackfriday-confluence v0.0.0-20220126124413-8e85477b49b3
go: downloading github.com/russross/blackfriday/v2 v2.1.0
go: downloading github.com/fsnotify/fsnotify v1.6.0
go: downloading github.com/mitchellh/mapstructure v1.5.0
go: downloading github.com/spf13/afero v1.9.3
go: downloading github.com/spf13/cast v1.5.0
go: downloading github.com/spf13/jwalterweatherman v1.1.0
go: downloading github.com/spf13/pflag v1.0.5
go: downloading github.com/cpuguy83/go-md2man/v2 v2.0.2
go: downloading gopkg.in/yaml.v3 v3.0.1
go: downloading golang.org/x/term v0.5.0
go: downloading golang.org/x/sys v0.5.0
go: downloading golang.org/x/text v0.7.0
go: downloading github.com/gdamore/encoding v1.0.0
go: downloading github.com/lucasb-eyer/go-colorful v1.2.0
go: downloading github.com/mattn/go-runewidth v0.0.14
go: downloading github.com/subosito/gotenv v1.4.1
go: downloading github.com/hashicorp/hcl v1.0.0
go: downloading gopkg.in/ini.v1 v1.67.0
go: downloading github.com/magiconair/properties v1.8.7
go: downloading github.com/pelletier/go-toml/v2 v2.0.6
go: downloading github.com/muesli/termenv v0.13.0
go: downloading github.com/pelletier/go-toml v1.9.5
go: downloading github.com/yuin/goldmark v1.5.3
go: downloading github.com/yuin/goldmark-emoji v1.0.1
go: downloading github.com/rivo/uniseg v0.4.3
go: downloading github.com/alecthomas/chroma v0.10.0
go: downloading github.com/microcosm-cc/bluemonday v1.0.21
go: downloading github.com/muesli/reflow v0.3.0
go: downloading github.com/olekukonko/tablewriter v0.0.5
go: downloading github.com/aymanbagabas/go-osc52 v1.2.1
go: downloading github.com/dlclark/regexp2 v1.7.0
go: downloading github.com/aymerick/douceur v0.2.0
go: downloading golang.org/x/net v0.7.0
go: downloading github.com/gorilla/css v1.0.0

Let's verify that the installation was successful and the binary is in $PATH:

which jira

/home/bandali/src/canonical/demos/go/bin/jira

jira version

(Version="v1.4.0", GitCommit="", CommitDate="", GoVersion="go1.20.3", Compiler="gc", Platform="linux/amd64")

Before we can really use the tool, we need to obtain an API token to use when connecting to the Jira server. We can do so by browsing to https://id.atlassian.com/manage-profile/security/api-tokens, clicking on Create API token, and working through the token creation steps. Be sure to copy the generated token afterwards, since it will be shown only once.

Then, put the token in place:

cat > $HOME/.netrc <<EOF
machine JIRA_SERVER_URL
login YOUR_CANONICAL_EMAIL
password YOUR_API_TOKEN
EOF

And verify that we are authenticated to Jira with our account:

jira me

This should output the email associated with our Jira account.

Let's use jira to create a task for this very demo:

jira issue create -a$(jira me) -tTask -s'Prepare jira cli demo' -yHigh

Notice how we provided the needed details as command line arguments. But jira does support and use prompting as well, and e.g. will ask for any missing arguments. Let's see an example of that in editing an issue; let's use jira issue edit to add a quick description:

jira issue edit # ISSUE-KEY

Let's get a list of issues assigned to me that are not Done:

jira issue list -a$(jira me) -s~Done

We can perform several actions from the issue list view. For example, v opens the selected issue in our $PAGER for viewing, and m to change the status of an issue (Untriaged, Triaged, …, and Done). Press ? for the full list.

All of these actions (and more) can also be done from the terminal, by directly running the corresponding sub-command. For example, to view an issue, with a maximum of 20 comments (default is only 1, if not specified):

jira issue view UDENG-577 --comments 20

To add a comment on an issue:

jira issue comment add UDENG-980

To move/transition an issue to the In Review status:

jira issue move UDENG-980 'In Review'

Last but certainly not least, jira supports the Jira Query Language (JQL) with the -q option. For example, to get a list of UDENG issues I'm a collaborator on, I would run:

jira issue list -q'project = "UDENG" and "Collaborators" in (currentUser())'

These are the main actions I've been using jira for; but it has many more sub-commands and sub-sub-commands. We can learn more about them by running them without any options (e.g. jira issue) or with the --help option (e.g. jira issue list --help). I hope you, too, find this interesting and useful. :-)

Finally, another (separate) CLI tool well worth checking out is jirashell, which is built on the Python Jira library and IPython for the interactive shell interface.

Copyright (C) 2023 Canonical Ltd.

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License version 3, as
published by the Free Software Foundation.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see https://www.gnu.org/licenses/.