ob-jira-markdown.el

About

This package provides a major mode, jira-markdown, which can be with ob-jira-markdown to create and edit Jira issues. The jira-markdown mode identifies a buffer’s contents as containing markup for a Jira issue, although the mode itself simply derives from markdown-mode.

Source blocks of the jira-markdown type can then be used to create and edit Jira issues via org-babel’s source block execution functionality.

Status

This package is an early draft, and should be considered to be alpha quality; feel free to use it, but it is subject to change! 😅

Installation

This package is not yet on MELPA, but can be installed locally with:

(use-package ob-jira-markdown
  :load-path "/path/to/ob-jira-markdown.el/"
  :custom
  (ob-jira-markdown-host "https://your-org.atlassian.net")
  :bind (("C-x j o" . ob-jira-markdown-open-in-browser)
	 ("C-x j w" . ob-jira-markdown-kill-issue)))

The variable ob-jira-markdown-host can be customised to make enable opening the issue for source blocks in a browser, but isn’t required for the main functionality of ob-jira-markdown.

Requirements

This package relies on jira-cli to communicate with Jira. You should ensure that you have installed and configured it, before attempting to use ob-jira-markdown.

Usage

Creating Jira issues

Jira issues can be created directly from jira-markdown source blocks by executing them as follows:

#+begin_src jira-markdown :command create :execute cli :title test issue
# hello world
this is a test
#+end_src

In this example, a new issue is created with the title “test issue”, and the contents of the source block.

Editing Jira issues

Issues can be edited as follows:

#+begin_src jira-markdown :command edit :execute cli :title test issue :issue abc-123
# hello world
this is a test
#+end_src

Viewing Jira issues

An issue can be viewed from a source block as follows:

#+begin_src jira-markdown :command view :execute cli :issue abc-123
#+end_src

When this source block is executed, the results will be the content of the issue abc-123.

Header arguments

The following header arguments are supported:

:command

Controls whether issues are created or edited. Valid values are create, edit, and view.

:execute

Controls whether the Jira CLI command should be executed, or outputted as a script. Valid values are cli to execute the command, and script to output the script. Use script if you want to preview the CLI command before executing it with cli.

:title

The title of the Jira issue.

:issue

The issue key of the issue. Required for :command edit, and must be omitted for :command create.

:parent

Optionally, the key of the issue to use as the parent issue.

:project

Optionally, the non-default project to create the issue in.

:type

They type of issue to create, e.g. Story.

Opening issues in a browser

If point is on a source block that has the :issue header argument set, the command ob-jira-markdown-open-in-browser can be used interactively to open the issue in a web browser. The custom variable ob-jira-markdown-host must be set to the address of your Jira installation for this to work correctly.

Killing the issue reference of the current source block

A useful command is included in this package to add the issue reference of the source block at point to the kill ring: ob-jira-markdown-kill-issue.

Related projects

• jira-cli.el
• jira.el
• org-jira
• ejira

Contributions

Contributions are very welcome! Please feel free to fork this repo, and raise a PR 🙏