doc/solutions/components/jira_vsa.md
{{< details >}}
{{< /details >}}
GitLab Value Stream Analytics (VSA) provides powerful insights into your development workflow, tracking key metrics such as:
For teams using Jira for issue tracking while leveraging GitLab for development, this integration enables automatic replication of Jira issues to GitLab in real-time. This ensures accurate VSA metrics without requiring teams to change their existing Jira workflows.
The integration also populates the GitLab Value Streams Dashboard (Ultimate only), which provides an overview of key DevSecOps metrics and can be found under Analyze > Analytics dashboards in your GitLab project or group.
[!note] A similar integration exists for incident replication to generate specific DORA metrics (Change Failure Rate and Time to Restore Service). If you're interested in incident replication, refer to the Jira Incident Replicator.
We will create 2 automation workflows using Jira automation:
When a new issue is created in Jira, the automation workflow sends a POST request to the GitLab Issues API to create a corresponding issue in the specified GitLab project.
When a Jira issue transitions to a resolved state (Closed, Done, Resolved), the automation workflow sends a PUT request to close the corresponding GitLab issue.
This walkthrough assumes that you have:
Jira places limits on the frequency of Automation runs depending on your Jira license:
| Tier | Limit |
|---|---|
| Free | 100 runs per month |
| Standard | 1700 runs per month |
| Premium | 1000 runs per user per month |
| Enterprise | Unlimited runs |
Each issue creation counts as 1 run, and each issue resolution counts as 1 run.
First, we need to create a GitLab project access token with the necessary permissions to create and update issues via the API.
Jira VSA Integration (or any descriptive name)Owner (This is required to set custom issue IDs)api (full API access)Important: An Owner level access token is required because the integration needs to force-set custom issue IDs when creating issues in GitLab. This ensures that when Jira issues are closed, the automation can identify and close the corresponding GitLab issue using the same ID mapping. Without the Owner role, the GitLab API will not allow setting custom issue IDs, breaking the synchronization between Jira issue closure and GitLab issue closure.
To automatically create GitLab issues when Jira issues are created, we'll use Jira automation.
Navigate to your Jira project. From the sidebar, head to Project settings > Automation.
Click Create rule in the upper right.
For your trigger, search for and select Issue created. Click Save.
Optional: Add conditions to filter which issues should be replicated. For example, you might want to add an Issue fields condition to only replicate issues of certain types or with specific labels.
Select THEN: Add an action. Search for and select Send web request.
Configure the web request:
https://gitlab.com/api/v4/projects/<GITLAB_PROJECT_ID>/issues (replace gitlab.com with your GitLab instance URL if self-hosted, and <GITLAB_PROJECT_ID> with your GitLab project's numerical ID, e.g., 42718690)Add the following headers:
| Name | Value |
|---|---|
| Authorization | Bearer <YOUR_GITLAB_TOKEN> |
| Content-Type | application/json |
Set the Authorization header to "Hidden" for security.
In the Custom data field, enter:
{
"title": "{{issue.summary}}",
"iid": {{issue.key.replace("VSA-", "1000")}}
}
Replace "VSA-" with your Jira project prefix (e.g., if your Jira issues are numbered PROJ-123, use "PROJ-"). The 1000 is a base number that gets added to ensure no conflict with issues that may have been created directly within GitLab itself via the UI - you can adjust this value as needed.
Click Save, give your automation a descriptive name (e.g., Jira to GitLab Issue Creation), and click Turn it on.
Create a second automation workflow to close GitLab issues when Jira issues are resolved:
Follow steps 1-2 from the creation workflow to start a new rule.
Set the trigger to Issue transitioned:
Closed, Done, Resolved (adjust based on your Jira workflow)Skip conditions (or add custom ones if needed).
Add a Send web request action with:
https://gitlab.com/api/v4/projects/<GITLAB_PROJECT_ID>/issues/{{issue.key.replace("<JIRA_PROJECT_PREFIX>-", "1000").urlEncode}} (replace gitlab.com with your GitLab instance URL if self-hosted, <GITLAB_PROJECT_ID> with your GitLab project's numerical ID, and <JIRA_PROJECT_PREFIX> with your Jira project prefix like VSA or PROJ)Use the same headers as the creation workflow.
In the Custom data field, enter:
{
"state_event": "close"
}
Save and enable the automation rule with a descriptive name (e.g., Jira to GitLab Issue Closer).
Once your automation workflows are active, GitLab will begin receiving issue data. Here's how to access your analytics:
The Value Streams Dashboard is automatically populated with metrics from your replicated issues and is available with GitLab Ultimate:
For more detailed analytics and custom value streams (available with GitLab Premium and Ultimate):
If you want to replicate issues from multiple Jira projects using a single set of automation rules, consider using a timestamp-based approach for generating unique issue IDs instead of the project prefix method:
Replace the iid value in your custom data with:
"iid": {{issue.created.replace("-","").replace("T","").replace(":","").replace(".","").replace("+","")}}
This converts the creation timestamp (format: 2025-02-15T09:45:32.7+0000) into a numeric value. Note that this approach may result in very long issue IDs and has a small risk of conflicts if two issues are created at exactly the same time.