docs: Jira plugins doc (Validator + Updater) (#5709)

* Docs of Jira Plugins - Validator and Updater * Added Index Links * Additional Proofreading
devtron-labs · Sep 3, 2024 · 02f4a1b · 02f4a1b
1 parent ba02845
commit 02f4a1b
Show file tree

Hide file tree

Showing 4 changed files with 115 additions and 0 deletions.
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
@@ -146,6 +146,8 @@
     * [DockerSlim](user-guide/plugins/docker-slim.md)
     * [GoLang-migrate](user-guide/plugins/golang-migrate.md)
     * [Jenkins](user-guide/plugins/jenkins.md)
+    * [Jira Issue Validator](user-guide/plugins/jira-validator.md)
+    * [Jira Issue Updater](user-guide/plugins/jira-updater.md)
     * [K6 Load Testing](user-guide/plugins/k6-load-testing.md)
     * [Pull images from container repository](user-guide/plugins/pull-images-from-container-repository.md)
     * [Semgrep](user-guide/plugins/semgrep.md)

diff --git a/docs/user-guide/plugins/jira-updater.md b/docs/user-guide/plugins/jira-updater.md
@@ -0,0 +1,57 @@
+# Jira Issue Updater
+
+## Introduction
+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.
+
+### Prerequisites
+
+- 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).
+- The API credentials (username, password, and base URL) for your Jira instance. Obtain the API credentials from your Jira admin if required.
+- A pull request raised with your Git provider. Title of pull request must contain the Jira ID.
+- Jira Issue (e.g., REDOC-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.
+
+---
+
+## Steps
+
+1. On the **Edit build pipeline** page, go to the **Post-Build Stage**.
+2. Click **+ Add task**.
+3. Select **Jira Issue Updater** from the list of plugins.
+    * Enter a task name (mandatory).
+    * Optionally, enter a description.
+    * Provide values for the input variables.
+
+    | Variable                 | Format | Description                                               |
+    | ------------------------ | ------ | --------------------------------------------------------- |
+    | JiraUsername             | String | Your Jira username (e.g., [email protected])             |
+    | JiraPassword             | String | Your Jira API token provided by the Jira admin            |
+    | JiraBaseUrl              | String | The base URL of your Jira instance (e.g., https://yourdomain.atlassian.net/) |
+    | UpdateWithDockerImageId  | Bool   | Set to `true` to include the Docker Image ID in the update  |
+    | UpdateWithBuildStatus    | Bool   | Set to `true` to include the build status in the update     |
+
+    * `Trigger/Skip Condition` allows you to set conditions under which this task will execute or be skipped.
+    * `Pass/Failure Condition` allows you define conditions to determine if the build passes or fails based on the Jira update.
+
+4. Go to the **Build Stage**.
+
+5. Select **Pull Request** in the **Source Type** dropdown.
+
+6. Use filters to fetch only the PRs matching your regex. Here are few examples:
+    * **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. 
+    * **State** can be `^open$`, where only PRs in open state will be shown for image build process.
+
+7. Click **Update Pipeline**.
+
+--- 
+
+## Results
+
+![Figure 1: Build Log](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/plugins/jira/jira-updater-log.jpg)
+
+![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)
+
+
+
+
+
diff --git a/docs/user-guide/plugins/jira-validator.md b/docs/user-guide/plugins/jira-validator.md
@@ -0,0 +1,54 @@
+# Jira Issue Validator
+
+## Introduction
+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.
+
+### Prerequisites
+
+- 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).
+- The API credentials (username, password, and base URL) for your Jira instance. Obtain the API credentials from your Jira admin if required.
+- A pull request raised with your Git provider. Title of pull request must contain the Jira ID.
+- Jira Issue (e.g., REDOC-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.
+
+---
+
+## Steps
+
+1. On the **Edit build pipeline** page, go to the **Pre-Build Stage** (or Post-Build Stage).
+2. Click **+ Add task**.
+3. Select **Jira Issue Validator** from the list of plugins.
+    * Enter a task name (mandatory).
+    * Optionally, enter a description.
+    * Provide values for the input variables.
+
+    | Variable       | Format | Description                                               |
+    | -------------- | ------ | --------------------------------------------------------- |
+    | JiraUsername   | String | Your Jira username  (e.g., [email protected])            |
+    | JiraPassword   | String | Your Jira API token provided by the Jira admin            |
+    | JiraBaseUrl    | String | The base URL of your Jira instance (e.g., https://yourdomain.atlassian.net) |
+
+    * `Trigger/Skip Condition` allows you to set conditions under which this task will execute or be skipped.
+    * `Pass/Failure Condition` allows you to define conditions that determine whether the build passes or fails based on Jira validation.
+
+4. Go to the **Build Stage**.
+
+5. Select **Pull Request** in the **Source Type** dropdown.
+
+6. Use filters to fetch only the PRs matching your regex. Here are few examples:
+    * **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. 
+    * **State** can be `^open$`, where only PRs in open state will be shown for image build process.
+
+7. Click **Update Pipeline**.
+
+--- 
+
+## Results
+
+**Case 1**: If Jira issue exists and the same is found in the PR title
+
+![Figure 1: Jira Issue Match](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/plugins/jira/jira-issue-validator.jpg)
+
+**Case 2**: If Jira issue is not found
+
+![Figure 2: Error in Finding Jira Issue](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/plugins/jira/issue-validation-failed.jpg)
diff --git a/docs/user-guide/plugins/plugin-list.md b/docs/user-guide/plugins/plugin-list.md
@@ -11,6 +11,8 @@ We have multiple plugins available in Devtron. At the moment, here are the plugi
 * [Dependency track - Python](./dependency-track-python.md)
 * [GoLang-migrate](./golang-migrate.md)
 * [Jenkins](./jenkins.md)
+* [Jira Issue Validator](./jira-validator.md)
+* [Jira Issue Updater](./jira-updater.md)
 * [K6 Load Testing](./k6-load-testing.md)
 * [Pull images from container repository](./pull-images-from-container-repository.md)
 * [Semgrep](./semgrep.md)