diff --git a/src/pages/docs/administration/managing-infrastructure/slack-integration.md b/src/pages/docs/administration/managing-infrastructure/slack-integration.md new file mode 100644 index 0000000000..315614e623 --- /dev/null +++ b/src/pages/docs/administration/managing-infrastructure/slack-integration.md @@ -0,0 +1,86 @@ +--- +layout: src/layouts/Default.astro +pubDate: 2026-07-03 +modDate: 2026-07-03 +title: Slack integration +description: Connect a Slack workspace to Octopus Deploy to send subscription notifications and deployment messages to Slack channels. +navOrder: 1700 +--- + +Connecting a Slack workspace to Octopus lets you send subscription events and deployment notifications to Slack channels. Once connected, you can: + +- Configure [subscriptions](/docs/administration/managing-infrastructure/subscriptions) to post event digests to channels. +- Add a [Send a Slack Message](/docs/projects/built-in-step-templates/send-slack-message) step to your deployment or runbook processes. + +Slack integration is available from Octopus Server version `2026.3.1827`. + +## Prerequisites + +You need permission to install apps in your Slack workspace. If you don't have this permission, ask a Slack workspace owner or admin to complete the setup. + +## Connect Octopus to Slack {#slack-integration-connect} + +To connect Octopus to Slack, navigate to **Configuration ➜ Settings ➜ Slack integration** and click **Add Slack Connection**. The wizard in Octopus will walk you through the steps outlined below. + +### 1. Create your Slack app + +Octopus generates a JSON app manifest pre-configured with the correct redirect URL and OAuth scopes. The wizard displays this manifest for you to copy. + +In a new tab, go to [Slack API Apps](https://api.slack.com/apps) and: + +1. Click **Create New App**. +2. Choose **From an app manifest**. +3. Select your workspace. +4. Paste the manifest Octopus generated and click **Next**, then **Create**. + +:::div{.hint} +The manifest uses your Octopus server's public address as the OAuth redirect URL. If the URL shown in the manifest doesn't match the address users access Octopus at, update the `redirect_urls` value before pasting. You can configure the public URL under **Configuration ➜ Nodes**. +::: + +Once you've created the Slack app, return to Octopus and click **I Created The App**. + +### 2. Add credentials + +In your new Slack app, go to **Basic Information** and copy the **Client ID** and **Client Secret**. Paste these into Octopus and click **Save And Continue**. + +### 3. Authorize Octopus in Slack + +Click **Open Slack To Authorize**. This opens Slack's OAuth consent page in a new tab. Review the requested scopes and click **Allow**. + +Once you approve, Octopus detects the connection automatically and moves to the next step. + +#### Scopes + +Octopus requests the following scopes when authorizing: + +| Scope | Purpose | +| ----- | ------- | +| `chat:write` | Post messages as Octopus | +| `chat:write.public` | Post in channels not invited | +| `channels:read` | List public channels | +| `groups:read` | List private channels invited to | +| `team:read` | Read workspace name | +| `users:read` | Read the bot user's display name | + +### 4. Confirm the connection + +Your workspace is now connected. You can optionally send a test message to `#general` to confirm everything is working before finishing. + +## Test the connection {#slack-integration-test} + +After connecting, you can send a test message at any time from **Configuration ➜ Settings ➜ Slack integration**. Select a channel and click **Send Test Message**. Octopus posts a short message to the selected channel so you can confirm the bot is working. + +## Public and private channels {#slack-integration-channels} + +By default the Slack app can post to any public channel in your workspace without needing to be invited. + +For private channels, you will need to type the name of the channel when selecting which channel to post to. The Slack app must be a member of the channel. See the [Slack documentation on apps](https://slack.com/help/articles/360001537467-Guide-to-apps-in-Slack) for instructions on adding the app to a channel. + +## Disconnect {#slack-integration-disconnect} + +To disconnect the Slack integration, go to **Configuration ➜ Settings ➜ Slack integration** and click **Disconnect**. This removes the stored credentials and OAuth token. You can reconnect at any time by running the wizard again. + +## What's next + +- [Subscriptions](/docs/administration/managing-infrastructure/subscriptions): configure Octopus to post event digests to Slack channels. +- [Send a Slack Message step](/docs/projects/built-in-step-templates/send-slack-message): post messages to Slack as part of a deployment or runbook process. diff --git a/src/pages/docs/administration/managing-infrastructure/subscriptions/index.md b/src/pages/docs/administration/managing-infrastructure/subscriptions/index.md index c91facb968..9a06f58c0c 100644 --- a/src/pages/docs/administration/managing-infrastructure/subscriptions/index.md +++ b/src/pages/docs/administration/managing-infrastructure/subscriptions/index.md @@ -1,13 +1,13 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2025-10-28 +modDate: 2026-07-03 title: Subscriptions description: Subscriptions allow you to subscribe to events that are happening within Octopus, so you can be notified when events have occurred and react accordingly. navOrder: 1600 --- -Subscriptions allow you to subscribe to events that are happening within Octopus, so you can be notified when events have occurred and react accordingly. Both **email** and **webhook** notifications are currently supported. +Subscriptions allow you to subscribe to events that are happening within Octopus, so you can be notified when events have occurred and react accordingly. **Email**, **webhook**, and **Slack** notifications are supported. Subscriptions can be accessed from the `Configuration` menu. @@ -17,7 +17,7 @@ For earlier versions of Octopus, Subscriptions can be accessed from the **Config ::: :::figure -![](/docs/img/administration/managing-infrastructure/subscriptions/images/subscriptions-menu.png) +![Subscriptions menu](/docs/img/administration/managing-infrastructure/subscriptions/images/subscriptions-menu.png) ::: ## Email notifications {#Subscriptions-EmailNotifications} @@ -35,19 +35,20 @@ Let's say you have some critical projects and you want your administrators to re Consider the following example: :::figure -![](/docs/img/administration/managing-infrastructure/subscriptions/images/subscriptions-email-example.png) +![Subscriptions email example](/docs/img/administration/managing-infrastructure/subscriptions/images/subscriptions-email-example.png) ::: -We can select the _Deployment-critical events_ group, which will automatically filter all deployment-critical events for us. +We can select the *Deployment-critical events* group, which will automatically filter all deployment-critical events for us. -We can then select just the projects/environments we want to monitor. In this case: our _Infrastructure_ or _Code_ projects. Also, we only want to get notified when these critical events occur in our _Production_ environment. +We can then select just the projects/environments we want to monitor. In this case: our *Infrastructure* or *Code* projects. Also, we only want to get notified when these critical events occur in our *Production* environment. -So in this example, all users in the _Octopus Administrators_ team (with a valid email address) will receive an email notification for _Deployment-critical events_, in the _Infrastructure_ or _Code_ projects, that occurred in our _Production_ environment. +So in this example, all users in the *Octopus Administrators* team (with a valid email address) will receive an email notification for *Deployment-critical events*, in the *Infrastructure* or *Code* projects, that occurred in our *Production* environment. :::div{.hint} Each filter you add is an "AND," while each option you add to the filter is an "OR." A subscription with the filters: + - Event Categories: Deployment Started - Environments: Staging, Production - Projects: Hello World @@ -62,13 +63,12 @@ You can read more about getting started with notifications in our [Getting Start In this example, we have also configured the timezone drop-down so all dates shown in the emails will be in our preferred timezone. ::: -We can then hit _Save_ and this subscription will show up in our subscriptions list screen. +We can then hit *Save* and this subscription will show up in our subscriptions list screen. ## Role permissions Each email will be customized based on the user's roles, so they will only be emailed with events that they have permission to see. See the "Event Visibility and Permissions" section below for more details. - ## Webhook notifications {#Subscriptions-WebhookNotifications} Webhook notifications allow you to receive a JSON payload, posted to a specified URL when events have occurred. Webhook notifications will be sent **per event** (unlike email notifications that send a digest of events) and will include a payload with the following structure: @@ -92,16 +92,16 @@ Webhook notifications allow you to receive a JSON payload, posted to a specified The `Payload` includes: -| Property | Hint | Description | -| ---------------------------- | ---- | ----------- | -| ServerUri | \* | The Octopus Server that generated this webhook | -| ServerAuditUri | \* | The URL to the Octopus Server's audit screen where this event may be found in more detail | -| Subscription | | The subscription object that triggered this webhook (including all filtering criteria so you can see exactly why you are receiving this webhook) | -| Event | | The event object that this webhook is responding to | -| BatchProcessingDate | | The processing date for the current batch. For 'Single' payload types, the events will be sent in batches. The batch date is included here for your reference | -| BatchId | \** | A unique GUID given to the current batch of events being processed | -| TotalEventsInBatch | \** | The total number of events, in the current batch of events being processed | -| EventNumberInBatch | \** | The event number of this event, in the current batch of events being processed | +| Property | Hint | Description | +| -------- | ---- | ----------- | +| ServerUri | \* | The Octopus Server that generated this webhook | +| ServerAuditUri | \* | The URL to the Octopus Server's audit screen where this event may be found in more detail | +| Subscription | | The subscription object that triggered this webhook (including all filtering criteria so you can see exactly why you are receiving this webhook) | +| Event | | The event object that this webhook is responding to | +| BatchProcessingDate | | The processing date for the current batch. For 'Single' payload types, the events will be sent in batches. The batch date is included here for your reference | +| BatchId | \** | A unique GUID given to the current batch of events being processed | +| TotalEventsInBatch | \** | The total number of events, in the current batch of events being processed | +| EventNumberInBatch | \** | The event number of this event, in the current batch of events being processed | \* This property will be null unless the publicly-accessible URL has been set for your Octopus instance (see the **Configuration ➜ Nodes ➜ Configuration Settings** menu). @@ -112,6 +112,17 @@ The `Payload` includes: While we make every effort to ensure events are only ever sent *once* to a given email or webhook subscription, we can offer no guarantees and advise that you design your consuming API with this in mind. ::: +## Slack notifications {#Subscriptions-SlackNotifications} + +Slack notifications post a digest of events to one or more channels in a connected Slack workspace. Available from Octopus Server version `2026.3.1827`. + +The **Slack notifications** section is visible on the subscription form. If a Slack workspace isn't connected yet, the section shows a prompt to set one up. See [Slack integration](/docs/administration/managing-infrastructure/slack-integration) for setup instructions. + +Once connected, select or enter the channels to post to and set the frequency. + +Public channels in your workspace are listed automatically. To post to a private channel, type its name and add it. The Slack app must be a member of the channel. + +For more information on what channels the Slack app can post to, see [public and private channels](/docs/administration/managing-infrastructure/slack-integration#slack-integration-channels). ## Event visibility and permissions {#Subscriptions-Event-Visibility-and-Permissions} @@ -229,84 +240,84 @@ The following is a list of all options for subscriptions including Event Groups, | Task canceled | | User password changed | -| DOCUMENT TYPES | -|--------------------------------------| -| Account | -| Action Template | -| Action Template Version | -| Api Key | -| Artifact | -| Auto Deploy Queue Item | -| Build Information | -| Certificate | -| Channel | -| Community Action Template | -| Connect Project to Tenants Task | -| Dashboard Configuration | -| Data Migration State | -| Deleted Space | -| Deployment | -| Deployment Completion | -| Deployment Environment | -| Deployment Freeze | -| Deployment Freeze Override | -| Deployment History | -| Deployment Process | -| Deployment Settings | -| Deployment Target Tag | -| Deprecation Usage | -| Event | -| Extension Configuration | -| Feature Toggle | +| DOCUMENT TYPES | +|---------------------------------------| +| Account | +| Action Template | +| Action Template Version | +| Api Key | +| Artifact | +| Auto Deploy Queue Item | +| Build Information | +| Certificate | +| Channel | +| Community Action Template | +| Connect Project to Tenants Task | +| Dashboard Configuration | +| Data Migration State | +| Deleted Space | +| Deployment | +| Deployment Completion | +| Deployment Environment | +| Deployment Freeze | +| Deployment Freeze Override | +| Deployment History | +| Deployment Process | +| Deployment Settings | +| Deployment Target Tag | +| Deprecation Usage | +| Event | +| Extension Configuration | +| Feature Toggle | | Feature Toggle Publishing Signing Key | -| Feed | -| Git Credential | -| Git Hub App Connection | -| Git Hub App Token | -| Insights Report | -| Interruption | -| Invitation | -| Kubernetes Monitor | -| Kubernetes Resource Manifest | -| Kubernetes Task Resource Status | -| Library Variable Set | -| Lifecycle | -| Machine | -| Machine Policy | -| Octopus Server Node | -| Process Execution | -| Project | -| Project Group | -| Project Intents | -| Project Trigger | -| Proxy | -| Release | -| Runbook | -| Runbook Process | -| Runbook Run | -| Runbook Run History | -| Runbooks Snapshot | -| Sample Project | -| Scoped User Role | -| Server Task | -| Server Task Approval | -| Server Account Oidc Identity | -| Signing Key | -| Space | -| Subscription | -| Tag Set | -| Team | -| Tenant | -| Tenant Variable | -| User | -| User Favorite Project | -| User Onboarding | -| User Role | -| User Session | -| Variable Set | -| Worker | -| Worker Pool | -| Worker Task Lease | +| Feed | +| Git Credential | +| Git Hub App Connection | +| Git Hub App Token | +| Insights Report | +| Interruption | +| Invitation | +| Kubernetes Monitor | +| Kubernetes Resource Manifest | +| Kubernetes Task Resource Status | +| Library Variable Set | +| Lifecycle | +| Machine | +| Machine Policy | +| Octopus Server Node | +| Process Execution | +| Project | +| Project Group | +| Project Intents | +| Project Trigger | +| Proxy | +| Release | +| Runbook | +| Runbook Process | +| Runbook Run | +| Runbook Run History | +| Runbooks Snapshot | +| Sample Project | +| Scoped User Role | +| Server Task | +| Server Task Approval | +| Server Account Oidc Identity | +| Signing Key | +| Space | +| Subscription | +| Tag Set | +| Team | +| Tenant | +| Tenant Variable | +| User | +| User Favorite Project | +| User Onboarding | +| User Role | +| User Session | +| Variable Set | +| Worker | +| Worker Pool | +| Worker Task Lease | \* License key expiry events are only available in Octopus Server version `2025.2.6402` and later. diff --git a/src/pages/docs/best-practices/deployments/notifications.md b/src/pages/docs/best-practices/deployments/notifications.md index 7edfcd32c4..e51e18e3c4 100644 --- a/src/pages/docs/best-practices/deployments/notifications.md +++ b/src/pages/docs/best-practices/deployments/notifications.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2023-01-01 +modDate: 2026-07-03 title: Notifications description: Guidelines and recommendations for notifications in Octopus Deploy. navOrder: 100 @@ -10,9 +10,9 @@ hideInThisSection: true Octopus Deploy provides multiple mechanisms for notifying you and your users of specific actions within Octopus Deploy. These include: -- [Subscriptions](/docs/administration/managing-infrastructure/subscriptions) to send out notifications when specific events occur within Octopus. Both email and webhook subscriptions are currently supported. +- [Subscriptions](/docs/administration/managing-infrastructure/subscriptions) to send out notifications when specific events occur within Octopus. Email, webhook, and Slack subscriptions are supported. - [Email notification step](/docs/projects/built-in-step-templates/email-notifications) to send out an email during a deployment or runbook run. -- [Slack notification step template](https://library.octopus.com/step-templates/99e6f203-3061-4018-9e34-4a3a9c3c3179/actiontemplate-slack-send-simple-notification) to send out Slack messages during a deployment or runbook run. +- [Slack notification step template](https://library.octopus.com/step-templates/99e6f203-3061-4018-9e34-4a3a9c3c3179/actiontemplate-slack-send-simple-notification) to send out Slack messages during a deployment or runbook run. From version `2026.3.5228`, you can use the [built-in Send a Slack Message step](/docs/projects/built-in-step-templates/send-slack-message) instead. - [Microsoft Teams notification step template](https://library.octopus.com/step-templates/110a8b1e-4da4-498a-9209-ef8929c31168/actiontemplate-microsoft-teams-post-a-message) to send out messages to Microsoft Teams during a deployment or runbook run. - [Twilio - send SMS step template](https://library.octopus.com/step-templates/3c3904a9-d08c-4f18-b86c-0304800bb541/actiontemplate-twilio-send-sms-(powershell)) to send out an SMS message during a deployment or runbook run. @@ -30,6 +30,7 @@ If you are not careful with your subscription, you could end up with a lot of "n Each filter you add is an "AND," while each option you add to the filter is an "OR." A subscription with the filters: + - Event Categories: Deployment Started - Environments: Staging, Production - Projects: Hello World @@ -61,4 +62,3 @@ For further reading on subscriptions and other notifications in Octopus Deploy p - [Subscriptions](/docs/administration/managing-infrastructure/subscriptions) - [Email Notifications](/docs/projects/built-in-step-templates/email-notifications) - diff --git a/src/pages/docs/projects/built-in-step-templates/send-slack-message.md b/src/pages/docs/projects/built-in-step-templates/send-slack-message.md new file mode 100644 index 0000000000..4c17e2216b --- /dev/null +++ b/src/pages/docs/projects/built-in-step-templates/send-slack-message.md @@ -0,0 +1,38 @@ +--- +layout: src/layouts/Default.astro +pubDate: 2026-07-03 +modDate: 2026-07-03 +title: Send a Slack Message step +description: Send a Slack Message steps let you post messages to Slack channels as part of a deployment or runbook process. +navOrder: 20 +--- + +The Send a Slack Message step posts a message to one or more Slack channels during a deployment or runbook run. You can use it to notify your team when a deployment succeeds or fails, or at any point in your deployment process. + +The Send a Slack Message step is available from Octopus Server version `2026.3.5228`. + +You can add this step to a process at any time. If a Slack workspace isn't connected yet, the step editor shows a prompt to set one up. See [Slack integration](/docs/administration/managing-infrastructure/slack-integration) for instructions. + +## Add the step + +1. Navigate to your project's deployment process and click **Add step**. +2. Search for and select **Send a Slack Message**. +3. Give the step a short memorable name. +4. Select one or more **Channels** to post to. For more information on what channels the Slack app can post to, see [public and private channels](/docs/administration/managing-infrastructure/slack-integration#slack-integration-channels). +5. Enter the **Message** to post. +6. Set conditions to determine when the step runs. +7. Save the deployment process. + +## Message formatting {#send-slack-message-formatting} + +The message field supports [Slack markdown formatting](https://api.slack.com/reference/surfaces/formatting) and [Octopus variable substitution](/docs/projects/variables/variable-substitutions). + +### Example + +```text +#{Octopus.Project.Name} #{Octopus.Release.Number} to #{Octopus.Environment.Name} has #{if Octopus.Deployment.Error}failed#{else}completed successfully#{/if}. <#{Octopus.Web.ServerUri}#{Octopus.Web.DeploymentLink}|View deployment> +``` + +:::div{.hint} +See [system variables](/docs/projects/variables/system-variables) for the full list of variables available during a deployment. +:::