# jiav
> [!NOTE]
> This repository is a **Proof of Concept.**
> [!WARNING]
> Since this tool executes commands locally, we should avoid trusting public comments as much as possible.
>
> It will default to scanning only private comments (regardless of the visibility group). It is possible to read from public comments **if you understand the potential risk, this might cause to your systems**.
>
> The output of verification steps is also not uploaded as attachments by default because it is impossible to limit attachments' visibility, refer to [JRASERVER-3893](https://jira.atlassian.com/browse/JRASERVER-3893). It is possible to attach the output **if you understand the potential risk, this might expose sensitive information**.
<https://github.com/user-attachments/assets/1a9d5728-96e3-436a-9e0d-b31f74d5298b>
**J**ira **I**ssues **A**uto **V**erification.
`jiav` is a [Python](https://www.python.org) based auto verification
tool for [Jira](https://www.atlassian.com/software/jira).
The primary goal is to provide a robust auto-verification
workflow while focusing on ease of use and simplicity.
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.
Both self-hosted and cloud Jira instances are supported.
## Backends
`jiav` allows developers to build custom backends; refer to the [development guide](docs/source/developing_backends.rst).
Built-in backends:
- `lineinfile` - looks for a line in file.
- `regexinfile` - looks for a regex in file.
- `jira_issue` - queries a Jira issue's status.
An example of a backends shipped externally:
- [`ansible`](https://github.com/vkhitrin/jiav-backend-ansible) - runs [Ansible](https://www.ansible.com) playbooks.
**This is a risky backend since it allows users to run arbitrary code. Be cautious when enabling it!**
- [`command`](https://github.com/vkhitrin/jiav-backend-command) - runs shell commands.
**This is a risky backend since it allows users to run arbitrary code. Be cautious when enabling it!**
## Requirements
`jiav` requires Python `>= 3.8`.
Self-hosted Jira instances require "Personal Access Tokens" (PAT) which are available starting from
[`>=8.14`](https://confluence.atlassian.com/enterprise/using-personal-access-tokens-1026032365.html).
Cloud Jira instances require a username + API tokens.
## Documentation
Visit <https://jiav.readthedocs.io>.
## Installation
### Remote
Install from remote using `pip3`:
```bash
pip3 install jiav
```
Install from remote using `pipx`:
```bash
pipx install jiav
```
### Local
Clone the local repository:
```bash
git clone https://github.com/vkhitrin/jiav.git
cd jiav
```
Install using `pip3`:
```bash
pip3 install .
```
Install using `pipx`:
```bash
pipx install .
```
## Usage
Please refer to the user guide:
<https://jiav.readthedocs.io/en/latest/user_guide.html>
If you do not have access to a Jira instance or wish to attempt this tool in an isolated environment, refer to
a ["Getting Started"](docs/source/getting_started.rst) on setting up a demo environment.
## Contributing
**All contributions are welcome!**
To install in development mode, use `poetry`:
```bash
poetry install --with=main,dev,types
```
If proposing new pull requests, please ensure that new/existing tests are passing:
```bash
pytest
```
Raw data
{
"_id": null,
"home_page": "https://github.com/vkhitrin/jiav",
"name": "jiav",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": null,
"author": "Vadim Khitrin",
"author_email": "me@vkhitrin.com",
"download_url": "https://files.pythonhosted.org/packages/e5/e4/e80b41f2930810509c8f3c1e04d4fe5f531bca2561fd09e15579693f3750/jiav-0.3.2.tar.gz",
"platform": null,
"description": "# jiav\n\n> [!NOTE]\n> This repository is a **Proof of Concept.**\n\n> [!WARNING]\n> Since this tool executes commands locally, we should avoid trusting public comments as much as possible.\n>\n> It will default to scanning only private comments (regardless of the visibility group). It is possible to read from public comments **if you understand the potential risk, this might cause to your systems**.\n>\n> The output of verification steps is also not uploaded as attachments by default because it is impossible to limit attachments' visibility, refer to [JRASERVER-3893](https://jira.atlassian.com/browse/JRASERVER-3893). It is possible to attach the output **if you understand the potential risk, this might expose sensitive information**.\n\n<https://github.com/user-attachments/assets/1a9d5728-96e3-436a-9e0d-b31f74d5298b>\n\n**J**ira **I**ssues **A**uto **V**erification.\n\n`jiav` is a [Python](https://www.python.org) based auto verification\ntool for [Jira](https://www.atlassian.com/software/jira).\n\nThe primary goal is to provide a robust auto-verification\nworkflow while focusing on ease of use and simplicity.\nUsers provide a YAML-formatted comment in Jira issues, and the tool will execute it. \nOn successful execution, the issue will move to the desired status.\n\nBoth self-hosted and cloud Jira instances are supported.\n\n## Backends\n\n`jiav` allows developers to build custom backends; refer to the [development guide](docs/source/developing_backends.rst).\n\nBuilt-in backends:\n\n- `lineinfile` - looks for a line in file.\n- `regexinfile` - looks for a regex in file.\n- `jira_issue` - queries a Jira issue's status.\n\nAn example of a backends shipped externally:\n\n- [`ansible`](https://github.com/vkhitrin/jiav-backend-ansible) - runs [Ansible](https://www.ansible.com) playbooks. \n **This is a risky backend since it allows users to run arbitrary code. Be cautious when enabling it!**\n- [`command`](https://github.com/vkhitrin/jiav-backend-command) - runs shell commands. \n **This is a risky backend since it allows users to run arbitrary code. Be cautious when enabling it!**\n\n## Requirements\n\n`jiav` requires Python `>= 3.8`.\n\nSelf-hosted Jira instances require \"Personal Access Tokens\" (PAT) which are available starting from\n[`>=8.14`](https://confluence.atlassian.com/enterprise/using-personal-access-tokens-1026032365.html).\n\nCloud Jira instances require a username + API tokens.\n\n## Documentation\n\nVisit <https://jiav.readthedocs.io>.\n\n## Installation\n\n### Remote\n\nInstall from remote using `pip3`:\n\n```bash\npip3 install jiav\n```\n\nInstall from remote using `pipx`:\n\n```bash\npipx install jiav\n```\n\n### Local\n\nClone the local repository:\n\n```bash\ngit clone https://github.com/vkhitrin/jiav.git\ncd jiav\n```\n\nInstall using `pip3`:\n\n```bash\npip3 install .\n```\n\nInstall using `pipx`:\n\n```bash\npipx install .\n```\n\n## Usage\n\nPlease refer to the user guide:\n<https://jiav.readthedocs.io/en/latest/user_guide.html>\n\nIf you do not have access to a Jira instance or wish to attempt this tool in an isolated environment, refer to\na [\"Getting Started\"](docs/source/getting_started.rst) on setting up a demo environment.\n\n## Contributing\n\n**All contributions are welcome!**\n\nTo install in development mode, use `poetry`:\n\n```bash\npoetry install --with=main,dev,types\n```\n\nIf proposing new pull requests, please ensure that new/existing tests are passing:\n\n```bash\npytest\n```\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "Jira Issues Auto Verification",
"version": "0.3.2",
"project_urls": {
"Documentation": "https://jiav.readthedocs.io",
"Homepage": "https://github.com/vkhitrin/jiav",
"Repository": "https://github.com/vkhitrin/jiav"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3e166fe093660279a8520908503b226d9d7fa7248c0daf00fcb97acd8521ab3a",
"md5": "ff6b81b4958d3d55880d4b5cff0b41c4",
"sha256": "e144454ee5a12daf05bdd31640661448550cc02e065a155a51049f8ed610bed0"
},
"downloads": -1,
"filename": "jiav-0.3.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ff6b81b4958d3d55880d4b5cff0b41c4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 22085,
"upload_time": "2024-09-18T14:51:01",
"upload_time_iso_8601": "2024-09-18T14:51:01.918416Z",
"url": "https://files.pythonhosted.org/packages/3e/16/6fe093660279a8520908503b226d9d7fa7248c0daf00fcb97acd8521ab3a/jiav-0.3.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e5e4e80b41f2930810509c8f3c1e04d4fe5f531bca2561fd09e15579693f3750",
"md5": "2e77547abb450430d23175583b9702cb",
"sha256": "fb09e497ddc017bb099b615ee382bae1743aea5ee37150b53df6da324607370c"
},
"downloads": -1,
"filename": "jiav-0.3.2.tar.gz",
"has_sig": false,
"md5_digest": "2e77547abb450430d23175583b9702cb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 17336,
"upload_time": "2024-09-18T14:51:03",
"upload_time_iso_8601": "2024-09-18T14:51:03.064355Z",
"url": "https://files.pythonhosted.org/packages/e5/e4/e80b41f2930810509c8f3c1e04d4fe5f531bca2561fd09e15579693f3750/jiav-0.3.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-18 14:51:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "vkhitrin",
"github_project": "jiav",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "jiav"
}
JSON
