diff --git a/documentation/advanced-features/notifications.md b/documentation/advanced-features/notifications.md index 1faae0b44..18343fc14 100644 --- a/documentation/advanced-features/notifications.md +++ b/documentation/advanced-features/notifications.md @@ -24,9 +24,49 @@ Notifications are configured in the `creds.json` file, since they often contain ## Usage -If you want to send a notification for a specific execution, add the `--notify` flag to the `dnscontrol preview` or `dnscontrol push` commands. +There are two ways to enable notifications: -To always send notifications, enable one or more of the `notify_on_push` or `notify_on_preview` options. +1. **On-demand**: Add the `--notify` flag to `dnscontrol preview` or `dnscontrol push` commands +2. **Automatic**: Enable `notify_on_push` or `notify_on_preview` in your `creds.json` + +### Automatic notifications + +To automatically send notifications without using the `--notify` flag, configure these options in your `creds.json`: + +- `notify_on_push`: Set to `true` to send notifications during `dnscontrol push` (when changes are applied) +- `notify_on_preview`: Set to `true` to send notifications during `dnscontrol preview` (dry-run mode) + +**Example: Notifications only for actual changes (push)** + +{% code title="creds.json" %} +```json +{ + "notifications": { + "notify_on_push": true, + "notify_on_preview": false, + "slack_url": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL" + } +} +``` +{% endcode %} + +**Example: Notifications for both preview and push** + +{% code title="creds.json" %} +```json +{ + "notifications": { + "notify_on_push": true, + "notify_on_preview": true, + "teams_url": "https://outlook.office.com/webhook/..." + } +} +``` +{% endcode %} + +With automatic notifications enabled, you don't need to use the `--notify` flag. The `--notify` flag will still work to send notifications on-demand regardless of these settings. + +### Example DNS change Below is an example where we add [the A record](../language-reference/domain-modifiers/A.md) `foo` and display the notification output. @@ -40,11 +80,24 @@ D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), ### Preview example -In case of `dnscontrol preview`: +Preview notifications show what changes would be made without applying them: +{% tabs %} + +{% tab title="With --notify flag" %} ```shell dnscontrol preview --notify ``` +{% endtab %} + +{% tab title="Automatically" %} +```shell +# Requires notify_on_preview: true in creds.json +dnscontrol preview +``` +{% endtab %} + +{% endtabs %} **The notification output** @@ -54,11 +107,24 @@ dnscontrol preview --notify ### Push example -In case of `dnscontrol push`: +Push notifications show the actual changes being applied: +{% tabs %} + +{% tab title="With --notify flag" %} ```shell dnscontrol push --notify ``` +{% endtab %} + +{% tab title="Automatically" %} +```shell +# Requires notify_on_push: true in creds.json +dnscontrol push +``` +{% endtab %} + +{% endtabs %} **The notification output** diff --git a/documentation/advanced-features/writing-providers.md b/documentation/advanced-features/writing-providers.md index 0a2e020a0..c0da36b84 100644 --- a/documentation/advanced-features/writing-providers.md +++ b/documentation/advanced-features/writing-providers.md @@ -2,7 +2,7 @@ Writing a new DNS provider is a relatively straightforward process. You essentially need to implement the -[providers.DNSServiceProvider interface.](https://pkg.go.dev/github.com/StackExchange/dnscontrol/pkg/providers#DNSServiceProvider) +[providers.DNSServiceProvider interface.](https://pkg.go.dev/github.com/StackExchange/dnscontrol/v4/pkg/providers#DNSServiceProvider) and the system takes care of the rest. Please do note that if you submit a new provider you will be @@ -122,7 +122,7 @@ Directory names should be consistent. It should be all lowercase and match the ## Step 4: Activate the driver Edit -[providers/\_all/all.go](https://github.com/StackExchange/dnscontrol/blob/main/pkg/pkg/providers/_all/all.go). +[providers/\_all/all.go](https://github.com/StackExchange/dnscontrol/blob/main/pkg/providers/_all/all.go). Add the provider list so DNSControl knows it exists. ## Step 5: Implement