Notifications

Vortex provides a flexible notification system that sends updates across multiple channels.

Notifications are triggered automatically during deployment to a hosting environment, and can be configured to suit your team's communication needs.

Channels

Configure notification channels in your .env file:

.env

# Enable notification channels (comma-separated list)
VORTEX_NOTIFY_CHANNELS=email,slack,github

Available channels: email, github, jira, newrelic, slack, webhook

Global environment variables

These variables apply to all notification channels unless overridden by channel-specific settings.

Variable	Required	Default	Location	Description
VORTEX_NOTIFY_CHANNELS	No	email	.env	Notification channels (comma-separated: email,slack,newrelic,github,jira,webhook)
VORTEX_NOTIFY_PROJECT	No	VORTEX_PROJECT	.env	Notification project name
VORTEX_NOTIFY_SKIP	No		Hosting	Notification skip flag (set to 1 to skip notifications)

Deployment context variables

These variables provide deployment context information used by notification channels. They must be set by the hosting environment (e.g., Lagoon, Acquia) before calling the notification script.

Variable	Required	Description
VORTEX_NOTIFY_BRANCH	Yes	Git branch name (used for GitHub API and JIRA issue extraction)
VORTEX_NOTIFY_SHA	Yes	Git commit SHA (used for New Relic revision tracking)
VORTEX_NOTIFY_PR_NUMBER	No	Pull request number (empty for branch deployments)
VORTEX_NOTIFY_LABEL	Yes	Human-readable deployment label for display

Branch vs PR deployment examples

The following table shows how these variables differ between branch and PR deployments:

Variable	Branch deployment	PR deployment
VORTEX_NOTIFY_BRANCH	main	feature/PROJ-123-add-feature
VORTEX_NOTIFY_SHA	abc123def456	def789abc012
VORTEX_NOTIFY_PR_NUMBER	(empty)	123
VORTEX_NOTIFY_LABEL	main	PR-123

Message templates and tokens

Most notification channels support customizable message templates using replacement tokens:

Token	Description	Example
%project%	Project name	My Project
%label%	Deployment label (branch, PR, or custom ID)	main or PR-123
%timestamp%	Current timestamp	15/11/2025 14:30:45 UTC
%environment_url%	Environment URL	https://example.com
%login_url%	Login URL	https://example.com/user/login

These tokens are replaced with actual values when the notification is sent.

Default message template:

## This is an automated message ##

Site %project% %label% has been deployed at %timestamp% and is available at %environment_url%.

Login at: %login_url%

This default template is used for Email and JIRA notifications when no custom message is specified.

Email

Send deployment notification via email.

Setup

1. Add VORTEX_NOTIFY_EMAIL_FROM variable to .env file with the value of the email address that is allowed to be sent from your hosting.
2. Add VORTEX_NOTIFY_EMAIL_RECIPIENTS variable to .env file with a list of recipients in format webmaster@your-site-domain.example|Webmaster (comma-separated for multiple recipients).

Environment variables

Variable	Required	Default	Location	Description
VORTEX_NOTIFY_EMAIL_FROM	Yes		.env	Email notification sender address
VORTEX_NOTIFY_EMAIL_RECIPIENTS	Yes		.env	Email notification recipients (format: email|name)
VORTEX_NOTIFY_EMAIL_PROJECT	No	VORTEX_NOTIFY_PROJECT	.env	Email notification project name
VORTEX_NOTIFY_EMAIL_MESSAGE	No	(template using tokens)	.env	Email notification message template

Example

Subject:

My Project deployment notification of main

Body:

## This is an automated message ##

Site My Project main has been deployed at 15/01/2025 14:30:45 UTC and is available at https://example.com.

Login at: https://example.com/user/login

GitHub

GitHub supports deployment statuses and environment links. Vortex can automatically post deployment status to GitHub pull requests.

Setup

1. Create a GitHub personal access token.
2. Add VORTEX_NOTIFY_GITHUB_TOKEN variable to your hosting provider's global environment variables.
3. Add VORTEX_NOTIFY_GITHUB_REPOSITORY variable to your hosting provider's global environment variables.

Environment variables

Variable	Required	Default	Location	Description
VORTEX_NOTIFY_GITHUB_TOKEN	Yes		Hosting	GitHub notification personal access token
VORTEX_NOTIFY_GITHUB_REPOSITORY	Yes		Hosting	GitHub notification repository in owner/repo format
VORTEX_NOTIFY_GITHUB_ENVIRONMENT_TYPE	No	PR	.env	GitHub notification environment type (production/staging/uat/dev/pr)

Example

The pull request page in GitHub has information about the deployment status.

When deployment starts, a notification is posted to GitHub with Deployment Starting status.

After deployment succeeds, a notification is posted to GitHub. You can use a View deployment button to quickly access the deployed environment.

JIRA

Post a deployment comment and, optionally, update issue status and assignee in JIRA.

Setup

1. Create a JIRA API token.

2. Add VORTEX_NOTIFY_JIRA_TOKEN variable to your hosting provider's global environment variables.

3. Add VORTEX_NOTIFY_JIRA_USER_EMAIL variable to .env file. Example:

   VORTEX_NOTIFY_JIRA_USER_EMAIL="your.email@example.com"

4. Optionally, add VORTEX_NOTIFY_JIRA_ASSIGNEE_EMAIL variable to .env file if you would like the issue to be assigned to this user once the deployment is complete. Example:

   VORTEX_NOTIFY_JIRA_ASSIGNEE_EMAIL="assignee@example.com"

5. Optionally, add VORTEX_NOTIFY_JIRA_TRANSITION variable to .env file with a transition name if you would like the issue to be transitioned to once the deployment is complete. Example:

   VORTEX_NOTIFY_JIRA_TRANSITION="In Review"

Environment variables

Variable	Required	Default	Location	Description
VORTEX_NOTIFY_JIRA_TOKEN	Yes		Hosting	JIRA notification API token
VORTEX_NOTIFY_JIRA_USER_EMAIL	Yes		.env	JIRA notification user email address
VORTEX_NOTIFY_JIRA_PROJECT	No	VORTEX_NOTIFY_PROJECT	.env	JIRA notification project name
VORTEX_NOTIFY_JIRA_MESSAGE	No	(template using tokens)	.env	JIRA notification message template
VORTEX_NOTIFY_JIRA_ASSIGNEE_EMAIL	No		.env	JIRA notification assignee email address
VORTEX_NOTIFY_JIRA_TRANSITION	No		.env	JIRA notification state to transition to
VORTEX_NOTIFY_JIRA_ENDPOINT	No	https://jira.atlassian.com	.env	JIRA notification API endpoint

Example

The notification system automatically extracts the JIRA issue key from the deployment label using the pattern [A-Za-z0-9]+-[0-9]+. The extraction is case-insensitive and will accept mixed-case input, but typical JIRA project keys are uppercase letters followed by a number (so you may see PROJ-123 or proj-123). For example:

• Label: feature/PROJ-123-add-feature → Issue key: PROJ-123
• Label: feature/proj-123-add-feature → Issue key: proj-123
• Label: feature/PRJ-456-fix-auth → Issue key: PRJ-456

Comment posted to JIRA issue:

## This is an automated message ##

Site My Project main has been deployed at 15/11/2025 14:30:45 UTC and is available at https://example.com.

Login at: https://example.com/user/login

The environment URL and login URL are displayed as inline links in JIRA's Atlassian Document Format (ADF).

New Relic

Deployment markers help you track code changes in New Relic APM by associating them with application performance data. Vortex can automatically create deployment markers in New Relic APM when a deployment is performed.

Setup

1. Create a New Relic User API Key:
   • Log in to New Relic
   • Click on your profile icon (bottom left)
   • Go to "API keys"
   • Create or copy an existing "User key"
   • The key format is: NRAK-XXXXXXXXXXXXXXXXXXXXXX
2. Add VORTEX_NOTIFY_NEWRELIC_USER_KEY variable to your hosting provider's global environment variables.
3. Optionally, add other New Relic-related variables to your .env file to customize the notification.

Environment variables

Variable	Required	Default	Location	Description
VORTEX_NOTIFY_NEWRELIC_USER_KEY	Yes		Hosting	New Relic User API Key (format: NRAK-XXXXXXXXXXXXXXXXXXXXXX)
VORTEX_NOTIFY_NEWRELIC_PROJECT	No	VORTEX_NOTIFY_PROJECT	.env	New Relic notification project name
VORTEX_NOTIFY_NEWRELIC_APP_NAME	No	${PROJECT}-${LABEL} (auto-generated)	.env	New Relic notification application name
VORTEX_NOTIFY_NEWRELIC_DESCRIPTION	No	(template using tokens)	.env	New Relic notification deployment description
VORTEX_NOTIFY_NEWRELIC_CHANGELOG	No	VORTEX_NOTIFY_NEWRELIC_DESCRIPTION	.env	New Relic notification deployment changelog
VORTEX_NOTIFY_NEWRELIC_USER	No	Deployment robot	.env	New Relic notification user performing deployment
VORTEX_NOTIFY_NEWRELIC_ENDPOINT	No	https://api.newrelic.com/v2	.env	New Relic notification API endpoint

Example

Deployment marker created in New Relic APM:

Slack

Post deployment notification to Slack a channel.

Setup

1. Create a Slack app and Incoming Webhook.
2. Add VORTEX_NOTIFY_SLACK_WEBHOOK variable to your hosting provider's global environment variables.
3. Optionally, add other Slack-related variables to your .env file to customize the notification.

Environment variables

Variable	Required	Default	Location	Description
VORTEX_NOTIFY_SLACK_WEBHOOK	Yes		Hosting	Slack notification webhook URL
VORTEX_NOTIFY_SLACK_PROJECT	No	VORTEX_NOTIFY_PROJECT	.env	Slack notification project name
VORTEX_NOTIFY_SLACK_MESSAGE	No	(template using tokens)	.env	Slack notification fallback text template
VORTEX_NOTIFY_SLACK_CHANNEL	No		.env	Slack notification target channel (overrides webhook default)
VORTEX_NOTIFY_SLACK_USERNAME	No	Deployment Bot	.env	Slack notification bot display name
VORTEX_NOTIFY_SLACK_ICON_EMOJI	No	:rocket:	.env	Slack notification bot icon emoji

Event behavior

Slack notifications are sent for both pre_deployment and post_deployment events:

• Pre-deployment: Gray color with "Deployment Starting" status
• Post-deployment: Green color with "Deployment Complete" status

Example

Notification posted to Slack channel using custom "VortexBot" Slack app:

Webhook

Send HTTP request to an arbitrary webhook URL.

Setup

1. Add VORTEX_NOTIFY_WEBHOOK_URL variable to your .env file or hosting provider's global environment variables.
2. Optionally, add other webhook-related variables to your .env file to customize the notification.

Environment variables

Variable	Required	Default	Location	Description
VORTEX_NOTIFY_WEBHOOK_URL	Yes		.env or Hosting	Webhook notification endpoint URL
VORTEX_NOTIFY_WEBHOOK_METHOD	No	POST	.env	Webhook notification HTTP method
VORTEX_NOTIFY_WEBHOOK_HEADERS	No	Content-Type: application/json	.env	Webhook notification pipe-separated headers
VORTEX_NOTIFY_WEBHOOK_PAYLOAD	No	(template using tokens)	.env	Webhook notification JSON payload
VORTEX_NOTIFY_WEBHOOK_RESPONSE_STATUS	No	200	.env	Webhook notification expected HTTP status

Default payload template

Webhook payloads support all standard tokens plus an additional %message% token that expands to the full deployment message with all other tokens replaced.

{
  "channel": "Channel 1",
  "message": "%message%",
  "project": "%project%",
  "label": "%label%",
  "timestamp": "%timestamp%",
  "environment_url": "%environment_url%",
  "login_url": "%login_url%"
}

The %message% token expands to the deployment message with all other tokens replaced.