Triggering CircleCI Builds from a Custom Slack Command

Hey everyone, Darian Vance here. I want to walk you through a workflow that personally saved me a few hours every week. At TechResolve, we have a specific CircleCI job for refreshing our staging environment’s data. It’s not on a schedule; we run it on-demand. For a while, triggering it meant opening CircleCI, finding the project, finding the right branch, and hitting ‘Run Pipeline’. It was a minor, but constant, interruption that broke my focus.

By creating a simple /rebuild-staging Slack command, our entire team can now trigger this job without ever leaving the channel where we coordinate our work. It’s a small change that delivered a massive quality-of-life improvement. Let’s build it together.

Prerequisites

Before we dive in, make sure you have the following ready:

• A Slack workspace where you have permissions to create and install applications.
• A CircleCI account with a project already configured.
• A CircleCI Personal API Token. You can generate one in your User Settings > API Tokens.
• A publicly accessible server to host our small application. For local development, a tool like ngrok is perfect for this.
• A working Python environment. We’ll be using Flask for our web server.

The Step-by-Step Guide

Alright, let’s get to the fun part. We’re going to create a Slack app, build a small Python server to listen for the command, and then use that server to call the CircleCI API.

Step 1: Create the Slack App and Slash Command

First, we need to tell Slack about our new command.

1. Navigate to the Slack API dashboard and click “Create New App”. Choose to create it “From scratch”.
2. Give it a name like “CircleCI Trigger” and pick your workspace.
3. In the sidebar, go to “Slash Commands” and click “Create New Command”.
4. Fill out the form:
   • Command: /rebuild-staging
   • Request URL: We need a URL for our server. For now, you can put a placeholder like https://temp-url.com/slack/events. We will update this later with our real server or ngrok URL.
   • Short Description: “Triggers a new build for the staging environment.”
5. Click “Save”. Now, go to “Install App” in the sidebar and install the app to your workspace.
6. Finally, navigate to “Basic Information” and find your “Signing Secret” under “App Credentials”. Also, go to “OAuth & Permissions” and copy your “Bot User OAuth Token”. Keep these two values safe; we’ll need them for our server.

Step 2: Set Up the Python Server with Flask

Now, let’s write the code that will receive the request from Slack. I’ll skip the standard virtualenv setup since you likely have your own workflow for that. Just make sure you install the necessary packages. In your terminal, you’d run something like pip install flask requests python-dotenv to get the libraries we need.

Create a project folder and add two files: app.py and a config.env for our secrets.

Your config.env file should hold your secrets. Never commit this file to version control!

# config.env
SLACK_SIGNING_SECRET="your_slack_signing_secret_here"
CIRCLECI_API_TOKEN="your_circleci_token_here"

Next, here is the basic structure for our Flask app in app.py. This sets up the web server and an endpoint to listen for Slack’s POST requests.

# app.py
import os
import hmac
import hashlib
import time
from flask import Flask, request, jsonify
from dotenv import load_dotenv
import requests

load_dotenv('config.env')

app = Flask(__name__)

SLACK_SIGNING_SECRET = os.environ.get('SLACK_SIGNING_SECRET')
CIRCLECI_API_TOKEN = os.environ.get('CIRCLECI_API_TOKEN')

@app.route('/slack/events', methods=['POST'])
def slack_command():
    # We will add our logic here
    return jsonify(
        response_type='in_channel',
        text='Command received, but logic is not implemented yet.'
    )

if __name__ == '__main__':
    app.run(port=3000)

Step 3: Verify the Slack Request (The Security Check)

This is the most critical part, and one I see people skip. We MUST verify that the request is actually coming from Slack. We do this using the Signing Secret we saved earlier.

Let’s update our slack_command function in app.py to include this verification logic.

@app.route('/slack/events', methods=['POST'])
def slack_command():
    # Get the request data
    request_body = request.get_data().decode('utf-8')
    timestamp = request.headers.get('X-Slack-Request-Timestamp')
    slack_signature = request.headers.get('X-Slack-Signature')

    # Avoid replay attacks
    if abs(time.time() - int(timestamp)) > 60 * 5:
        return ('Request timestamp expired.', 403)

    # Construct the signature base string
    sig_basestring = f'v0:{timestamp}:{request_body}'

    # Hash the base string with the signing secret
    my_signature = 'v0=' + hmac.new(
        bytes(SLACK_SIGNING_SECRET, 'utf-8'),
        bytes(sig_basestring, 'utf-8'),
        hashlib.sha256
    ).hexdigest()

    # Compare signatures
    if not hmac.compare_digest(my_signature, slack_signature):
        return ('Signature verification failed.', 403)

    # If verification passes, we can proceed
    # For now, let's just acknowledge it.
    return jsonify(
        response_type='ephemeral',
        text='Got it! Kicking off the staging build now...'
    )

Pro Tip: At this point, I highly recommend running your Flask app and using ngrok to expose it (e.g., ngrok http 3000). Take the ngrok URL it gives you, append /slack/events to it, and update the “Request URL” in your Slack App’s command settings. Then, try running /rebuild-staging in Slack. If you get the “Got it!” message, your verification logic is working perfectly.

Step 4: Trigger the CircleCI Pipeline

Now that we can securely receive the command, let’s actually trigger the build. We’ll use the CircleCI API v2. You’ll need your project slug, which follows the format vcs/org/repo (e.g., gh/TechResolve/web-app).

Let’s add a function to handle this and call it from our main route.

def trigger_circleci_build():
    project_slug = 'gh/YourOrganization/YourRepo' # <-- IMPORTANT: Change this!
    branch_name = 'main' # Or whatever branch you want to build

    url = f'https://circleci.com/api/v2/project/{project_slug}/pipeline'
    
    headers = {
        'Content-Type': 'application/json',
        'Circle-Token': CIRCLECI_API_TOKEN,
    }

    payload = {
        'branch': branch_name
    }

    try:
        response = requests.post(url, json=payload, headers=headers)
        response.raise_for_status() # Raises an exception for 4xx/5xx errors
        return True, response.json()
    except requests.exceptions.RequestException as e:
        print(f'Error triggering CircleCI build: {e}')
        return False, str(e)

# We update our slack_command function to call this:
@app.route('/slack/events', methods=['POST'])
def slack_command():
    # ... (all the verification logic from before) ...
    if not hmac.compare_digest(my_signature, slack_signature):
        return ('Signature verification failed.', 403)

    # Trigger the build in a separate thread if it's slow,
    # but for this example, we'll do it directly.
    success, data = trigger_circleci_build()

    if success:
        pipeline_number = data.get('number')
        message = f'Successfully triggered build #{pipeline_number} for the staging environment.'
    else:
        message = f'Failed to trigger build. Error: {data}'
    
    # We will use the response_url to send a delayed message.
    # For now, we'll just send a simple immediate response.
    # Slack gives you 3 seconds, so this needs to be fast.
    return jsonify(
        response_type='in_channel', # 'in_channel' is visible to everyone
        text=message
    )

Pro Tip: Slack expects a response within 3 seconds. An API call can sometimes take longer. In my production setups, I immediately return a “Working on it…” message. Then I use the response_url that Slack sends in the initial payload to post a follow-up message with the result of the CircleCI API call. This makes the bot feel much more responsive and reliable.

Common Pitfalls

Here are a few places where I usually mess up when building these integrations:

• Signature Verification Fails: This is often because I’m using the wrong secret or the request body is being modified before I read it. Always use the raw request body for the signature check.
• CircleCI ‘Project Not Found’: Nine times out of ten, this is a typo in the project slug. Double-check that it’s exactly vcs-provider/organization-name/repository-name. For GitHub, it’s gh/org/repo.
• Slack Command Timeout: As mentioned in the pro tip, if your logic takes more than 3 seconds, Slack will show an error to the user. Always acknowledge the command immediately and handle long-running tasks asynchronously.

Conclusion

And there you have it! A straightforward but incredibly powerful way to bring your CI/CD pipeline directly into your team’s main communication hub. This kind of “ChatOps” workflow is a fantastic way to reduce context switching and empower your entire team to manage infrastructure tasks safely.

From here, you can expand this concept significantly. You could parse text from the command to specify a branch (e.g., /rebuild-staging feature/new-login), add more commands for different jobs, or even build interactive Slack modals for more complex options. Happy automating!

Darian Vance

Lead Cloud Architect & DevOps Strategist

With over 12 years in system architecture and automation, Darian specializes in simplifying complex cloud infrastructures. An advocate for open-source solutions, he founded TechResolve to provide engineers with actionable, battle-tested troubleshooting guides and robust software alternatives.

🤖 Frequently Asked Questions