Skip to content

Commit 02f4a1b

Browse files
ashokdevtronashokdevtron
authored
docs: Jira plugins doc (Validator + Updater) (#5709)
* Docs of Jira Plugins - Validator and Updater * Added Index Links * Additional Proofreading
1 parent ba02845 commit 02f4a1b

File tree

4 files changed

+115
-0
lines changed

4 files changed

+115
-0
lines changed

‎docs/SUMMARY.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -146,6 +146,8 @@
146146
* [DockerSlim](user-guide/plugins/docker-slim.md)
147147
* [GoLang-migrate](user-guide/plugins/golang-migrate.md)
148148
* [Jenkins](user-guide/plugins/jenkins.md)
149+
* [Jira Issue Validator](user-guide/plugins/jira-validator.md)
150+
* [Jira Issue Updater](user-guide/plugins/jira-updater.md)
149151
* [K6 Load Testing](user-guide/plugins/k6-load-testing.md)
150152
* [Pull images from container repository](user-guide/plugins/pull-images-from-container-repository.md)
151153
* [Semgrep](user-guide/plugins/semgrep.md)

‎docs/user-guide/plugins/jira-updater.md

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# Jira Issue Updater
2+
3+
## Introduction
4+
The Jira Issue Updater plugin extends the capabilities of Devtron CI by allowing updates to Jira issues directly from the pipeline. It can add build pipeline status and docker image ID as a comment on Jira tickets, keeping the issue tracking synchronized with your CI processes.
5+
6+
### Prerequisites
7+
8+
- A Jira account with the necessary [API access](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/#Create-an-API-token).
9+
- The API credentials (username, password, and base URL) for your Jira instance. Obtain the API credentials from your Jira admin if required.
10+
- A pull request raised with your Git provider. Title of pull request must contain the Jira ID.
11+
- Jira Issue (e.g., REDOC-12)
12+
- Webhook added to the git repository. [Click here](https://docs.devtron.ai/usage/applications/creating-application/workflow/ci-pipeline#configuring-webhook) to know more.
13+
14+
---
15+
16+
## Steps
17+
18+
1. On the **Edit build pipeline** page, go to the **Post-Build Stage**.
19+
2. Click **+ Add task**.
20+
3. Select **Jira Issue Updater** from the list of plugins.
21+
* Enter a task name (mandatory).
22+
* Optionally, enter a description.
23+
* Provide values for the input variables.
24+
25+
| Variable | Format | Description |
26+
| ------------------------ | ------ | --------------------------------------------------------- |
27+
| JiraUsername | String | Your Jira username (e.g., [email protected]) |
28+
| JiraPassword | String | Your Jira API token provided by the Jira admin |
29+
| JiraBaseUrl | String | The base URL of your Jira instance (e.g., https://yourdomain.atlassian.net/) |
30+
| UpdateWithDockerImageId | Bool | Set to `true` to include the Docker Image ID in the update |
31+
| UpdateWithBuildStatus | Bool | Set to `true` to include the build status in the update |
32+
33+
* `Trigger/Skip Condition` allows you to set conditions under which this task will execute or be skipped.
34+
* `Pass/Failure Condition` allows you define conditions to determine if the build passes or fails based on the Jira update.
35+
36+
4. Go to the **Build Stage**.
37+
38+
5. Select **Pull Request** in the **Source Type** dropdown.
39+
40+
6. Use filters to fetch only the PRs matching your regex. Here are few examples:
41+
* **Title** can be a regex pattern (e.g., `^(?P<jira_Id>([a-zA-Z0-9-].*))`) to extract the Jira ID from the PR title. Only those PRs fulfilling the regex will be shown for image build process.
42+
* **State** can be `^open$`, where only PRs in open state will be shown for image build process.
43+
44+
7. Click **Update Pipeline**.
45+
46+
---
47+
48+
## Results
49+
50+
![Figure 1: Build Log](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/plugins/jira/jira-updater-log.jpg)
51+
52+
![Figure 2: Comments added by the Plugin on the Jira Issue](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/plugins/jira/jira-updater.jpg)
53+
54+
55+
56+
57+

‎docs/user-guide/plugins/jira-validator.md

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# Jira Issue Validator
2+
3+
## Introduction
4+
The Jira Issue Validator plugin extends the filtering capabilities of the Devtron CI and lets users perform validation based on Jira Ticket ID status. This plugin ensures that only builds associated with valid Jira tickets are executed, improving the accuracy of the CI process.
5+
6+
### Prerequisites
7+
8+
- A Jira account with the necessary [API access](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/#Create-an-API-token).
9+
- The API credentials (username, password, and base URL) for your Jira instance. Obtain the API credentials from your Jira admin if required.
10+
- A pull request raised with your Git provider. Title of pull request must contain the Jira ID.
11+
- Jira Issue (e.g., REDOC-12)
12+
- Webhook added to the git repository. [Click here](https://docs.devtron.ai/usage/applications/creating-application/workflow/ci-pipeline#configuring-webhook) to know more.
13+
14+
---
15+
16+
## Steps
17+
18+
1. On the **Edit build pipeline** page, go to the **Pre-Build Stage** (or Post-Build Stage).
19+
2. Click **+ Add task**.
20+
3. Select **Jira Issue Validator** from the list of plugins.
21+
* Enter a task name (mandatory).
22+
* Optionally, enter a description.
23+
* Provide values for the input variables.
24+
25+
| Variable | Format | Description |
26+
| -------------- | ------ | --------------------------------------------------------- |
27+
| JiraUsername | String | Your Jira username (e.g., [email protected]) |
28+
| JiraPassword | String | Your Jira API token provided by the Jira admin |
29+
| JiraBaseUrl | String | The base URL of your Jira instance (e.g., https://yourdomain.atlassian.net) |
30+
31+
* `Trigger/Skip Condition` allows you to set conditions under which this task will execute or be skipped.
32+
* `Pass/Failure Condition` allows you to define conditions that determine whether the build passes or fails based on Jira validation.
33+
34+
4. Go to the **Build Stage**.
35+
36+
5. Select **Pull Request** in the **Source Type** dropdown.
37+
38+
6. Use filters to fetch only the PRs matching your regex. Here are few examples:
39+
* **Title** can be a regex pattern (e.g., `^(?P<jira_Id>([a-zA-Z0-9-].*))`) to extract the Jira ID from the PR title. Only those PRs fulfilling the regex will be shown for image build process.
40+
* **State** can be `^open$`, where only PRs in open state will be shown for image build process.
41+
42+
7. Click **Update Pipeline**.
43+
44+
---
45+
46+
## Results
47+
48+
**Case 1**: If Jira issue exists and the same is found in the PR title
49+
50+
![Figure 1: Jira Issue Match](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/plugins/jira/jira-issue-validator.jpg)
51+
52+
**Case 2**: If Jira issue is not found
53+
54+
![Figure 2: Error in Finding Jira Issue](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/plugins/jira/issue-validation-failed.jpg)

‎docs/user-guide/plugins/plugin-list.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,8 @@ We have multiple plugins available in Devtron. At the moment, here are the plugi
1111
* [Dependency track - Python](./dependency-track-python.md)
1212
* [GoLang-migrate](./golang-migrate.md)
1313
* [Jenkins](./jenkins.md)
14+
* [Jira Issue Validator](./jira-validator.md)
15+
* [Jira Issue Updater](./jira-updater.md)
1416
* [K6 Load Testing](./k6-load-testing.md)
1517
* [Pull images from container repository](./pull-images-from-container-repository.md)
1618
* [Semgrep](./semgrep.md)

0 commit comments

Comments
 (0)