Getting Started with Jira Workflow Approval

Overview

This guide explains how to use the Jira Workflow Approval catalog to enforce approval-based gating in resource provisioning workflows. It helps administrators integrate Jira approval steps into automated infrastructure deployments.

Approval Workflow Execution

A Jupyter Notebook template is used in this guide as an example to demonstrate how the Jira Workflow Approval works. When the workflow handler is attached to an environment template, it automatically triggers upon launch and creates a Jira ticket for approval. Provisioning proceeds only after the ticket is approved.

The same process applies to any environment template where approval-based gating is required.

Prerequisites

Before proceeding, ensure the following:

• A Jira instance is accessible with a valid FQDN
• A Jira project is set up to receive approval tickets
• A Jira user account with API token access is available
• Approval states (e.g., Approved, Denied) are clearly defined

Initial Setup

This involves selecting an environment template, configuring the workflow handler, and sharing both with the appropriate project for end-user access.

End User Flow

When the end user deploys the shared environment template, the attached workflow handler triggers a Jira ticket. Provisioning proceeds only after the ticket is approved.

Part 1: Create Jupyter Notebook Template

To begin, create a Jupyter Notebook:

• As an Org Admin, go to Template Catalog
• Select the AI/ML tab and choose the Jupyter Notebook
• Click Get Started
• Provide the following details:
  • Provide a name and version name (e.g., 1.0)
  • Select a project (e.g., defaultproject)
  • Click Continue

The Environment Template page appears, allowing users to provide the required inputs and deploy the notebook. Refer to the Jupyter Notebook Deployment page for detailed steps on how to deploy a notebook.

Part 2: Share the Jira Workflow Approval Handler

Step 1: Select the Jira Workflow Approval Template

• From the Template Catalog, select the Workflow Helpers tab, choose the Jira Workflow Approval catalog, and click Get Started
• Provide the following details:
  • Provide a name and version name (e.g., 1.0)
  • Select a project (e.g., defaultproject)
  • Click Continue

Step 2: Configure the Jira Integration

• In the Workflow Handler page, click Configuration to provide the required input values needed to configure the Jira integration and click Save

Input Variables for vCluster System Template

Ticket Approval and Denial States
The Jira workflow handler checks the status of the ticket to determine whether to proceed with resource provisioning. The following variables must be configured: - configuration_approved_state: Status value (e.g., Approved, Done) that indicates approval. - configuration_denied_state: Status value (e.g., Rejected, Cancelled) that indicates denial. These values must match the exact status strings used in the Jira project's workflow. Mismatched or incorrect values may result in the ticket not being recognized as resolved, blocking further actions.

Once the changes are complete, users can view the workflow handlers list.

Part 3: Attach the Jira Workflow Handler to an Environment Template

• Navigate to Environment Templates to attach the Jira Workflow Handler as a hook to the notebook environment template created in Part 1 (e.g., jupyter-workspace-init)

• Click the Edit icon for the selected environment template and go to the Hooks section

• Click + Add Hook

• Enter a name for the hook and select the hook type as Workflow Handler

• From the list of available workflow handlers, choose the one created in Part 2 – Step 2

• Provide the other details as required and click Save Changes

• Click Save as Draft or Save as Active

💡 Recommended: Enable Skip On Destroy
It is generally recommended to enable Skip On Destroy when configuring Jira workflow handlers in self-service scenarios. Enabling this option ensures that the workflow handler is triggered only during environment provisioning and not during deletion. This prevents unnecessary approval requests or ticket creation when an environment is being removed. For specific use cases where notification or tracking during deletion is required, this option can be left disabled. In such cases, a ticket may be generated to inform stakeholders about the environment termination. This setting should be reviewed based on the expected behavior during the destroy phase of the environment lifecycle.

Part 4: Launch the Notebook Template

• Navigate to Environments and launch the Jupyter Notebook created in Part 1

• Provide a name and, optionally, a description

• Select an active agent from the dropdown

• Enter the cluster name and API Key

• Click Save & Deploy

• The initial status is Pending and changes to Waiting for Approval

An output is displayed with the Jira link and ticket_number.

• Copy and paste the Jira link, then approve or decline based on the requirement

• Once approved, the remaining activities take place and the environment is successfully created with the status shown as Success

If declined, the remaining activities will not proceed.