Jira

The Jira channel posts a comment with the environment and login links on the issue named in the branch. It can also move the issue to another status and assign it to someone, so the issue tracks the deployment without manual updates.

This page is for the lead or DevOps engineer who connects deployments to a Jira project. It covers the setup steps, every variable the channel reads and how the channel finds the issue key in a branch name.

Setup

To set up Jira notifications:

1. Create a Jira API token.
2. Add VORTEX_NOTIFY_JIRA_TOKEN to your hosting provider's environment variables.
3. Set VORTEX_NOTIFY_JIRA_USER_EMAIL in your .env file to the email address of the account that owns the token.
4. Set VORTEX_NOTIFY_JIRA_ENDPOINT to the URL of your Jira site, for example https://your-org.atlassian.net, because the default is https://jira.atlassian.com.
5. Add jira to the comma-separated VORTEX_NOTIFY_CHANNELS list in your .env file, for example VORTEX_NOTIFY_CHANNELS=email,jira.
6. Optional: To move the issue after the comment, set VORTEX_NOTIFY_JIRA_TRANSITION to the transition name, for example In Review.
7. Optional: To assign the issue after the comment, set VORTEX_NOTIFY_JIRA_ASSIGNEE_EMAIL to the assignee's email address.

Confirm that the next deployment of a branch with an issue key posted the comment. The deployment output on your hosting platform shows Posted comment with ID and the comment's ID, then [ OK ] Finished JIRA notification. The comment appears on the issue.

Environment variables

See the Notifications overview for the router, what a failed channel stops, the shared VORTEX_NOTIFY_* variables and the Location column. The following table lists the variables that the Jira channel reads:

Variable	Required	Default	Location	Description
VORTEX_NOTIFY_JIRA_TOKEN	Yes	None	Hosting	Jira API token
VORTEX_NOTIFY_JIRA_USER_EMAIL	Yes	None	.env	Jira user email
VORTEX_NOTIFY_JIRA_PROJECT	No	VORTEX_NOTIFY_PROJECT	.env	Project name
VORTEX_NOTIFY_JIRA_MESSAGE	No	Default template	.env	Custom comment template
VORTEX_NOTIFY_JIRA_ASSIGNEE_EMAIL	No	None	.env	Assignee email after deployment
VORTEX_NOTIFY_JIRA_TRANSITION	No	None	.env	Transition name, matched exactly (for example, "In Review")
VORTEX_NOTIFY_JIRA_ENDPOINT	No	https://jira.atlassian.com	.env	Jira API endpoint
VORTEX_NOTIFY_JIRA_BRANCHES	No	None	.env	Exact branch names to post for (comma-separated); empty posts for every branch
VORTEX_NOTIFY_JIRA_BRANCH	No	VORTEX_NOTIFY_BRANCH	Hosting	Branch the issue key is extracted from
VORTEX_NOTIFY_JIRA_LABEL	No	VORTEX_NOTIFY_LABEL	Hosting	Deployment label
VORTEX_NOTIFY_JIRA_ENVIRONMENT_URL	No	VORTEX_NOTIFY_ENVIRONMENT_URL	Hosting	Environment URL
VORTEX_NOTIFY_JIRA_LOGIN_URL	No	VORTEX_NOTIFY_LOGIN_URL	Hosting	Login URL
VORTEX_NOTIFY_JIRA_EVENT	No	VORTEX_NOTIFY_EVENT, then post_deployment	Hosting	Deployment event; pre_deployment posts nothing
VORTEX_NOTIFY_JIRA_LOG	No	VORTEX_NOTIFY_LOG, then 0	.env	1 adds the collected deployment log to the comment as a code block; 0 leaves it out
VORTEX_NOTIFY_JIRA_LOG_FILE	No	VORTEX_NOTIFY_LOG_FILE	Hosting	Log file added to the comment as a code block; the router sets the default

Issue key extraction

The channel takes the Jira issue key from the branch name, using the pattern [A-Za-z0-9]+-[0-9]+, as in these examples:

• feature/PROJ-123-add-feature → PROJ-123
• feature/PRJ-456-fix-auth → PRJ-456

Lowercase keys, such as proj-123, match too. The key has to start the branch name or come right after its first /. When the branch has no key, the channel posts nothing and finishes without an error.

A key anywhere else in the name, or a date in the name, produces an invalid issue key:

• feature/foo/PROJ-123 gives feature/PROJ-123.
• release/2023-04-17 gives 2023-04.

Posting the comment then fails with Unable to create a comment.

VORTEX_NOTIFY_JIRA_BRANCHES takes exact branch names only, so it can't exclude a pattern such as release/*. To keep the channel off the environment of a date-named branch, set VORTEX_NOTIFY_CHANNELS without jira in that environment's hosting variables. A value set in the hosting variables takes precedence over .env.