Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add documentation for Slack Workspace #3005

Closed
wants to merge 6 commits into from
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
21 changes: 19 additions & 2 deletions pages/integrations/slack.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,21 @@ Configuring a Slack notification service will authorize access for your desired

Setting up a Notification Service requires Buildkite organization admin access.

## Adding a notification service
## Adding notification services
There are two ways to add notification services: workspace-wide and channel-specific. We reccomend using a workspace. Using a workspace only requires a single authorization for the entire workspace, allowing you to connect channels via YAML rather than multiple notifications services. The migration to a Workspace will not impact current integration implementation.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I reckon it's also worth calling out that the workspace integration adds support for Slack mentions, specifically because we request an additional scope to read user email addresses.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
There are two ways to add notification services: workspace-wide and channel-specific. We reccomend using a workspace. Using a workspace only requires a single authorization for the entire workspace, allowing you to connect channels via YAML rather than multiple notifications services. The migration to a Workspace will not impact current integration implementation.
There are two ways to add notification services: workspace-wide and channel-specific. We recommend using a workspace. Using a workspace only requires a single authorization for the entire workspace, allowing you to connect channels via YAML rather than multiple notifications services. The migration to a Workspace will not impact current integration implementation.


### Adding workspace notification services
In your [Organization's Notification Settings](https://buildkite.com/organizations/-/services), add a Slack Workspace notification service:

<%= image "buildkite-add-slack-workspace.png", width: 1458/2, height: 142/2, alt: "Screenshot of the 'Add' button for adding a Slack workspace service to Buildkite" %>

Click the **Add to Slack** button:

<%= image "buildkite-add-to-slack-workspace.png", width: 1458/2, height: 358/2, alt: "Screenshot of 'Add Slack workspace service' screen on Buildkite. It shows an 'Add to Slack workspace' button" %>

This will take you to Slack. Log in, and grant Buildkite the ability to post across your workspace. Once you have granted access, you can then edit the YAML of your pipelines to [configure notifications](/docs/pipelines/notifications).

### Adding a channel-specific notification service

In your [Organization's Notification Settings](https://buildkite.com/organizations/-/services), add a Slack notification service:

Expand Down Expand Up @@ -36,7 +50,7 @@ With the configuration above, you'll receive notifications at the pipeline level

## Changing channels

Once created, the Slack channel and workspace cannot be changed. To post to a different channel or workspace, create a new notification service.
Once created, the Slack channel and workspace cannot be changed. To post to a different channel or workspace, create a new notification service. Alternatively, use a Slack Workspace to avoid the need to configure multiple notification services. Follow the process above to do so.

## Conditional notifications

Expand Down Expand Up @@ -69,3 +83,6 @@ Once you've found the matching Buildkite service and Slack app, confirm where an
### Create a new Slack notification service which posts

Using the instructions above, [add a new Buildkite notification service](/docs/integrations/slack#adding-a-notification-service) with the same settings as the legacy integration.

#### Slack Privacy Policy
For more details, please checkout the [Slack Marketplace Privacy Policy](https://api.slack.com/slack-marketplace/guidelines#privacy)
2 changes: 1 addition & 1 deletion pages/pipelines/conditionals.md
Original file line number Diff line number Diff line change
Expand Up @@ -322,7 +322,7 @@ The following variables are supported by the `if` attribute. Note that you canno
<tr>
<td><code>build.state</code></td>
<td><code>String</code></td>
<td>The state the current build is in<br><em>Available states:</em>, <code>started</code>, <code>scheduled</code>, <code>running</code>, <code>passed</code>, <code>failed</code>, <code>failing</code>, <code>blocked</code>, <code>canceling</code>, <code>canceled</code>, <code>skipped</code>, <code>not_run</code></td>
<td>The state the current build is in<br><em>Available states:</em>, <code>started</code>, <code>scheduled</code>, <code>running</code>, <code>passed</code>, <code>failed</code>, <code>failing</code>, <code>started_failing</code>, <code>blocked</code>, <code>canceling</code>, <code>canceled</code>, <code>skipped</code>, <code>not_run</code></td>
</tr>
<tr>
<td><code>build.tag</code></td>
Expand Down
22 changes: 20 additions & 2 deletions pages/pipelines/notifications.md
Original file line number Diff line number Diff line change
Expand Up @@ -150,9 +150,9 @@ You can set notifications:
* On build status events in the Buildkite UI, by using your Slack Notification Service's 'Build State Filtering' settings.
* On step status and other non-build events, by extending the Slack Notification Service using the `notify` attribute in your `pipeline.yml`.

Before adding a `notify` attribute to your `pipeline.yml`, ensure an organization admin has set up a [Slack integration](/docs/integrations/slack) for the channel or user that you want to post to. Buildkite customers on the [Enterprise](https://buildkite.com/pricing) plan can also check the ['Manage Notifications Services'](https://buildkite.com/organizations/~/security/pipelines) checkbox to create, edit, or delete notification services. For detailed information about setting up a Notification Service, see the [Slack integration page](/docs/integrations/slack).
Before adding a `notify` attribute to your `pipeline.yml`, ensure an organization admin has set up either a [Slack Workspace](/docs/integrations/slack) for a single authorization, or individual [notification services](/docs/integrations/slack) for the channel or user that you want to post to. Buildkite customers on the [Enterprise](https://buildkite.com/pricing) plan can also check the ['Manage Notifications Services'](https://buildkite.com/organizations/~/security/pipelines) checkbox to create, edit, or delete notification services. For detailed information about setting up a Notification Service, see the [Slack integration page](/docs/integrations/slack).

Once a Slack channel has been configured in your organization, add a Slack notification to your pipeline using the `slack` attribute of the `notify` YAML block. Remember that if you rename or modify the Slack channel for which the integration was set up, for example if you change it from public to private, you need to set up a new integration.
Once a Workspace or Slack channel has been configured in your organization, add a Slack notification to your pipeline using the `slack` attribute of the `notify` YAML block. Remember that if you rename or modify the Slack channel for which the integration was set up, for example if you change it from public to private, you need to set up a new integration. This is not required when using a Slack Workspace.

> 🚧
> When using only a channel name, you must specify it in quotes, as otherwise the `#` will cause the channel name to be treated as a comment.
Expand Down Expand Up @@ -198,6 +198,14 @@ notify:
```
{: codeblock-file="pipeline.yml"}


When using a Slack Workspace, provide the Slack user ID, which you can access via User > More options > Copy member ID.

```
notify:
- slack: "U123ABC456"
```

Step-level notifications to user `@someuser` in all configured workspaces:

```yaml
Expand Down Expand Up @@ -274,6 +282,16 @@ steps:
```
{: codeblock-file="pipeline.yml"}

### Notify in private channels

You can notify individuals in private channels by inviting the Buildkite Builds Slack App into the channel with `/add Buildkite Builds`. You must be using the [Slack Workspace integration](./integrations/slack.md)

```yaml
notify:
# Notify private channel
- slack: "buildkite-community#private-channel"
```

### Custom messages

You can define a custom message to send in the notification using the `message` attribute.
Expand Down
Loading