Skip to content

Commit 5dcab66

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

File tree

32 files changed

+1290
-49
lines changed

32 files changed

+1290
-49
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/.ahoy.yml‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,9 @@ commands:
6464
cmd: ./tests/lint.markdown.sh --fix
6565

6666
lint-docs:
67-
cmd: yarn --cwd=docs run lint
67+
cmd: |
68+
yarn --cwd=docs run lint
69+
yarn --cwd=./docs run spellcheck
6870
6971
test:
7072
name: Test Vortex project.

‎.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: 226 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,4 +5,229 @@ 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+
| 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 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
45+
value of the email address that is allowed to be sent from your
46+
hosting.
47+
2. Add `VORTEX_NOTIFY_EMAIL_RECIPIENTS` variable to `.env` file with a
48+
list of recipients in format
49+
`[email protected]|Webmaster` (comma-separated for
50+
multiple recipients).
51+
52+
### Environment variables
53+
54+
| Variable | Required | Default | Location | Description |
55+
|----------------------------------|----------|---------|----------|-----------------------------------------|
56+
| `VORTEX_NOTIFY_EMAIL_FROM` | **Yes** | | `.env` | Email address to send notifications from|
57+
| `VORTEX_NOTIFY_EMAIL_RECIPIENTS` | **Yes** | | `.env` | Recipients (format: `email\|name`) |
58+
59+
### Example
60+
61+
**Subject:**
62+
63+
```text
64+
My Project deployment notification of "main" branch
65+
```
66+
67+
**Body:**
68+
69+
```text
70+
## This is an automated message ##
71+
72+
Site My Project "main" branch has been deployed at 15/01/2025
73+
14:30:45 UTC and is available at https://example.com.
74+
75+
Login at: https://example.com/user/login
76+
```
77+
78+
## GitHub
79+
80+
GitHub supports deployment statuses and environment links. **Vortex** can
81+
automatically post deployment status to GitHub pull requests.
82+
83+
### Setup
84+
85+
1. [Create a GitHub personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens).
86+
2. Add `VORTEX_NOTIFY_GITHUB_TOKEN` variable to your hosting
87+
provider's global environment variables.
88+
3. Add `VORTEX_NOTIFY_GITHUB_REPOSITORY` variable to your hosting
89+
provider's global environment variables.
90+
91+
### Environment variables
92+
93+
| Variable | Required | Default | Location | Description |
94+
|-----------------------------------|----------|---------|----------|-----------------------------------|
95+
| `VORTEX_NOTIFY_GITHUB_TOKEN` | **Yes** | | Hosting | GitHub personal access token |
96+
| `VORTEX_NOTIFY_GITHUB_REPOSITORY` | **Yes** | | Hosting | Repository in `owner/repo` format |
97+
98+
### Example
99+
100+
The pull request page in GitHub has information about the deployment
101+
status.
102+
103+
![notification-github-before.png](/img/notification-github-before.png)
104+
105+
After deployment succeeds, a notification is posted to GitHub. You can use a
106+
`View deployment` button to quickly access the deployed environment.
107+
108+
![notification-github-after.png](/img/notification-github-after.png)
109+
110+
## JIRA
111+
112+
Post a deployment comment and, optionally, update issue status and
113+
assignee in JIRA.
114+
115+
### Setup
116+
117+
1. [Create a JIRA API token](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/).
118+
2. Add `VORTEX_NOTIFY_JIRA_TOKEN` variable to your hosting provider's
119+
global environment variables.
120+
3. Add `VORTEX_NOTIFY_JIRA_USER` variable to `.env` file.
121+
4. Add `VORTEX_NOTIFY_JIRA_ASSIGNEE` variable to `.env` file if you
122+
would like the issue to be assigned to this user once the deployment
123+
is complete.
124+
5. Add `VORTEX_NOTIFY_JIRA_TRANSITION` variable to `.env` file with a
125+
transition name if you would like the issue to be transitioned to
126+
once the deployment is complete.
127+
6. Optionally, modify the comment prefix by adding
128+
`VORTEX_NOTIFY_JIRA_COMMENT_PREFIX` variable to `.env` file.
129+
130+
### Environment variables
131+
132+
| Variable | Required | Default | Location | Description |
133+
|-------------------------------------|----------|------------------------------|----------|----------------------------|
134+
| `VORTEX_NOTIFY_JIRA_TOKEN` | **Yes** | | Hosting | JIRA API token |
135+
| `VORTEX_NOTIFY_JIRA_USER` | **Yes** | | `.env` | JIRA user email address |
136+
| `VORTEX_NOTIFY_JIRA_ASSIGNEE` | No | | `.env` | User email to assign to |
137+
| `VORTEX_NOTIFY_JIRA_TRANSITION` | No | | `.env` | State to transition to |
138+
| `VORTEX_NOTIFY_JIRA_ENDPOINT` | No | `https://jira.atlassian.com` | `.env` | JIRA API endpoint |
139+
| `VORTEX_NOTIFY_JIRA_COMMENT_PREFIX` | No | `"Deployed to "` | `.env` | Comment prefix |
140+
141+
### Example
142+
143+
**Comment posted to JIRA issue:**
144+
145+
```text
146+
Deployed to https://example.com
147+
```
148+
149+
The environment URL is displayed as an inline card in JIRA.
150+
151+
## New Relic
152+
153+
[Deployment markers](https://docs.newrelic.com/docs/apm/apm-ui-pages/events/record-deployments/)
154+
help you track code changes in New Relic APM by associating them with
155+
application performance data. **Vortex** can automatically create deployment
156+
markers in New Relic APM when a deployment is performed.
157+
158+
### Setup
159+
160+
1. [Create a New Relic API key](https://docs.newrelic.com/docs/apis/intro-apis/new-relic-api-keys/).
161+
2. Add `VORTEX_NOTIFY_NEWRELIC_APIKEY` variable to your hosting
162+
provider's global environment variables.
163+
3. Optionally, add other New Relic-related variables to your `.env`
164+
file to customize the notification.
165+
166+
### Environment variables
167+
168+
| Variable | Required | Default | Location | Description |
169+
|--------------------------------------|----------|--------------------------------------|----------|----------------------------|
170+
| `VORTEX_NOTIFY_NEWRELIC_APIKEY` | **Yes** | | Hosting | New Relic API key |
171+
| `VORTEX_NOTIFY_NEWRELIC_PROJECT` | No | `VORTEX_NOTIFY_PROJECT` | `.env` | Project name |
172+
| `VORTEX_NOTIFY_NEWRELIC_APP_NAME` | No | `{PROJECT}-{REF}` | `.env` | Application name |
173+
| `VORTEX_NOTIFY_NEWRELIC_APPID` | No | | `.env` | Application ID (auto) |
174+
| `VORTEX_NOTIFY_NEWRELIC_DESCRIPTION` | No | `"{ref} deployed"` | `.env` | Deployment description |
175+
| `VORTEX_NOTIFY_NEWRELIC_CHANGELOG` | No | `VORTEX_NOTIFY_NEWRELIC_DESCRIPTION` | `.env` | Deployment changelog |
176+
| `VORTEX_NOTIFY_NEWRELIC_USER` | No | `Deployment robot` | `.env` | User performing deployment |
177+
| `VORTEX_NOTIFY_NEWRELIC_ENDPOINT` | No | `https://api.newrelic.com/v2` | `.env` | API endpoint |
178+
179+
### Example
180+
181+
Deployment marker created in New Relic APM:
182+
183+
<img src="/img/notification-newrelic.png" alt="New Relic deployment marker" width="828"/>
184+
185+
## Slack
186+
187+
Post deployment notification to Slack a channel.
188+
189+
### Setup
190+
191+
1. [Create a Slack app and Incoming Webhook](https://api.slack.com/messaging/webhooks).
192+
2. Add `VORTEX_NOTIFY_SLACK_WEBHOOK` variable to your hosting
193+
provider's global environment variables.
194+
3. Optionally, add other Slack-related variables to your `.env` file to
195+
customize the notification.
196+
197+
### Environment variables
198+
199+
| Variable | Required | Default | Location | Description |
200+
|----------------------------------|----------|-------------------------|----------|-----------------------------|
201+
| `VORTEX_NOTIFY_SLACK_WEBHOOK` | **Yes** | | Hosting | Slack Incoming Webhook URL |
202+
| `VORTEX_NOTIFY_SLACK_PROJECT` | No | `VORTEX_NOTIFY_PROJECT` | `.env` | Project name |
203+
| `VORTEX_NOTIFY_SLACK_CHANNEL` | No | | `.env` | Target channel (overrides) |
204+
| `VORTEX_NOTIFY_SLACK_USERNAME` | No | `Deployment Bot` | `.env` | Bot display name |
205+
| `VORTEX_NOTIFY_SLACK_ICON_EMOJI` | No | `:rocket:` | `.env` | Bot icon emoji |
206+
207+
### Example
208+
209+
Notification posted to Slack channel using custom "VortexBot" Slack app:
210+
211+
<img src="/img/notification-slack.png" alt="Slack notification" width="528"/>
212+
213+
## Webhook
214+
215+
Send HTTP request to an arbitrary webhook URL.
216+
217+
### Setup
218+
219+
1. Add `VORTEX_NOTIFY_WEBHOOK_URL` variable to your `.env` file or
220+
hosting provider's global environment variables.
221+
2. Optionally, add other webhook-related variables to your `.env` file
222+
to customize the notification.
223+
224+
### Environment variables
225+
226+
| Variable | Required | Default | Location | Description |
227+
|-----------------------------------------|----------|----------------------------------|-------------------|-------------------------|
228+
| `VORTEX_NOTIFY_WEBHOOK_URL` | **Yes** | | `.env` or Hosting | Webhook endpoint URL |
229+
| `VORTEX_NOTIFY_WEBHOOK_PROJECT` | No | `VORTEX_NOTIFY_PROJECT` | Hosting | Project name |
230+
| `VORTEX_NOTIFY_WEBHOOK_METHOD` | No | `POST` | `.env` | HTTP method |
231+
| `VORTEX_NOTIFY_WEBHOOK_HEADERS` | No | `Content-Type: application/json` | `.env` | Pipe-separated headers |
232+
| `VORTEX_NOTIFY_WEBHOOK_PAYLOAD` | No | JSON with substitution variables | `.env` | JSON payload |
233+
| `VORTEX_NOTIFY_WEBHOOK_RESPONSE_STATUS` | No | `200` | `.env` | Expected HTTP status |

0 commit comments

Comments
 (0)