opensource/coder
3
0
Fork 0
mirror of https://github.com/coder/coder.git synced 2026-09-24 15:04:27 +08:00
Code Issues Packages Projects Releases Wiki Activity

feat: support custom notifications (#19751)

Browse Source 
## Description

Adds support for sending an ad‑hoc custom notification to the
authenticated user via API and CLI. This is useful for surfacing the
result of scripts or long‑running tasks. Notifications are delivered
through the configured method and the dashboard Inbox, respecting
existing preferences and delivery settings.

## Changes

* New notification template: “Custom Notification” with a label for a
custom title and a custom message.
* New API endpoint: `POST /api/v2/notifications/custom` to send a custom
notification to the requesting user.
* New API endpoint: `GET /notifications/templates/custom` to get custom
notification template.
* New CLI subcommand: `coder notifications custom <title> <message>` to
send a custom notification to the requesting user.
* Documentation updates: Add a “Custom notifications” section under
Administration > Monitoring > Notifications, including instructions on
sending custom notifications and examples of when to use them.

Closes: https://github.com/coder/coder/issues/19611
This commit is contained in:
Susana Ferreira
2025-09-11 15:08:57 +02:00
committed by GitHub
parent 4c98decfb7
commit eec6c8c120
26 changed files with 1056 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/admin/monitoring/notifications/index.md
+40 -1
View File
@@ -143,9 +143,11 @@ After setting the required fields above:
```text
CODER_EMAIL_SMARTHOST=smtp.gmail.com:465
CODER_EMAIL_AUTH_USERNAME=<user>@<domain>
CODER_EMAIL_AUTH_PASSWORD="<app password created above>"
CODER_EMAIL_AUTH_PASSWORD="<app password created above (no spaces)>"
```
**Note:** The `CODER_EMAIL_AUTH_PASSWORD` must be entered without spaces.
See
[this help article from Google](https://support.google.com/a/answer/176600?hl=en)
for more options.
@@ -261,6 +263,43 @@ Administrators can configure which delivery methods are used for each different
You can find this page under
`https://$CODER_ACCESS_URL/deployment/notifications?tab=events`.
## Custom notifications
Custom notifications let you send an ad‑hoc notification to yourself using the Coder CLI.
These are useful for surfacing the result of long-running tasks or important state changes.
At this time, custom notifications can only be sent to the user making the request.
To send a custom notification, execute [`coder notifications custom <title> <message>`](../../../reference/cli/notifications_custom.md).
<!-- TODO(ssncferreira): Update when sending custom notifications to multiple users/roles is supported.
Explain deduplication behaviour for multiple users/roles.
See: https://github.com/coder/coder/issues/19768
-->
**Note:** The recipient is always the requesting user as targeting other users or groups isn’t supported yet.
### Examples
- Send yourself a quick update:
```shell
coder templates push -y && coder notifications custom "Template push complete" "Template version uploaded."
```
- Use in a script after a long-running task:
```shell
#!/usr/bin/env bash
set -o pipefail
if make test 2>&1 | tee test_output.log; then
coder notifications custom "Tests Succeeded" $'Test results:\n • ✅ success'
else
failures=$(grep -Po '\d+(?=\s+failures)' test_output.log | tail -n1 || echo 0)
coder notifications custom "Tests Failed" $'Test results:\n • ❌ failed ('"$failures"' tests failed)'
exit 1
fi
```
## Stop sending notifications
Administrators may wish to stop _all_ notifications across the deployment. We
docs/manifest.json
+5
View File
@@ -1287,6 +1287,11 @@
"description": "Manage Coder notifications",
"path": "reference/cli/notifications.md"
},
{
"title": "notifications custom",
"description": "Send a custom notification",
"path": "reference/cli/notifications_custom.md"
},
{
"title": "notifications pause",
"description": "Pause notifications",
docs/reference/api/notifications.md
Generated
+122 -3
View File
@@ -1,5 +1,64 @@
# Notifications
## Send a custom notification
### Code samples
```shell
# Example request using curl
curl -X POST http://coder-server:8080/api/v2/notifications/custom \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`POST /notifications/custom`
> Body parameter
```json
{
"content": {
"message": "string",
"title": "string"
}
}
```
### Parameters
| Name | In | Type | Required | Description |
|--------|------|------------------------------------------------------------------------------------|----------|--------------------------------------|
| `body` | body | [codersdk.CustomNotificationRequest](schemas.md#codersdkcustomnotificationrequest) | true | Provide a non-empty title or message |
### Example responses
> 400 Response
```json
{
"detail": "string",
"message": "string",
"validations": [
{
"detail": "string",
"field": "string"
}
]
}
```
### Responses
| Status | Meaning | Description | Schema |
|--------|----------------------------------------------------------------------------|-----------------------------------------------|--------------------------------------------------|
| 204 | [No Content](https://tools.ietf.org/html/rfc7231#section-6.3.5) | No Content | |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | Invalid request body | [codersdk.Response](schemas.md#codersdkresponse) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | System users cannot send custom notifications | [codersdk.Response](schemas.md#codersdkresponse) |
| 500 | [Internal Server Error](https://tools.ietf.org/html/rfc7231#section-6.6.1) | Failed to send custom notification | [codersdk.Response](schemas.md#codersdkresponse) |
To perform this operation, you must be authenticated. [Learn more](authentication.md).
## Get notification dispatch methods
### Code samples
@@ -315,6 +374,65 @@ curl -X PUT http://coder-server:8080/api/v2/notifications/settings \
To perform this operation, you must be authenticated. [Learn more](authentication.md).
## Get custom notification templates
### Code samples
```shell
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/notifications/templates/custom \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`GET /notifications/templates/custom`
### Example responses
> 200 Response
```json
[
{
"actions": "string",
"body_template": "string",
"enabled_by_default": true,
"group": "string",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"kind": "string",
"method": "string",
"name": "string",
"title_template": "string"
}
]
```
### Responses
| Status | Meaning | Description | Schema |
|--------|----------------------------------------------------------------------------|----------------------------------------------------|-----------------------------------------------------------------------------------|
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | array of [codersdk.NotificationTemplate](schemas.md#codersdknotificationtemplate) |
| 500 | [Internal Server Error](https://tools.ietf.org/html/rfc7231#section-6.6.1) | Failed to retrieve 'custom' notifications template | [codersdk.Response](schemas.md#codersdkresponse) |
<h3 id="get-custom-notification-templates-responseschema">Response Schema</h3>
Status Code **200**
| Name | Type | Required | Restrictions | Description |
|------------------------|--------------|----------|--------------|-------------|
| `[array item]` | array | false | | |
| `» actions` | string | false | | |
| `» body_template` | string | false | | |
| `» enabled_by_default` | boolean | false | | |
| `» group` | string | false | | |
| `» id` | string(uuid) | false | | |
| `» kind` | string | false | | |
| `» method` | string | false | | |
| `» name` | string | false | | |
| `» title_template` | string | false | | |
To perform this operation, you must be authenticated. [Learn more](authentication.md).
## Get system notification templates
### Code samples
@@ -350,9 +468,10 @@ curl -X GET http://coder-server:8080/api/v2/notifications/templates/system \
### Responses
| Status | Meaning | Description | Schema |
|--------|---------------------------------------------------------|-------------|-----------------------------------------------------------------------------------|
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | array of [codersdk.NotificationTemplate](schemas.md#codersdknotificationtemplate) |
| Status | Meaning | Description | Schema |
|--------|----------------------------------------------------------------------------|----------------------------------------------------|-----------------------------------------------------------------------------------|
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | array of [codersdk.NotificationTemplate](schemas.md#codersdknotificationtemplate) |
| 500 | [Internal Server Error](https://tools.ietf.org/html/rfc7231#section-6.6.1) | Failed to retrieve 'system' notifications template | [codersdk.Response](schemas.md#codersdkresponse) |
<h3 id="get-system-notification-templates-responseschema">Response Schema</h3>
docs/reference/api/schemas.md
Generated
+33
View File
@@ -1872,6 +1872,39 @@ CreateWorkspaceRequest provides options for creating a new workspace. Only one o
| `oidc_convert` |
| `tailnet_resume` |
## codersdk.CustomNotificationContent
```json
{
"message": "string",
"title": "string"
}
```
### Properties
| Name | Type | Required | Restrictions | Description |
|-----------|--------|----------|--------------|-------------|
| `message` | string | false | | |
| `title` | string | false | | |
## codersdk.CustomNotificationRequest
```json
{
"content": {
"message": "string",
"title": "string"
}
}
```
### Properties
| Name | Type | Required | Restrictions | Description |
|-----------|--------------------------------------------------------------------------|----------|--------------|-------------|
| `content` | [codersdk.CustomNotificationContent](#codersdkcustomnotificationcontent) | false | | |
## codersdk.CustomRoleRequest
```json
docs/reference/cli/notifications.md
Generated
+13 -7
View File
@@ -19,7 +19,7 @@ coder notifications
Administrators can use these commands to change notification settings.
- Pause Coder notifications. Administrators can temporarily stop notifiers from
dispatching messages in case of the target outage (for example: unavailable SMTP
server or Webhook not responding).:
server or Webhook not responding):
$ coder notifications pause
@@ -28,15 +28,21 @@ server or Webhook not responding).:
$ coder notifications resume
- Send a test notification. Administrators can use this to verify the notification
target settings.:
target settings:
$ coder notifications test
- Send a custom notification to the requesting user. Sending notifications
targeting other users or groups is currently not supported:
$ coder notifications custom "Custom Title" "Custom Message"
```
## Subcommands
| Name | Purpose |
|--------------------------------------------------|--------------------------|
| [<code>pause</code>](./notifications_pause.md) | Pause notifications |
| [<code>resume</code>](./notifications_resume.md) | Resume notifications |
| [<code>test</code>](./notifications_test.md) | Send a test notification |
| Name | Purpose |
|--------------------------------------------------|----------------------------|
| [<code>pause</code>](./notifications_pause.md) | Pause notifications |
| [<code>resume</code>](./notifications_resume.md) | Resume notifications |
| [<code>test</code>](./notifications_test.md) | Send a test notification |
| [<code>custom</code>](./notifications_custom.md) | Send a custom notification |
docs/reference/cli/notifications_custom.md
Generated
+10
View File
@@ -0,0 +1,10 @@
<!-- DO NOT EDIT | GENERATED CONTENT -->
# notifications custom
Send a custom notification
## Usage
```console
coder notifications custom <title> <message>
```