Guide: Jira Basics

In this guide we cover basic ways of working with the jira command, including:

• creating issues
• updating issues
• assigning issues
• commenting on issues
• logging work on issues
• aliases

Also check out Yetibot's Jira reference for docs on its full capabilities.

Channel project

The first thing you'll want to do is set the Jira project(s) for your channel. This tells Yetibot the default project to use when running jira commands in your channel, and allows it to auto-expand issues when you mention an issue key in conversation, without needing to trigger Yetibot manually.

Check current settings:

!channel settings

And if jira-project is not set, set it with:

!channel set jira-project YETIBOT

Once jira-project is set we can run commands like jira recent to see all recent tasks for the configured project:

!jira recent

Make sure to set jira-project for every channel you're in. It can vary from channel to channel, and also supports multiple comma-separated projects. When multiple projects are specified, commands like jira recent or jira create will default to the first project, and the issue observer that listens for words that look like a Jira issue key (as demonstrated in the screenshot above) will fire on all configured projects.

Create

Let's check the jira create docs:

!help jira | grep jira create

There are quite a few options, and which ones are required depend on your particular Jira project configuration, but summary is always required, and description often is. Try it out:

!jira create hello at `time +0` UTC!

Recent issues

We already saw how jira recent lists recent issues for the configured projects in a channel.

!jira recent

Internally, this uses Jira's powerful JQL support to query for issues. With YETIBOT as the configured jira-project, the exact query would be:

(project in (YETIBOT)) ORDER BY updatedDate

This doesn't limit the issues to a certain age, but just returns the most recent page (default page size is 10) of issues.

Show

If we know an issue key, we can ask Yetibot to show all of its details:

!jira show YETIBOT-1

But what if we just want to show the latest issue without knowing its key? We can use a combination of commands with pipes, like:

!jira recent | head | jira parse | jira show

This works by evaluating commands from left to right, passing the value from one command to the next across the | "pipe" as input:

1. jira recent gets the list of recent issues
2. head takes the first issue
3. jira parse parses out just the issue key, e.g. YETIBOT-123
4. jira show shows the issue given the key

We'll continue to use this pattern to work on the latest issue throughout the rest of this guide, so let's alias it:

!alias firstjira = "jira recent | head | jira parse"

!firstjira

Update

Yetibot can update issues:

!help jira | grep jira update

Let's update the description of the most recent issue then pipe it to jira show, which will show us the full description (unlike the short format).

!firstjira | jira update %s -d This description was updated at `time +0` UTC | jira parse | jira show

We can run this multiple times, and notice the updated timestamp each time it's run.

User search

Search the users in Jira with:

!jira users yeti

Assigning issues

Issues can be re-assigned using jira update:

!jira update `firstjira` -a yeti

The assignee can be a partial match. Yetibot uses the search API to resolve the user.

Priority

List all the priorities in Jira:

!jira priorities

When setting a priority in jira create or jira update use the name, or at least part of the name, and Yetibot will do its best to match to a known priority:

!jira update `firstjira` -y med

Components

List components in Jira with:

!jira components

And just like priorities, we can set the component of an issue:

!jira update `firstjira` -c core | jira parse | jira show

Or get crazy and set the component randomly:

!jira update `firstjira` -c `jira components | render {{name}} | random` | jira parse | jira show

Try running the above multiple times and watch the component change.

Comments

We can comment on an issue with Yetibot, but the author will always be Yetibot itself, as it doesn't have permission to comment on other users' behalf:

!help jira | grep jira comment

!jira comment `firstjira` why isn't this done yet 🤔

Logging work

Yetibot can log work, but just like comments, it's logged on behalf of the Yetibot account.

!help jira | grep jira worklog

time-spent can be expressed like 2h, 3d, or 1w.

Let's log a whole 2 weeks on the latest item:

!jira worklog `firstjira` 2w deleted a lot of code 💾

Transitions

Transitions are Jira's workflow mechanism:

A Jira workflow is a set of statuses and transitions that an issue moves through during its lifecycle, and typically represents a process within your organization.

Working with workflows

Yetibot can list available transitions for an issue and move an issue through transitions.

!jira transitions `firstjira`

!jira transition `firstjira` in progress

Or apply a random transition:

!jira transition `firstjira` `firstjira | jira transitions | random`

Aliases

We can use aliases to further simplify Jira issue creation. For example, if we wanted a quick way to create new tasks assigned to Yetibot, we could alias it with:

!alias yetitask = "jira create $s -a yetibot"

Then quickly create new issues for yetibot with:

!yetitask do stuff, yeti ⚡️

A common use case is to hardcode the assignee like above as a fast way to create issues for yourself. Want to quickly create a list of stuff? Try:

!list fix the foo, deploy the bar, decomplect the baz | xargs yetitask

Finally

We hope this guide has helped you increase your Yetibot expression and automation fluency. While this guide illustrates working with a single command, Yetibot is well-suited to be the glue between many systems in the communal context of the mighty channel. See Guide: Google Sheets to Jira issues for one such reification of this idea along with more advanced jira usage.

If you feel like cleaning up after yourself, use this to delete all the issues you just created:

!jira jql created > -1h | xargs jira parse | xargs jira delete

🔥

Question? Ideas for other guides? Post a comment below 🙏.