DEV Community

Cover image for Am I Doing This Right? #1: Deploy Notifications That Actually Get Read
JaredHarbison
JaredHarbison

Posted on

Am I Doing This Right? #1: Deploy Notifications That Actually Get Read

#github #cicd #devops #productivity

I'm the only engineer at my company. That means when I deploy, there's no one watching the CI pipeline with me—my teammates are non-technical stakeholders who care about what shipped and what they need to do about it, not the mechanics of how it got there.

So I built a system that meets them where they are: a Slack message on every deploy that includes recent commits and links to any new documentation.

Here's what it looks like:

💯 Deployment to staging succeeded!

📚 New Documentation:
• Testing: New Feature Name

Recent commits:
• feat: add user onboarding flow
• fix: resolve null check in profile loader
• chore: update dependencies
Enter fullscreen mode Exit fullscreen mode

And here's how it works.

The trigger

The GitHub Action fires on any push to main or staging. Staging deploys include commit messages; production deploys are cleaner since by that point everyone's already seen what's coming.

on:
  push:
    branches:
      - main
      - staging
Enter fullscreen mode Exit fullscreen mode

This assumes you've added your Heroku API key and Slack webhook URL as repository secrets in GitHub.

The documentation layer

This was the part I thought hardest about. I write SOPs (Standard Operating Procedures) for site admins—things like how to report issues, how to test a new feature, how to run monthly reports. I use AI to draft these and review before publishing, which makes it realistic to keep docs current even as a solo eng. The docs live in Google Docs because that's what my team already knows. No learning curve, no new logins, free.

I needed a way to attach new docs to the next deploy notification without manually editing the workflow every time. So I created a simple YAML file that tracks documents and whether they've been sent:

notes:
  - type: "sop"
    title: "Admin Issue Reporting Guide"
    url: "https://docs.google.com/document/d/your-doc-id"
    added: "2025-11-21T23:15:58Z"
    sent: false
Enter fullscreen mode Exit fullscreen mode

And a shell script to add new notes without touching the YAML directly:

./scripts/add-deploy-note.sh
Enter fullscreen mode Exit fullscreen mode

It prompts for the doc type (SOP or technical), title, and URL, validates that it's a Google Docs link, and appends it to the file with sent: false.

The deploy workflow

The workflow does a few things:

  1. Sets environment variables based on the branch (staging vs. production, different Heroku apps)
  2. Pulls commit messages since the last deploy using git log
  3. Checks the notes file for any unsent documentation
  4. Pushes to Heroku
  5. Builds and sends the Slack message
  6. Marks notes as sent and commits that change back to the repo

The Slack message construction looks like this:

- name: Build and send Slack notification
  if: success()
  run: |
    if [[ "$ENVIRONMENT" == "production" ]]; then
      EMOJI="✅"
    else
      EMOJI="💯"
    fi

    MESSAGE_TEXT="$EMOJI *Deployment to $ENVIRONMENT succeeded!*"

    if [[ "$HAS_NOTES" == "true" && -n "$NOTES_SECTION" ]]; then
      MESSAGE_TEXT="${MESSAGE_TEXT}"$'\n\n'"${NOTES_SECTION}"
    fi

    MESSAGE_TEXT="${MESSAGE_TEXT}"$'\n\n'"${SAFE_COMMITS}"

    # ... send via curl to Slack webhook
Enter fullscreen mode Exit fullscreen mode

After a successful deploy, the workflow marks all notes as sent: true and commits the change with [skip ci] to avoid triggering another run.

Decisions I made (and am not sure about)

Google Docs over a proper docs site: I went with Google Docs because my stakeholders already live there. But it means documentation isn't versioned with the code, search is scattered, and I'm trusting Google's link permanence. Would love to hear from anyone who's migrated a non-technical team to something like Notion or a static docs site.

YAML for note tracking: This felt simpler than a database or external service, and it lives in the repo so it's versioned. But the "mark as sent and commit back" step feels slightly fragile. If the commit fails for some reason, notes could get re-sent. Is there a cleaner pattern here?

Shell script for adding notes: I like that it validates URLs and keeps the YAML format consistent. But it's another thing to remember. Would a GitHub Issue template or something more visual be better for a mixed-technical team?

Using AI for documentation: I draft SOPs with AI and review before publishing. It's the only way I can keep docs current as a solo eng. But I'm curious how others feel about this—any concerns about quality, consistency, or maintainability?

The full workflow

Full source available here: deploy.yml and add-deploy-note.sh

That's the setup. Am I overcomplicating this? Undercomplicating it? Missing something obvious? Let me know how your team handles deploy communication—especially if you're bridging technical and non-technical audiences.

Top comments (0)