Skip to content

Commit 41a6b25

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

File tree

27 files changed

+1291
-48
lines changed

27 files changed

+1291
-48
lines changed

‎.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 @@ [email protected]
246247
# with optional names in the format "email|name".
247248
# Example: "[email protected]|Jane Doe, [email protected]|John Doe"
248249
VORTEX_NOTIFY_EMAIL_RECIPIENTS="[email protected]|Webmaster"
250+
#;> NOTIFICATIONS_EMAIL
251+
252+
#;< NOTIFICATIONS_JIRA
253+
# JIRA user email.
254+
VORTEX_NOTIFY_JIRA_USER=[email protected]
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: 230 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,4 +5,233 @@ 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
9+
across multiple channels.
10+
11+
Notifications are triggered automatically during deployment to a
12+
hosting environment, and can be configured to suit your team's
13+
communication needs.
14+
15+
## Channels
16+
17+
Configure notification channels in your `.env` file:
18+
19+
```bash title=".env"
20+
# Enable notification channels (comma-separated list)
21+
VORTEX_NOTIFY_CHANNELS=email,slack,github
22+
```
23+
24+
Available channels: [`email`](#email), [`github`](#github),
25+
[`jira`](#jira), [`newrelic`](#new-relic), [`slack`](#slack),
26+
[`webhook`](#webhook)
27+
28+
## Global environment variables
29+
30+
These variables apply to all notification channels unless overridden by
31+
channel-specific settings.
32+
33+
### Setup
34+
35+
None
36+
37+
| Variable | Required | Default | Location | Description |
38+
|-------------------------|----------|------------------|----------|------------------------------------|
39+
| `VORTEX_NOTIFY_PROJECT` | No | `VORTEX_PROJECT` | `.env` | Project name used in notifications |
40+
| `VORTEX_NOTIFY_SKIP` | No | | Hosting | Set to `1` to skip notifications |
41+
42+
## Email
43+
44+
Send deployment notification via email.
45+
46+
### Setup
47+
48+
1. Add `VORTEX_NOTIFY_EMAIL_FROM` variable to `.env` file with the
49+
value of the email address that is allowed to be sent from your
50+
hosting.
51+
2. Add `VORTEX_NOTIFY_EMAIL_RECIPIENTS` variable to `.env` file with a
52+
list of recipients in format
53+
`[email protected]|Webmaster` (comma-separated for
54+
multiple recipients).
55+
56+
### Environment variables
57+
58+
| Variable | Required | Default | Location | Description |
59+
|----------------------------------|----------|---------|----------|-----------------------------------------|
60+
| `VORTEX_NOTIFY_EMAIL_FROM` | **Yes** | | `.env` | Email address to send notifications from|
61+
| `VORTEX_NOTIFY_EMAIL_RECIPIENTS` | **Yes** | | `.env` | Recipients (format: `email\|name`) |
62+
63+
<details>
64+
<summary>Example</summary>
65+
66+
**Subject:**
67+
68+
```text
69+
My Project deployment notification of "main" branch
70+
```
71+
72+
**Body:**
73+
74+
```text
75+
## This is an automated message ##
76+
77+
Site My Project "main" branch has been deployed at 15/01/2025
78+
14:30:45 UTC and is available at https://example.com.
79+
80+
Login at: https://example.com/user/login
81+
```
82+
83+
</details>
84+
85+
## GitHub
86+
87+
Provide a link to the deployment environment in GitHub.
88+
89+
### Setup
90+
91+
1. [Create a GitHub personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens).
92+
2. Add `VORTEX_NOTIFY_GITHUB_TOKEN` variable to your hosting
93+
provider's global environment variables.
94+
3. Add `VORTEX_NOTIFY_GITHUB_REPOSITORY` variable to your hosting
95+
provider's global environment variables.
96+
97+
### Environment variables
98+
99+
| Variable | Required | Default | Location | Description |
100+
|-----------------------------------|----------|---------|----------|-----------------------------------|
101+
| `VORTEX_NOTIFY_GITHUB_TOKEN` | **Yes** | | Hosting | GitHub personal access token |
102+
| `VORTEX_NOTIFY_GITHUB_REPOSITORY` | **Yes** | | Hosting | Repository in `owner/repo` format |
103+
104+
<details>
105+
<summary>Example</summary>
106+
107+
TBD
108+
109+
</details>
110+
111+
## JIRA
112+
113+
Post a deployment comment and, optionally, update issue status and
114+
assignee in JIRA.
115+
116+
### Setup
117+
118+
1. [Create a JIRA API token](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/).
119+
2. Add `VORTEX_NOTIFY_JIRA_TOKEN` variable to your hosting provider's
120+
global environment variables.
121+
3. Add `VORTEX_NOTIFY_JIRA_USER` variable to `.env` file.
122+
4. Add `VORTEX_NOTIFY_JIRA_ASSIGNEE` variable to `.env` file if you
123+
would like the issue to be assigned to this user once the deployment
124+
is complete.
125+
5. Add `VORTEX_NOTIFY_JIRA_TRANSITION` variable to `.env` file with a
126+
transition name if you would like the issue to be transitioned to
127+
once the deployment is complete.
128+
6. Optionally, modify the comment prefix by adding
129+
`VORTEX_NOTIFY_JIRA_COMMENT_PREFIX` variable to `.env` file.
130+
131+
### Environment variables
132+
133+
| Variable | Required | Default | Location | Description |
134+
|-------------------------------------|----------|------------------------------|----------|----------------------------|
135+
| `VORTEX_NOTIFY_JIRA_TOKEN` | **Yes** | | Hosting | JIRA API token |
136+
| `VORTEX_NOTIFY_JIRA_USER` | **Yes** | | `.env` | JIRA user email address |
137+
| `VORTEX_NOTIFY_JIRA_ASSIGNEE` | No | | `.env` | User email to assign to |
138+
| `VORTEX_NOTIFY_JIRA_TRANSITION` | No | | `.env` | State to transition to |
139+
| `VORTEX_NOTIFY_JIRA_ENDPOINT` | No | `https://jira.atlassian.com` | `.env` | JIRA API endpoint |
140+
| `VORTEX_NOTIFY_JIRA_COMMENT_PREFIX` | No | `"Deployed to "` | `.env` | Comment prefix |
141+
142+
<details>
143+
<summary>Example</summary>
144+
145+
TBD
146+
147+
</details>
148+
149+
## New Relic
150+
151+
Create a deployment marker in New Relic APM.
152+
153+
### Setup
154+
155+
1. [Create a New Relic API key](https://docs.newrelic.com/docs/apis/intro-apis/new-relic-api-keys/).
156+
2. Add `VORTEX_NOTIFY_NEWRELIC_APIKEY` variable to your hosting
157+
provider's global environment variables.
158+
3. Optionally, add other New Relic-related variables to your `.env`
159+
file to customize the notification.
160+
161+
### Environment variables
162+
163+
| Variable | Required | Default | Location | Description |
164+
|--------------------------------------|----------|-----------------------------------|----------|----------------------------|
165+
| `VORTEX_NOTIFY_NEWRELIC_APIKEY` | **Yes** | | Hosting | New Relic API key |
166+
| `VORTEX_NOTIFY_NEWRELIC_PROJECT` | No | `VORTEX_NOTIFY_PROJECT` | `.env` | Project name |
167+
| `VORTEX_NOTIFY_NEWRELIC_APP_NAME` | No | `{PROJECT}-{REF}` | `.env` | Application name |
168+
| `VORTEX_NOTIFY_NEWRELIC_APPID` | No | | `.env` | Application ID (auto) |
169+
| `VORTEX_NOTIFY_NEWRELIC_DESCRIPTION` | No | `"{ref} deployed"` | `.env` | Deployment description |
170+
| `VORTEX_NOTIFY_NEWRELIC_CHANGELOG` | No | `VORTEX_NOTIFY_NEWRELIC_DESCRIP...` | `.env` | Deployment changelog |
171+
| `VORTEX_NOTIFY_NEWRELIC_USER` | No | `Deployment robot` | `.env` | User performing deployment |
172+
| `VORTEX_NOTIFY_NEWRELIC_ENDPOINT` | No | `https://api.newrelic.com/v2` | `.env` | API endpoint |
173+
174+
<details>
175+
<summary>Example</summary>
176+
177+
TBD
178+
179+
</details>
180+
181+
## Slack
182+
183+
Post deployment notification to Slack a channel.
184+
185+
### Setup
186+
187+
1. [Create a Slack app and Incoming Webhook](https://api.slack.com/messaging/webhooks).
188+
2. Add `VORTEX_NOTIFY_SLACK_WEBHOOK` variable to your hosting
189+
provider's global environment variables.
190+
3. Optionally, add other Slack-related variables to your `.env` file to
191+
customize the notification.
192+
193+
### Environment variables
194+
195+
| Variable | Required | Default | Location | Description |
196+
|----------------------------------|----------|-------------------------|----------|-----------------------------|
197+
| `VORTEX_NOTIFY_SLACK_WEBHOOK` | **Yes** | | Hosting | Slack Incoming Webhook URL |
198+
| `VORTEX_NOTIFY_SLACK_PROJECT` | No | `VORTEX_NOTIFY_PROJECT` | `.env` | Project name |
199+
| `VORTEX_NOTIFY_SLACK_CHANNEL` | No | | `.env` | Target channel (overrides) |
200+
| `VORTEX_NOTIFY_SLACK_USERNAME` | No | `Deployment Bot` | `.env` | Bot display name |
201+
| `VORTEX_NOTIFY_SLACK_ICON_EMOJI` | No | `:rocket:` | `.env` | Bot icon emoji |
202+
203+
<details>
204+
<summary>Example</summary>
205+
206+
TBD
207+
208+
</details>
209+
210+
## Webhook
211+
212+
Send HTTP request to an arbitrary webhook URL.
213+
214+
### Setup
215+
216+
1. Add `VORTEX_NOTIFY_WEBHOOK_URL` variable to your `.env` file or
217+
hosting provider's global environment variables.
218+
2. Optionally, add other webhook-related variables to your `.env` file
219+
to customize the notification.
220+
221+
### Environment variables
222+
223+
| Variable | Required | Default | Location | Description |
224+
|-----------------------------------------|----------|----------------------------------|-------------------|-------------------------|
225+
| `VORTEX_NOTIFY_WEBHOOK_URL` | **Yes** | | `.env` or Hosting | Webhook endpoint URL |
226+
| `VORTEX_NOTIFY_WEBHOOK_PROJECT` | No | `VORTEX_NOTIFY_PROJECT` | Hosting | Project name |
227+
| `VORTEX_NOTIFY_WEBHOOK_METHOD` | No | `POST` | `.env` | HTTP method |
228+
| `VORTEX_NOTIFY_WEBHOOK_HEADERS` | No | `Content-Type: application/json` | `.env` | Pipe-separated headers |
229+
| `VORTEX_NOTIFY_WEBHOOK_PAYLOAD` | No | JSON with substitution variables | `.env` | JSON payload |
230+
| `VORTEX_NOTIFY_WEBHOOK_RESPONSE_STATUS` | No | `200` | `.env` | Expected HTTP status |
231+
232+
<details>
233+
<summary>Example</summary>
234+
235+
TBD
236+
237+
</details>

0 commit comments

Comments
 (0)