Slack Orb v4 Beta

Hello all! We have been working on a new iteration of the Slack orb, building it from the ground up to be more flexible and cover more use cases for notifying your team of various hapennings within your pipelines.

Since this is a complete re-imagining of the Slack orb, we are running a limited time beta so we can fully test and examine the behaviour in real-world use cases. It’s important to note that this is not a drop-in replacement - steps will need to be taken to fully implement it within your configuration.

The beta version of the orb can be selected by setting your orb version to dev:beta, as seen here:

version: 2.1

  slack: circleci/slack@dev:beta

What’s Changed?

First, we’re changing the way we work with the Slack API. Rather than passing a large glob of parameters within the body of the request to modify the message, we’re opting to build the new Slack version with the Block Kit in mind. This allows you to fully customize the message being sent for any occaison, using the graphical editor to generate JSON, which will then be used by the orb to send the message.

There are a handful of templates included in this beta test, which we plan to expand down the line - these are demonstrated in the development branch’s README.

Custom messages and block kit JSON can be passed along as a parameter - this is roughly the same as before, but we now rely more heavily on the JSON format. Here are some examples:

      - slack/notify:
            event: always
            custom: |
                "text": "Hello world"
      - slack/notify:
          template: basic_fail_1
          event: always

There are two ways of utilizing the slack/notify command - either by using a predefined template, as shown with the basic_fail_1, or by passing through a custom template with the custom field. You can easily include << parameter >> syntax or environment variables within your custom message, to tailor your messages to your use case.

You can copy and paste the result of the Block Kit Builder directly into the custom parameter.

Where can I report bugs?

Bugs can either be reported in this Discuss thread, or over in the Slack orb GitHub repository. We have a tag for tracking issues related to the beta, and we will be doing our best to include edge cases in our testing suite to ensure no regressions. We encourage you to post JSON you have passed along to the orb, along with the log of the job performing the actions.

1 Like

Couple of questions here:

  1. You’re calling this a limited beta yet when adding a new project, going to the project settings and selecting Slack Integrations I’m forced to use this new orb and I can’t find a way to use the previous iteration, how is that limited?

  2. Correct me if I’m wrong and I hope I am but by using this orb I now have to add - slack/status: to the end of every single job? How is this better than the previous iteration where all you had to do was add a webhook, its riduculous.

If this “limited beta” is going to be pushed through like the UI changes will every job need to be updated to use the orb? We have hundreds of jobs.

Hi! Our existing Slack orb behaves a bit differently from this beta/upcoming v4 version. This beta is testing the new functionality and behaviour.

Adding the job explicitly, and defining the message or data you would like sent to your Slack channel(s), gives a lot more flexibility for when and how you would like to be notified.

Due to the nature of orbs being immutable, there will be no impact when this eventually rolls out unless you opt to import the newer version of the orb.

Okay so to clarify:

  • This post is about the beta functionality you’re adding.
  • You’re still forcing the use of the slack orb going forward instead of the previous way where you simply added the webhook and notifications were sent?

These two initiatives are seperate. The Slack orb was originally created with the release of Orbs, right after the launch of CircleCI 2.0. The older Slack webhooks integration has been officially unsupported since the sunset of CircleCI 1.0, the reason being is the older Slack Webhook integration is not particularly useful on CircleCI 2.0

The older webhook integration (besides not being customizable), was based around the idea of a CircleCI 1.0 “job” which represented the entirety of what today would be a “pipeline”. Because of this, statuses such as “fixed” no longer correlate to anything on CircleCI 2.0. The official sunsetting of the defunct webhook service comes with the new UI changes.

The change described here is a rewrite of our existing slack orb which aims to offer similar functionality with more customization and control.

Our ultimate goal (and currently in the works), will be fully fledged bots for Slack, Microsoft Teams, Ect. The update to the Slack Orb we are proposing now is an interim solution to the existing orb product while we continue to work towords bots.


Hey guys it’s great the orb is being updated with new functionality.
I appreciate it’s in beta. Before it gets the 4.0 can you document appropriate variables please.
Eg I’m not sure if I should be using SLACK_WEBHOOK or SLACK_ACCESS_TOKEN perhaps src/examples/full_deployment_sample.yml and / can get the full list


Hey Tim,

We had a last moment large change and extended the beta. You can see the wiki for the beta now here:

Hi @KyleTryon
Thank you.
As a setup page that looks good. It’s nice and easy to follow.

Please don’t take any of the following as nit picking as I’m genuinely excited to use the new functionality and would like this orb to be an example to to those I work with on standards they should be looking to achieve.

Do we get a usage page as well?

I think the examples are still a little incomplete. Specifically surrounding the channel. If I want to post something to a channel that is not the default, would I use the env var SLACK_DEFAULT_CHANNEL or a different env var (yes I know looking at commands/notify.yml I can see I pass in the param. I hope that people aren’t needing to dig through the orb to get detail on how to use it.
I also think that on hold notification example is no longer valid as I think it’s referencing commands/on-hold

1 Like

Hey Tim,
Absolutely, and we honestly appreciate the feedback. This is our most used orb, so anything is highly useful. Those usage examples are admittedly from before we switched to the OAUTH a few days ago, which we probably should have taken care of in another branch since we had already launched the beta. That’s honestly my bad there.

We just today launched our new Orb Development Kit (which we secretly used for this Slack Orb), which has stolen a bit of our focus but we will have this completely cleared by end of next week.

The Slack Orb is now due to be updated Oct 12th.

We’ll have those usage examples updated very shortly and will update here.

for the time being,
there is now no longer a “webhook”, just the Oauth (which isnt a parameter) and a new parameter for channel.

By default, channel will be set to $SLACK_DEFAULT_CHANNEL, but you can enter a comma separated list of channel IDs instead if you wish.

You can get a channel ID by copying a link to a channel in slack, and inspecting the link.


I think the FAQ needs a little more detail around the channel param. I think most people who are not familiar with the orb will assume the channel refers to the friendly name eg #general rather than ABCDEF.
I know to some extent it’s documenting someone else’s product (slack) but can the FAQ’s have a

  • “How do I find the channel value” eg Q:“My messages are being sent, but not arriving?” A: "Are you using #general rather than ABCZXY, you can find the channel by …

From within the desktop app if I right clicked the channel name there is a “Copy link” option. The channel is the string after the final slash

1 Like

You got it :+1: Adding now

1 Like

Slack Orb V4.0.0 is LIVE!