Jirassic is an Emacs package that provides a convenient interface for interacting with Jira’s REST API. It allows you to create, update, delete, and retrieve Jira issues directly from Emacs, with optional integration into Org Mode.
- Import Jira issues into Org Mode buffers.
- Normalize headings:
Jira issue descriptions often use heading levels (e.g., level 3 and greater) for visual reasons. This can look inconsistent when translated to Org format. Jirassic provides a feature to normalize heading levels by reducing all headings in the description by the difference between the largest heading level and 1.
This behavior is controlled by the customizable variable
jirassic-normalize-heading-levels. When enabled, it ensures that headings in the description are adjusted to start at a visually consistent level in Org mode.(setopt jirassic-normalize-heading-levels t) - Metadata Serialization:
Jirassic automatically adds metadata from the Jira issue as Org properties.
For example:
- Additional properties, tags, etc.
You can customize how Jira issues are serialized into Org by modifying the hooks and variables provided by Jirassic. For example, you can add custom properties or tags to the Org entry after insertion using the
jirassic-org-after-insert-hook.(add-hook 'jirassic-org-after-insert-hook (lambda () (org-set-tags "jira")))
Jirassic supports handling attachments of Jira issues.
(setopt jirassic-org-add-attachments t) ; Enable downloading and attaching filesWhen jirassic-org-add-attachments is set to t, attachments will be downloaded and attached via org-attach (see the section on Attachments in the org manual). This allows you to manage attachments directly within your Org files.
(use-package jirassic
:ensure (:type git :host github :repo "emil-vdw/jirassic")
:custom
;; Set your Jira host URL here
(jirassic-host "https://your-subdomain.atlassian.net/"))Jirassic uses Emacs’ built-in auth-source library to securely manage your Jira credentials. Follow the steps below to configure your credentials.
- Locate or Create Your Auth Source File On Linux, the default auth source file is typically located at `~/.authinfo` or `~/.authinfo.gpg`. If it doesn’t exist, you can create one.
- Add Your Jira Credentials
Add an entry for your Jira instance in the auth source file. Replace
host.atlassian.net,<user-email>, and<api-key>with your Jira host, email, and API key, respectively.machine host.atlassian.net login <user-email> password <api-key>
- Verify Permissions
Ensure your auth source file has the correct permissions to prevent unauthorized access. For example:
chmod 600 ~/.authinfo - Test Your Configuration
After setting up your credentials, test the configuration by calling a Jirassic function, such as:
(jirassic-get-issue "ISSUE-123")
If everything is configured correctly, Jirassic will use the credentials from your auth source file to authenticate with Jira.
auth-source can directly query the macOS Keychain for credentials. To add Jira credentials to the Keychain:
- Open the Keychain Access application.
- Create a new password entry with the following details:
- Key: The Jira host (e.g.,
host.atlassian.net). - Account: Your Jira email address.
- Password: Your Jira API key.
- Key: The Jira host (e.g.,
You can use the function jirassic-org-insert-issue to insert a Jira issue into an Org buffer at the current point. This function fetches the issue details from Jira and inserts them as a structured Org entry. It stores the point and buffer where it was called from and makes the API call asynchronously, allowing you to continue working in Emacs while the issue is being fetched (normally the response is instant though).
When called interactively, it prompts you for the issue key. You can also set a prefix arg to specify the level the entry must be at (defaults to the current level if not specified, i.e. org-current-level), for example:
C-u 4 M-x jirassic-org-insert-issue
will insert the issue at level 4.
To insert an issue, call jirassic-org-insert-issue interactively or programmatically.
(jirassic-org-insert-issue "ABC-1234")This will fetch the issue with the key ABC-1234 and insert it at the current point in the Org buffer.
You can bind jirassic-org-insert-issue to a key for quick access:
(define-key org-mode-map (kbd "C-c j") #'jirassic-org-insert-issue)The function accepts an optional level argument to specify the heading level for the inserted issue. If not provided, it defaults to the current Org level.
(jirassic-org-insert-issue "ABC-1234" 2)You can easily use jirassic in org capture templates to capture org tasks from Jira tickets.
Here is an example of a capture template that inserts the contents of a Jira task into the capture buffer as the contents of the capture:
(setq org-capture-templates
'(("j" "Jira task" plain
(file+headline "~/org/test.org" "Tasks")
nil
:hook (lambda ()
(jirassic-org-insert-issue
(read-string "Enter issue key: ")
;; Here we specify what level to insert the issue at.
2)))))- [ ] Org Roam integration
- [ ] Viewing comments
- [ ] Updating issues (with ediff)
- [ ] UI for searching issues
- At the moment, Jirassic does not support serialization of media nodes (like you would include in an issue description). I’m not exactly sure how to do this, there doesn’t seem to be a public api for fetching these?. It does support media attachments though.
Emacs29.3 or laterdash2.0.0 or laters1.12.0 or laterorg9.5 or later
Jirassic is licensed under the GNU General Public License v3.0. See the LICENSE file for details.