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

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

Jared Harbison, a solo engineer, built a GitHub Actions workflow that sends Slack messages on every deploy, including commit logs and links to new documentation. The system ensures non-technical stakeholders receive clear, actionable updates without technical jargon.

Why This Matters

The ideal of seamless deployment communication assumes all stakeholders understand CI/CD pipelines, but in reality, non-technical teams often lack context about what changes were made and why. Misaligned expectations can lead to delays or errors in post-deploy tasks. For example, a missing documentation link might cause a site admin to overlook critical testing steps, risking production issues.

Key Insights

• “YAML for note tracking: Simplifies doc management but risks re-sending if commits fail” (from author’s self-evaluation)
• “SOPs via AI: Balances solo eng workload with review process” (author’s approach to drafting documentation)
• “Slack notifications with commit logs: Bridges technical/non-technical gaps” (core system behavior)

Working Example

# GitHub Actions workflow trigger
on:
  push:
    branches:
      - main
      - staging

# Example deploy note tracking file
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

# Shell script to add deploy notes
./scripts/add-deploy-note.sh

# Slack message construction in workflow
if [[ "$ENVIRONMENT" == "production" ]]; then
  EMOJI="✅"
else
  EMOJI="💯"
fi
MESSAGE_TEXT="$EMOJI *Deployment to $ENVIRONMENT succeeded!*"
# ... send via curl to Slack webhook

Practical Applications

• Use Case: Solo engineers managing non-technical stakeholders with deploy updates
• Pitfall: Over-reliance on Google Docs for documentation may create versioning and searchability issues

References:

• https://dev.to/jaredharbison/am-i-doing-this-right-1-deploy-notifications-that-actually-get-read-1ink