Skip to content

Commit d862fd0

Browse files
AlexSkrypnykAlexSkrypnyk
committed
[#1923] Added Slack notifications + docs.
Breaking change: `VORTEX_NOTIFY_REPOSITORY` -> `VORTEX_NOTIFY_GITHUB_REPOSITORY`
1 parent c178365 commit d862fd0

27 files changed

Lines changed: 1219 additions & 48 deletions

File tree

‎.env‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -230,9 +230,10 @@ VORTEX_DEPLOY_TYPES=artifact
230230

231231
# The channels of the notifications.
232232
#
233-
# A combination of comma-separated values: email,newrelic,github,jira
233+
# A combination of comma-separated values: email,slack,newrelic,github,jira,webhook
234234
VORTEX_NOTIFY_CHANNELS=email
235235

236+
#;< NOTIFICATIONS_EMAIL
236237
# An email address to send notifications from.
237238
#
238239
# Applies to email notifications.
@@ -246,6 +247,17 @@ VORTEX_NOTIFY_EMAIL_FROM=webmaster@your-site-domain.example
246247
# with optional names in the format "email|name".
247248
# Example: "to1@example.com|Jane Doe, to2@example.com|John Doe"
248249
VORTEX_NOTIFY_EMAIL_RECIPIENTS="webmaster@your-site-domain.example|Webmaster"
250+
#;> NOTIFICATIONS_EMAIL
251+
252+
#;< NOTIFICATIONS_JIRA
253+
# JIRA user email.
254+
VORTEX_NOTIFY_JIRA_USER=user@example.com
255+
#;> NOTIFICATIONS_JIRA
256+
257+
#;< NOTIFICATIONS_WEBHOOK
258+
# Webhook URL to send notifications to.
259+
VORTEX_NOTIFY_WEBHOOK_URL=
260+
#;> NOTIFICATIONS_WEBHOOK
249261
#;> NOTIFICATIONS
250262

251263
#;< DEMO

‎.vortex/docs/.utils/variables/extra/acquia.variables.sh‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,3 +14,28 @@ VORTEX_PURGE_CACHE_ACQUIA_SKIP=
1414

1515
# Skip Drupal site provisioning in Acquia environment.
1616
VORTEX_PROVISION_ACQUIA_SKIP=
17+
18+
# NewRelic API key, usually of type 'USER'.
19+
#
20+
# @see https://www.vortextemplate.com/docs/workflows/notifications#new-relic
21+
VORTEX_NOTIFY_NEWRELIC_APIKEY=
22+
23+
# JIRA API token.
24+
#
25+
# @see https://www.vortextemplate.com/docs/workflows/notifications#jira
26+
VORTEX_NOTIFY_JIRA_TOKEN=
27+
28+
# GitHub token.
29+
#
30+
# @see https://www.vortextemplate.com/docs/workflows/notifications#github
31+
VORTEX_NOTIFY_GITHUB_TOKEN=
32+
33+
# Slack webhook URL.
34+
# The incoming Webhook URL from your Slack app configuration.
35+
# @see https://www.vortextemplate.com/docs/workflows/notifications#slack
36+
VORTEX_NOTIFY_SLACK_WEBHOOK="${VORTEX_NOTIFY_SLACK_WEBHOOK:-}"
37+
38+
# Custom webhook URL.
39+
#
40+
# @see https://www.vortextemplate.com/docs/workflows/notifications#webhook
41+
VORTEX_NOTIFY_WEBHOOK_URL=

‎.vortex/docs/.utils/variables/extra/lagoon.variables.sh‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,3 +15,28 @@ NEWRELIC_ENABLED=
1515
#
1616
# Set as project-wide variable.
1717
NEWRELIC_LICENSE=
18+
19+
# Notification NewRelic API key, usually of type 'USER'.
20+
#
21+
# @see https://www.vortextemplate.com/docs/workflows/notifications#new-relic
22+
VORTEX_NOTIFY_NEWRELIC_APIKEY=
23+
24+
# Notification JIRA API token.
25+
#
26+
# @see https://www.vortextemplate.com/docs/workflows/notifications#jira
27+
VORTEX_NOTIFY_JIRA_TOKEN=
28+
29+
# Notification GitHub token.
30+
#
31+
# @see https://www.vortextemplate.com/docs/workflows/notifications#github
32+
VORTEX_NOTIFY_GITHUB_TOKEN=
33+
34+
# Notification Slack webhook URL.
35+
# The incoming Webhook URL from your Slack app configuration.
36+
# @see https://www.vortextemplate.com/docs/workflows/notifications#slack
37+
VORTEX_NOTIFY_SLACK_WEBHOOK="${VORTEX_NOTIFY_SLACK_WEBHOOK:-}"
38+
39+
# Notification custom webhook URL.
40+
#
41+
# @see https://www.vortextemplate.com/docs/workflows/notifications#webhook
42+
VORTEX_NOTIFY_WEBHOOK_URL=

‎.vortex/docs/content/workflows/deployment.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ sidebar_position: 3
44

55
# Deployment
66

7-
The deployment to a remote location is performed by the
7+
Deployment to a remote location is performed by the
88
[`scripts/vortex/deploy.sh`](https://github.com/drevops/vortex/blob/develop/scripts/vortex/deploy.sh) _router_
99
script.
1010

‎.vortex/docs/content/workflows/notifications.mdx‎

Lines changed: 158 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,4 +5,161 @@ sidebar_position: 4
55

66
# Notifications
77

8-
The documentation section is still a work in progress.
8+
Vortex provides a flexible notification system that sends updates across
9+
multiple channels.
10+
11+
Notifications are triggered automatically during deployment to a hosting
12+
environment, and can be configured to suit your team's communication needs.
13+
14+
## Channels
15+
16+
Configure notification channels in your `.env` file:
17+
18+
```bash title=".env"
19+
# Enable notification channels (comma-separated list)
20+
VORTEX_NOTIFY_CHANNELS=email,slack,github
21+
```
22+
23+
Available channels: `email`, `github`, `jira`, `newrelic`, `slack`, `webhook`
24+
25+
## Global environment variables
26+
27+
These variables apply to all notification channels unless overridden by channel-specific settings.
28+
29+
### Setup
30+
31+
None
32+
33+
| Variable | Required | Default | Location | Description |
34+
|-------------------------|----------|--------------------|----------|-----------------------------------------------------------|
35+
| `VORTEX_NOTIFY_PROJECT` | No | `VORTEX_PROJECT` | `.env` | Project name used in notifications |
36+
| `VORTEX_NOTIFY_SKIP` | No | | Hosting | Set to `1` to skip all notifications |
37+
38+
## Email
39+
40+
Send deployment notification via email.
41+
42+
### Setup
43+
44+
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.
45+
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).
46+
47+
### Environment variables
48+
49+
| Variable | Required | Default | Location | Description |
50+
|----------------------------------|----------|---------|----------|------------------------------------------------------------|
51+
| `VORTEX_NOTIFY_EMAIL_FROM` | Yes | | `.env` | Email address to send notifications from |
52+
| `VORTEX_NOTIFY_EMAIL_RECIPIENTS` | Yes | | `.env` | Comma-separated list of recipients (format: `email\|name`) |
53+
54+
<details>
55+
<summary>Example</summary>
56+
57+
**Subject:**
58+
59+
```text
60+
My Project deployment notification of "main" branch
61+
```
62+
63+
**Body:**
64+
65+
```text
66+
## This is an automated message ##
67+
68+
Site My Project "main" branch has been deployed at 15/01/2025 14:30:45 UTC and is available at https://example.com.
69+
70+
Login at: https://example.com/user/login
71+
```
72+
73+
</details>
74+
75+
## GitHub
76+
77+
Provide a link to the deployment environment in GitHub.
78+
79+
### Setup
80+
81+
None
82+
83+
### Environment variables
84+
85+
| Variable | Required | Default | Location | Description |
86+
|-----------------------------------|----------|---------|----------|-----------------------------------|
87+
| `VORTEX_NOTIFY_GITHUB_TOKEN` | Yes | | Hosting | GitHub personal access token |
88+
| `VORTEX_NOTIFY_GITHUB_REPOSITORY` | Yes | | Hosting | Repository in `owner/repo` format |
89+
90+
## JIRA
91+
92+
Post a deployment comment and, optionally, update issue status and assignee in JIRA.
93+
94+
### Setup
95+
96+
None
97+
98+
### Environment variables
99+
100+
| Variable | Required | Default | Location | Description |
101+
|-------------------------------------|----------|----------------------------------|----------|---------------------------------------|
102+
| `VORTEX_NOTIFY_JIRA_TOKEN` | Yes | | Hosting | JIRA API token |
103+
| `VORTEX_NOTIFY_JIRA_USER` | Yes | | `.env` | JIRA user email address |
104+
| `VORTEX_NOTIFY_JIRA_ASSIGNEE` | No | | `.env` | User email to assign issue to |
105+
| `VORTEX_NOTIFY_JIRA_TRANSITION` | No | | `.env` | State to transition issue to |
106+
| `VORTEX_NOTIFY_JIRA_ENDPOINT` | No | `https://jira.atlassian.com` | `.env` | JIRA API endpoint |
107+
| `VORTEX_NOTIFY_JIRA_COMMENT_PREFIX` | No | `"Deployed to "` | `.env` | Comment prefix |
108+
109+
## New Relic
110+
111+
Add a deployment marker in New Relic APM.
112+
113+
### Setup
114+
115+
None
116+
117+
### Environment variables
118+
119+
| Variable | Required | Default | Location | Description |
120+
|--------------------------------------|----------|----------------------------------------------------------------------------|----------|-----------------------------------|
121+
| `VORTEX_NOTIFY_NEWRELIC_APIKEY` | Yes | | Hosting | New Relic API key |
122+
| `VORTEX_NOTIFY_NEWRELIC_PROJECT` | No | `VORTEX_NOTIFY_PROJECT` | `.env` | Project name |
123+
| `VORTEX_NOTIFY_NEWRELIC_APP_NAME` | No | `VORTEX_NOTIFY_NEWRELIC_PROJECT-VORTEX_NOTIFY_NEWRELIC_REF` | `.env` | Application name in New Relic |
124+
| `VORTEX_NOTIFY_NEWRELIC_APPID` | No | | `.env` | Application ID (auto-discovered) |
125+
| `VORTEX_NOTIFY_NEWRELIC_DESCRIPTION` | No | `"{ref} deployed"` | `.env` | Deployment description |
126+
| `VORTEX_NOTIFY_NEWRELIC_CHANGELOG` | No | `VORTEX_NOTIFY_NEWRELIC_DESCRIPTION` | `.env` | Deployment changelog |
127+
| `VORTEX_NOTIFY_NEWRELIC_USER` | No | `Deployment robot` | `.env` | User performing deployment |
128+
| `VORTEX_NOTIFY_NEWRELIC_ENDPOINT` | No | `https://api.newrelic.com/v2` | `.env` | API endpoint |
129+
130+
## Slack
131+
132+
Post deployment notification to Slack a channel.
133+
134+
### Setup
135+
136+
None
137+
138+
### Environment variables
139+
140+
| Variable | Required | Default | Location | Description |
141+
|----------------------------------|----------|----------------------------|----------|--------------------------------------------------------------------|
142+
| `VORTEX_NOTIFY_SLACK_WEBHOOK` | Yes | | Hosting | Slack Incoming Webhook URL |
143+
| `VORTEX_NOTIFY_SLACK_PROJECT` | No | `VORTEX_NOTIFY_PROJECT` | `.env` | Project name |
144+
| `VORTEX_NOTIFY_SLACK_CHANNEL` | No | | `.env` | Target channel (overrides webhook default, e.g., `#channel`) |
145+
| `VORTEX_NOTIFY_SLACK_USERNAME` | No | `Deployment Bot` | `.env` | Bot display name |
146+
| `VORTEX_NOTIFY_SLACK_ICON_EMOJI` | No | `:rocket:` | `.env` | Bot icon emoji |
147+
148+
## Webhook
149+
150+
Send custom HTTP request to a webhook endpoint.
151+
152+
### Setup
153+
154+
None
155+
156+
### Environment variables
157+
158+
| Variable | Required | Default | Location | Description |
159+
|-----------------------------------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------|------------------------------------------|
160+
| `VORTEX_NOTIFY_WEBHOOK_URL` | Yes | | `.env` or Hosting | Webhook endpoint URL |
161+
| `VORTEX_NOTIFY_WEBHOOK_PROJECT` | No | `VORTEX_NOTIFY_PROJECT` | Hosting | Project name |
162+
| `VORTEX_NOTIFY_WEBHOOK_METHOD` | No | `POST` | `.env` | HTTP method |
163+
| `VORTEX_NOTIFY_WEBHOOK_HEADERS` | No | `Content-Type: application/json` | `.env` | Pipe-separated headers |
164+
| `VORTEX_NOTIFY_WEBHOOK_PAYLOAD` | No | <code>\{\"channel\": \"Channel 1\", \"message\": \"%message%\", \"project\": \"%project%\", \"ref\": \"%ref%\", \"timestamp\": \"%timestamp%\", \"environment_url\": \"%environment_url%\"\}</code> | `.env` | JSON payload with substitution variables |
165+
| `VORTEX_NOTIFY_WEBHOOK_RESPONSE_STATUS` | No | `200` | `.env` | Expected HTTP status code |

0 commit comments

Comments
 (0)