jiav, An Auto Verification Tool For Jira
Note
If you do not have access to a Jira instance, you can refer to jiav's Documentation - Getting Started to setup a self-hosted development Jira instance.
Introduction To jiav
jiav (Jira Issue Auto Verification) is a Python tool that aims to provide an auto verification workflow for Jira issues.
Users provide a YAML-formatted comment in Jira issues, and the tool will execute it. On successful execution, the issue will move to the desired status.
jiav aims to support both on-prem (Jira Datacenter) and cloud versions.
Requirements
- Access to a Jira instance.
- For on-premise instances, a Personal Access Token (PAT) is required (available from release
8.1.4and onwards). - For cloud instasnces, a username and an API token are required.
- For on-premise instances, a Personal Access Token (PAT) is required (available from release
- Being familiar with your instance’s issue workflow.
jiavbinary requires Python3.8or higher.
Installing jiav
jiav repository is hosted on GitHub and distributed via PyPI.
The binary can be installed from remote using pip:
pip3 install jiav
Or pipx:
pipx install jiav
jiav Internals
Automated Verification Workflow
- Access the Jira instance (using PAT or API token).
- Recurse over Jira issues (provided by JQL or manually).
- In each issue, recurse the comments from latest to oldest.
- Check for a valid jiav manifest (only in private comments by default).
- If a manifest is valid, execute the verification steps.
- If the execution is successful, verify the issue.
Manifest
A jiav manifest contains information about the steps to execute during the verification workflow and the desired verified status after a successful execution.
An example of a simple manifest which will verify issue(s) based on a status of a given Jira issue:
---
jiav:
verified_status: "Done"
verification_steps:
- name: "Check for feature completion"
backend: "jira_issue"
issue: "MYPROJECT-20"
status: "Done"
For more detailed information regarding the manifest, refer to jiav’s Documentation - Overview - Manifest.
Backends
Backends in jiav represent distinct methods of executing user-defined logic.
Each backend performs actions that are part of the verification workflow.
jiav ships with the following backends:
lineinfile- Looks for a line in file.regexinfile- Looks for a regex in file.jira_issue- Looks for a Jira issue status.
Developers are able to extend jiav with custom backends, refer to jiav’s Documentation - Developing Backends
Example of external jiav backends:
Usage
After installing the jiav binary, you can access help information by using the --help option.
Validate Local Manifests
Before publishing a manifest in Jira issue(s), we can validate that our given manfiest is valid and will be executed by jiav:
-
Create a local file containing a manifest:
touch /tmp/path_to_temp_manifest.yaml -
Populate
/tmp/path_to_temp_manifest.yamlwith content:--- jiav: verified_status: "Done" verification_steps: - name: "Check for feature completion" backend: "jira_issue" issue: "MYPROJECT-20" status: "Done" -
Validate manifest:
jiav validate-manifest -f /tmp/path_to_temp_manifest.yamlOn a successful validation, we will recieve a confirmation:
[16:37:10] INFO File content: --- jiav: verified_status: "Done" verification_steps: - name: "Check for feature completion" backend: "jira_issue" issue: "MYPROJECT-20" status: "Done" [16:37:10] INFO Provided YAML is validOn a failed validation, we will recieve a validation error:
[16:41:15] INFO File content: --- jiavE: verified_status: "Done" verification_steps: - name: "Check for feature completion" backend: "jira_issue" issue: "MYPROJECT-20" status: "Done" [16:41:15] ERROR 'jiav' is a required property Failed validating 'required' in schema: {'type': 'object', 'required': ['jiav'], 'properties': {'jiav': {'type': 'object', 'required': ['verified_status', 'verification_steps'], 'properties': {'verification_steps': {'type': 'array'}, 'verified_status': {'type': 'string'}}}}} On instance: {'jiavE': {'verified_status': 'Done', 'verification_steps': [{'name': 'Check for feature ' 'completion', 'backend': 'jira_issue', 'issue': 'MYPROJECT-20', 'status': 'Done'}]}} [16:41:15] ERROR Provided manifest is not valid
Verify Issues
Verify a single issue on a cloud hosted Jira instance:
-
Post a manifest as a comment in the browser:
--- jiav: verified_status: "Done" verification_steps: - name: "Check bash is a valid shell" backend: "lineinfile" path: "/etc/shells" path: "bash" -
Verify issue from public comments (this example assumes your cloud instance requires authentication):
jiav verify --jira "<JIRA_CLOUD_INSTANCE_URL>" -u "<JIRA_CLOUD_INSTANCE_USERNAME>" -a "<JIRA_CLOUD_API_TOKEN>" -i "<JIRA_CLOUD_ISSUE>" --allow-public-commentsIf the manfiest was executed successfully, and the desired
verified_statusis a valid transition:[17:48:12] INFO Valid manifest was found in issue '<JIRA_CLOUD_ISSUE>' [17:48:12] INFO Manifest was executed successfully [17:48:12] INFO Posted a comment in '<JIRA_CLOUD_ISSUE>' [17:48:12] INFO Updated status for '<JIRA_CLOUD_ISSUE>' Verified Issues Issue Summary Status Assignee Reporter Comments ────────────────────────────────────────────────────────────────────────────────────────── <JIRA_CLOUD_ISSUE> <JIRA ISSUE SUMMARY> <STATUS> <ASSIGNEE> <REPORTER> <NUMBER>If the manifest failed to execute:
[17:48:12] INFO Valid manifest was found in issue '<JIRA_CLOUD_ISSUE>' [17:48:12] INFO Manifest has failed to execute [17:48:12] INFO No issues were verified
For more detailed information refer to jiav’s Documentation - User Guide.
Demonstration
To follow this exmaple, feel free to create a development Jira instance mentioned at the top of the blog post.
-
Create an API token (for cloud instances) or a PAT (for on-prem instances).
-
Ensure you have a project created.
Access the project’s issue workflow to view possible transitions:
-
Create an issue (if required).
You can also update the issue’s status based to a status that can be transitioned to the desired state:
-
Post a comment in a Jira instance. If your instance supports “private” comments, it is recommended to use it.
Ensure your comment was posted.
-
Execute
jiavbinary to verify the issue.jiav verify --jira "http://192.168.1.4:2990/jira" -a "<TOKEN_FROM_STEP_1>" -i "EXAMPLE-1"On a successful exection:
[17:48:11] INFO Successfully authenticated with Jira instance 'http://192.168.1.4:2990/jira' of type 'Server' [17:48:12] INFO Discovered issues: [<JIRA Issue: key='EXAMPLE-1', id='10000'>] [17:48:12] INFO Looking at issue 'EXAMPLE-1' [17:48:12] INFO Valid manifest was found in issue 'EXAMPLE-1' [17:48:12] INFO Manifest was executed successfully [17:48:12] INFO Posted a comment in 'EXAMPLE-1' [17:48:12] INFO Updated status for 'EXAMPLE-1' Verified Issues Issue Summary Status Assignee Reporter Comments ──────────────────────────────────────────────────────────────────────────── EXAMPLE-1 Check Bash Is Usable Done admin admin 2 -
Revisit Jira issue in the browser to ensure that the issues was verified.
Final Notes
In this blog post we covered a minimal basic scenario of jiav.
This tool can be utilized to perform more advanced verification workflows.
Refer to the documentation and GitHub repository for more details.