Integrating MsgGO into Bitbucket Pipelines: Step by Step

Ditch the Notification Noise: Streamlining Bitbucket Pipelines with MsgGO

Ever missed that critical deployment notification because it got lost in email? Or maybe spent valuable time digging through Bitbucket logs to figure out why a build failed? It happens to the best of us. Let's fix that. With MsgGO, you can set up detailed, useful pipeline notifications delivered straight into Slack, keeping you and your team instantly informed.

Here's the kind of helpful notification we're aiming for:

Clear status, repo details, branch, and even crucial error logs are right there, giving you the vital info at a glance.

Speaking of those logs, here's a little insight from our own experience: we use MsgGO at MsgGO for our deployments. One common step is running database migrations, but the detailed logs from those don't always surface easily in the standard Bitbucket pipeline output. Before using MsgGO for this, I often had to SSH onto the server just to check if migrations completed successfully – a real hassle. Now? We simply pipe those specific logs directly into our Slack notification via MsgGO. One look, and I know if things went smoothly or if there was an issue, without leaving Slack. Getting the right information, right where you need it, especially when things don't go as planned – that's the kind of efficiency boost we all appreciate.

Ready to build notifications like this without excessive effort? Let's dive in.

Why Are Traditional Notifications Often a Pain?

Let's be honest, setting up CI/CD notifications can be frustrating. Common challenges include:

• Needing complex integrations or yet another third-party tool.
• Having to edit pipeline scripts every time notification requirements change.
• Struggling to get the right info to the right people (or channels) under the right conditions.
• And the most common scenario? Often, no notifications get set up at all because dealing with the complexity just isn't worth the time.

MsgGO was designed to address these frustrations. It allows you to:

• Send notifications reliably with a straightforward HTTP request using tools like curl.
• Let team members manage their notification preferences without requiring changes to your pipeline code.
• Easily add new notification methods – Slack, email, SMS, webhooks – as your needs evolve.

Hooking Up MsgGO & Bitbucket Pipelines: The Setup

Getting started is refreshingly straightforward.

Step 1: Create Your MsgGO Account

Visit msggo.io/signup. The free account provides enough credits to test the integration thoroughly.

Step 2: Generate Your API Key

You need an API key for secure communication between Bitbucket and MsgGO.

• Log into your MsgGO dashboard.
• Navigate to the "API Keys" section in the sidebar.
• Click "New Key". Give it a descriptive name you'll recognize, like Bitbucket Pipeline Notifications.
• Important: Copy this API key and store it securely for the next step. Treat it with care.

Step 3: Add the API Key to Bitbucket (Securely!)

Avoid hardcoding API keys in scripts. Use Bitbucket's secured repository variables.

• In your Bitbucket repo, go to Repository settings ➡️ Pipelines ➡️ Repository variables.
• Click "Add variable". Name it MSGGO_KEY.
• Paste your MsgGO API key into the value field.
• Crucially, ensure the "Secured" checkbox is checked. This prevents the key from being exposed in logs.

Step 4: Teaching MsgGO About Your Pipeline Events

Here's how MsgGO processes incoming data. Every HTTP request sent to MsgGO's endpoint (https://msggo.io/inbox) arrives in your organization's general "Inbox".

To make sense of this raw data, you create an Event Definition. This acts as a filter, telling MsgGO, "When a message arrives matching these specific criteria (like having a certain event_name), recognize it as a 'Bitbucket Pipeline Notification' event."

Here's how to set it up:

1. Go to Events: In your MsgGO dashboard, click "Events" in the sidebar, then "Add Event".
2. Define the Event:
   • Name: Use something clear, like Bitbucket Pipeline Notification.
   • Group (Optional): Consider a Bitbucket or DevOps group for organization.
   • Description (Optional): Add context about the event.
3. Set Matching Rules: This tells MsgGO how to identify this event type.
   • Default Behavior: MsgGO often defaults to looking for an event_name key matching your definition name (e.g., event_name=bitbucket-pipeline-notification).
   • Custom Rules: You can define rules based on other data if needed, but matching on event_name is usually sufficient for this purpose.
4. Save it: Click "Create".

You've now defined the type of event. Next, let's connect Slack so MsgGO has a destination for messages related to this event.

Step 5: Connecting Slack – Enabling Communication

Before selecting a Slack channel, authorize MsgGO to post to your workspace.

1. Find Integrations: Click "Integrations" in the MsgGO sidebar.
2. Locate Slack: Find "Slack" in the available integrations.
3. Click "Add".
4. Grant Permission in Slack: You'll be redirected to Slack. Review the requested permissions and click "Allow".

You'll return to MsgGO, confirming Slack is connected.

Step 6: Telling MsgGO Where & How to Notify (The Delivery Definition)

With Slack connected and the Event Definition created, let's configure the actual notification. This is the Delivery Definition.

• Find Your Event: Go back to the "Events" list and locate Bitbucket Pipeline Notification.
• Add Delivery: Click the "Add delivery" button for this event.
• Select Target: Choose Slack as the delivery method.
• Configure Channel: Select your Slack Workspace and the target Channel. (Ensure you've invited the @MsgGO bot to that channel in Slack using /invite @MsgGO).

At this point, a field should appear allowing you to select an existing message template or create a new one. Choose "New message template" and enter the following template:

🚀 *Bitbucket Pipeline Notification*
--------------------------------------------------------------------------------------


{{ data.status == 'success' ? '✅' : data.status == 'error' ? '❌' : '⏳' }} {{ data.message }}


--------------------------------------------------------------------------------------
📂 Repository: `{{ data.repository }}` 🌳 Branch: `{{ data.branch }}`


{% if data.logs %}
📝 *Logs:*
```
{{ data.logs }}
```
{% endif %}

Now you can click “Save”.

Now, any event matching the Bitbucket Pipeline Notification definition will trigger this styled message in your specified Slack channel.

The Bitbucket Pipeline bitbucket-pipelines.yml

And that's it—we're nearly finished. There's just one final step left: sending an event (request) to MsgGO so it can react and send a message to Slack.

Here's the pipeline configuration, showing the curl command within the after-script to send the final status update.

pipelines:
  branches:
    master:
      - step:
          name: "Deploy to production"
          deployment: Development
          script:
            # Your real deployment steps go here...
            # Optionally send 'in-progress' updates from here using curl as needed

            # Example: Capture relevant logs towards the end
            - bash examples/fake-build.sh | tail -c 30000 > /tmp/build.log
          after-script:
            # Determine the final outcome
            - BUILD_STATUS=$([ $BITBUCKET_EXIT_CODE -eq 0 ] && echo "success" || echo "error")
            # Send the final notification for this step
            - >
              curl -X POST "" \
                -d "msggo-key=$MSGGO_KEY" \
                -d "event_name=bitbucket-pipeline-notification" \
                -d "repository=$BITBUCKET_REPO_SLUG" \
                -d "branch=$BITBUCKET_BRANCH" \
                -d "status=$BUILD_STATUS" \
                -d "done=yes" \
                -d "message=Deployment process finished with status: $BUILD_STATUS" \
                --data-urlencode "logs@/tmp/build.log"

Quick Notes

• The line bash examples/fake-build.sh | tail -c 30000 > /tmp/build.log is just an example process whose logs we want to capture and send to MsgGO. In a real pipeline, this would be replaced with your actual build, test, or deployment commands. The important part is piping the output into a log file that can then be sent with our notification.
• Why tail? MsgGO has a payload limit (~50k characters), and so does Slack. Sending massive logs often isn't practical or necessary. tail -c 30000 provides the last chunk of the log, which is frequently the most useful part for diagnosing issues. Adjust the size based on your needs.

Testing and Troubleshooting Your Pipeline Notifications

Now you can run your pipeline and test receiving notifications on Slack. After setting everything up, trigger a pipeline run and wait for the notification to appear in your Slack channel.

Debugging Missing Notifications

If your Slack notification doesn't arrive as expected, here's how to troubleshoot:

1. Check the MsgGO Inbox:
   • Log into MsgGO and click "Inbox" in the left sidebar
   • The Inbox presents a table with three columns: "Event name", "Data", and "Received at"
   • "Event name" shows matched event definitions, "Data" displays a preview of the received JSON, and "Received at" shows the timestamp
2. Verify Event Reception:
   • If your event doesn't appear in the Inbox at all, your API key might be incorrect or the curl request failed
   • Check your Bitbucket pipeline logs for any curl errors
3. Check Event Matching:
   • If your event appears in the Inbox but shows "Unrecognized" in the "Event name" column, it means no event definition matched the incoming data
   • Verify that your event_name in the curl request exactly matches what you set up in your event definition
4. Examine Delivery Details:
   • Click the arrow at the beginning of each row to expand it
   • Under "Delivered to", you'll see a list of delivery attempts and their status
   • Under "Event data", you'll see the complete data that was received
5. Inspect Delivery Errors:
   • If there was a problem delivering to Slack, the expanded "Delivered to" section will show specific error messages
   • Common issues include not inviting the MsgGO bot to your Slack channel or integration permission problems

By working through these steps, you can identify exactly where the notification process is breaking down and fix the specific issue.

Handling Updates During Long Pipelines

Our example focuses on sending one final notification via after-script. However, this MsgGO setup is perfectly capable of handling status updates during lengthy pipelines.

For pipelines with multiple long-running stages, you can send intermediate events from various points in your script:

• Send an event with status=in-progress and message="Running database migrations...", setting done=no.
• Later, send another like status=in-progress, message="Deploying frontend...", done=no.
• The final event (typically from after-script) signals completion by setting the final status and crucially, done=yes.

Our Slack template is designed to show the appropriate status icon (⏳, ✅, ❌) and message for each update, providing valuable real-time feedback.

Bonus Round: Email Summary Upon Process Completion

Let's say team leaders in your company want to be informed about new deployments via email. They're not interested in every step of the pipeline process—they just want to know the final result. We can easily achieve this by defining a new event that only matches inbox events with both event_name=bitbucket-pipeline-notification AND done=yes. Yes, it's that simple.

Below I'll show you how to set up email delivery, but here's the thing—if your CTO wants to receive SMS notifications about these events instead, they can set that up with just a few clicks by adding another delivery method to an existing event definition. That's the beauty of MsgGO. Every member of your organization can decide what they want to be notified about and where they want those notifications delivered.

Create a Second Event Definition:

• Name: Pipeline Completed.
• Matching Rule: Configure it to match two values from inbox event:
  • when event_name key equals bitbucket-pipeline-notification and
  • when done key equals yes
• Save.

This event definition will only send notifications when "done" equals "yes"—which is exactly what we want. We want to send a summary email only when the pipeline has completed its work.

Add Email Delivery to This New Event:

• Find the Pipeline Completed event definition.
• Add a new delivery definition to it.
• Target: Email.
• Recipient: Select the appropriate verified team member.

Message Template:

Pipeline Process Completed for {{ data.repository }}

The pipeline process for repository '{{ data.repository }}' on branch '{{ data.branch }}' has finished with final status: {{ data.status }}.

Result: When your pipeline sends its concluding event with done=yes:

• MsgGO matches it to the first definition (Bitbucket Pipeline Notification) ➡️ Sends the detailed Slack alert.
• MsgGO also matches it to the second definition (Pipeline Completed) ➡️ Sends the summary email.

Intermediate updates (done=no) would only trigger the first definition (Slack alert). This provides layered notifications based on process completion.

Conclusion: Go Forth and Notify!

Integrating MsgGO with Bitbucket Pipelines offers a flexible and efficient way to manage notifications, solving common frustrations. You now have a pipeline that not only notifies your team through Slack but gives them the critical information they need to quickly understand what's happening.

This is just the beginning of what you can do with MsgGO notifications. For example, you could send a summary email to team leaders about each deployment, or perhaps your CTO wants to receive SMS notifications for every production deployment. With the event definition framework we've set up, adding these additional notification methods doesn't require changing your pipeline code at all - just configure new delivery targets in MsgGO. The sky's the limit!

Ready to try it yourself? The free plan is a great starting point:

👉 Get started with MsgGO

For more details, check the MsgGO Documentation, or reach out to support if you have questions.

Happy deploying, and enjoy the clarity your new notification system brings! 🎉