Notify Developers of Broken Builds via Desktop Notification

Hey team, Darian here. Let’s talk about a small tweak that gave me back a surprising amount of focus time. I used to be a chronic build-checker. I’d either have a Jenkins tab permanently open or I’d be compulsively checking my email for CI/CD failure alerts. Each check was a context switch, pulling me out of deep work. I realized I was probably wasting an hour or two a week just *monitoring*. This guide will show you how to build a simple, local script that pushes a desktop notification directly to you the moment a build breaks. It’s a classic “set it and forget it” solution that lets the important information come to you.

Prerequisites

Before we start, make sure you have the following ready:

• Python 3 installed on your machine.
• A way to access your build logs. For this tutorial, we’ll simulate this with a local text file, but you could adapt this to pull from a CI/CD API endpoint.
• The ability to install a couple of Python packages.

The Guide: Step-by-Step

Step 1: Setting Up Your Project

First, find a good spot on your machine for this project. You’ll want to create a directory for it. I’ll skip the standard virtualenv setup commands since you likely have your own preferred workflow for that. Just make sure you’re working in an isolated environment.

You’ll need two Python libraries. In your terminal, you’ll want to install plyer for handling the cross-platform notifications and python-dotenv for managing our configuration. The commands would be something like pip install plyer python-dotenv.

Your project structure will be very simple:

• build_checker.py – Our main Python script.
• config.env – A file to store our configuration variables.
• build_log.txt – A mock log file to simulate our CI/CD output.

Step 2: Configuring Your Environment

Let’s create the config.env file. In my production setups, I always use environment files to keep sensitive data or configuration details out of the main codebase. It makes the script more portable and secure.

Create a file named config.env and add the following:

# Path to the log file we are monitoring
LOG_FILE_PATH="build_log.txt"

# The specific string that indicates a build failure
FAILURE_KEYWORD="BUILD FAILED"

Step 3: The Python Script

Now for the core logic. Create the build_checker.py file and let’s build it out. We’ll read the log file, check for our keyword, and trigger a notification if we find it.

import os
from plyer import notification
from dotenv import load_dotenv

def check_last_build_status(log_file, keyword):
    """Checks the last line of a log file for a specific keyword."""
    try:
        with open(log_file, 'r') as f:
            lines = f.readlines()
            if not lines:
                return False  # Log file is empty
            last_line = lines[-1].strip()
            if keyword in last_line:
                return True
    except FileNotFoundError:
        print(f"Error: Log file not found at {log_file}")
        return False
    except Exception as e:
        print(f"An unexpected error occurred: {e}")
        return False
    return False

def send_notification(title, message):
    """Sends a desktop notification."""
    try:
        notification.notify(
            title=title,
            message=message,
            app_name='Build Monitor',
            timeout=10  # Notification will disappear after 10 seconds
        )
        print("Notification sent successfully.")
    except Exception as e:
        print(f"Failed to send notification: {e}")

if __name__ == "__main__":
    load_dotenv('config.env')

    log_path = os.getenv("LOG_FILE_PATH")
    fail_keyword = os.getenv("FAILURE_KEYWORD")

    if not log_path or not fail_keyword:
        print("Error: Configuration variables not found. Check your config.env file.")
    else:
        print(f"Monitoring log file: {log_path}")
        if check_last_build_status(log_path, fail_keyword):
            send_notification(
                title="Build Failure Detected!",
                message=f"The latest build failed. Please check the logs."
            )
        else:
            print("Build status OK. No failure detected.")

Here’s the breakdown of the logic: We load our configuration from config.env. The check_last_build_status function opens our log file, reads the very last line, and checks if our FAILURE_KEYWORD is present. If it is, the main block calls send_notification, which uses the plyer library to pop up that handy desktop alert.

Pro Tip: This script checks the *last line*. A more robust solution might track the last-checked line number in a separate state file (e.g., .last_checked_line) so it doesn’t re-notify you for the same old failure every time it runs. This prevents notification spam.

Step 4: Simulating a Broken Build

To test it, let’s create our build_log.txt file. First, add some successful build messages:

INFO: Starting build #123...
INFO: Tests passed.
INFO: Build #123 successful.

Now, run the script from your terminal: python3 build_checker.py. It should print “Build status OK.”

Next, append a failure line to build_log.txt:

INFO: Starting build #124...
ERROR: Compilation error in module 'core'.
CRITICAL: BUILD FAILED.

Run the script again. This time, you should see a desktop notification pop up!

Step 5: Automation (The “Set It and Forget It” Part)

Running this manually is neat, but the real power comes from automation. You want this script to run periodically in the background.

On macOS or Linux, a cron job is perfect for this. You could set it to run every 5 minutes during work hours. The cron entry would look something like this, but remember to navigate to your project directory first.

*/5 * * * * cd /path/to/your/project && python3 build_checker.py

On Windows, you can achieve the same thing using the Task Scheduler. You’d create a new task that triggers the script on a schedule of your choosing.

Pro Tip: Don’t set the interval too low! Checking every 5 minutes is reasonable. Checking every 5 seconds is excessive and might cause performance issues or API rate-limiting if you adapt this to hit a server.

Common Pitfalls (Where I Usually Mess Up)

• Permission Errors: The first time I set this up, the script couldn’t read the log file because it was owned by a different user (the CI server’s user). Make sure your script has read permissions for the target log file.
• Incorrect Paths in Cron: A script that runs perfectly from your terminal might fail in a cron job. This is usually because cron jobs run with a minimal environment. Always use full paths to your script and log files, or use the cd trick like I showed above to ensure the script runs from the correct directory.
• Keyword Mismatch: I once spent 20 minutes debugging why I wasn’t getting alerts, only to realize my build server was logging “Build Failed” and my script was looking for “BUILD FAILED”. Case-sensitivity matters! Double-check your keyword.

Conclusion

And that’s it. This is a simple but incredibly effective piece of personal automation. It reduces the mental load of monitoring and lets you stay focused on what you’re actually paid to do: write great code. By bringing critical failure information directly to your desktop, you can react faster without being glued to a dashboard. Feel free to expand on this—you could make it parse the log for specific error codes or even add buttons to the notification that link directly to the failed build. Happy coding.

---

🤖 Frequently Asked Questions