DEV Community: Aaron Ross

Free DevOps Notifications with Discord and GitHub Actions

Aaron Ross — Tue, 10 Feb 2026 04:26:25 +0000

I run a few open source projects, and I don't have a team. It's just me, which means there's nobody else to notice when the 6am cron job fails. I'm certainly not going to sit there refreshing the GitHub Actions page to find out.

Slack would work for this, but paying for Slack so that one person can send notifications to themselves feels a little sad when you think about it. Discord servers are free, GitHub Actions are free for public repos, and Discord webhooks are just HTTP endpoints that accept JSON. You probably see where this is going.

The Pitch

I now get push notifications on my phone when my scheduled jobs fail, and I didn't pay anyone for the privilege. The whole setup took an evening, and most of that was figuring out how I wanted to format the messages.

Getting a Webhook URL

Right-click a channel in Discord, go to Edit Channel, then Integrations, then Webhooks. Create one, copy the URL, and add it as a secret in your GitHub repo (I called mine DISCORD_WEBHOOK_URL).

That's genuinely it. No OAuth dance, no bot tokens, no registering an application with Discord's developer portal. Just a URL that accepts POST requests with JSON bodies. If you've ever set up a Slack app you're probably crying right now, and honestly, it's okay. Let it out.

The Script

After a few iterations of inline bash in my workflow files (which worked but was getting repetitive), I pulled everything into a reusable script. Here's what it looks like:

#!/usr/bin/env bash
set -euo pipefail

TITLE=""
COLOR=""
DESCRIPTION=""
BUTTONS=()

while [[ $# -gt 0 ]]; do
  case $1 in
    --title) TITLE="$2"; shift 2 ;;
    --color) COLOR="$2"; shift 2 ;;
    --description) DESCRIPTION="$2"; shift 2 ;;
    --button) BUTTONS+=("$2"); shift 2 ;;
    *) echo "Unknown arg: $1" >&2; exit 1 ;;
  esac
done

if [ -z "${DISCORD_WEBHOOK:-}" ]; then
  echo "DISCORD_WEBHOOK not set, skipping notification"
  exit 0
fi

TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
WEBHOOK_URL="$DISCORD_WEBHOOK"

# Convert buttons to Discord component format
BUTTONS_JSON="[]"
if [ ${#BUTTONS[@]} -gt 0 ]; then
  BUTTONS_JSON=$(printf '%s\n' "${BUTTONS[@]}" | \
    jq -R 'split("|") | {type: 2, style: 5, label: .[0], url: (.[1:] | join("|"))}' | \
    jq -s '.')
  WEBHOOK_URL="${WEBHOOK_URL}?with_components=true"
fi

PAYLOAD=$(jq -n \
  --arg title "$TITLE" \
  --argjson color "$COLOR" \
  --arg description "$DESCRIPTION" \
  --arg timestamp "$TIMESTAMP" \
  --argjson buttons "$BUTTONS_JSON" \
  '{
    username: "DD Notification Bot",
    avatar_url: "https://democracy-direct.com/logo-square.png",
    embeds: [{
      title: $title,
      color: $color,
      description: $description,
      footer: { text: "Democracy Direct CI" },
      timestamp: $timestamp
    }]
  } + if ($buttons | length) > 0 then {
    components: [{ type: 1, components: $buttons }]
  } else {} end')

curl -fsS -H "Content-Type: application/json" -d "$PAYLOAD" "$WEBHOOK_URL"

Save that to .github/scripts/discord-notify.sh, make it executable, and now you can call it from any workflow with a simple interface:

.github/scripts/discord-notify.sh \
  --title "🚨 Something Broke" \
  --color 15158332 \
  --description "The thing that was supposed to work did not work." \
  --button "View Run|https://github.com/..." \
  --button "Production|https://your-site.com"

The --button format is just "Label|URL". You can have multiple buttons and they'll show up as actual clickable Discord buttons, not just markdown links. The script also gracefully skips sending if the webhook secret isn't set, which is nice for forks or local testing.

What I Actually Use It For

Democracy Direct has scheduled jobs that sync data from the Congress API every morning (legislators, votes, bills, that sort of thing). For these, "it passed" isn't enough information. I want to know whether anything actually changed, how much changed, and if something failed, which specific part failed.

The notifications look like this when things go well:

And like this when they don't:

The workflow builds up a description string based on what each sync step reported, picks a color based on the overall status, and calls the script:

- name: Send Discord notification
  if: always()
  env:
    DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK_URL }}
    LEGISLATORS_RESULT: ${{ steps.legislators.outputs.result }}
    LEGISLATORS_FAILED: ${{ steps.legislators.outputs.failed }}
    # ... etc for other steps
  run: |
    # Parse the JSON output from each step
    LEG_CHANGED=$(echo "$LEGISLATORS_RESULT" | jq -r '.changed // false')
    LEG_COUNT=$(echo "$LEGISLATORS_RESULT" | jq -r '.recordsUpserted // 0')

    # Determine overall status and pick a color
    if [ "$LEGISLATORS_FAILED" = "true" ] || [ "$VOTES_FAILED" = "true" ]; then
      TITLE="🚨 Data Refresh Failed"
      COLOR=15158332  # red
    elif [ "$LEG_CHANGED" = "true" ] || [ "$VOTES_CHANGED" = "true" ]; then
      TITLE="📊 Data Refresh Complete"
      COLOR=3066993  # green
    else
      TITLE="✅ Data Refresh - No Changes"
      COLOR=9807270  # gray
    fi

    # Build the description
    if [ "$LEGISLATORS_FAILED" = "true" ]; then
      LEG_STATUS="❌ **Legislators**: Failed"
    elif [ "$LEG_CHANGED" = "true" ]; then
      LEG_STATUS="✅ **Legislators**: ${LEG_COUNT} upserted"
    else
      LEG_STATUS="⏭️ **Legislators**: Unchanged"
    fi

    # ... similar for votes, bills, etc

    DESC="${LEG_STATUS}"$'\n'"${VOTES_STATUS}"$'\n'"${BILLS_STATUS}"
    GH_RUN="https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}"

    .github/scripts/discord-notify.sh \
      --title "$TITLE" \
      --color "$COLOR" \
      --description "$DESC" \
      --button "View Run|$GH_RUN"

The key is having your sync scripts output structured JSON ({"changed": true, "recordsUpserted": 42}). Once you have that, you can format it however you want.

The "Oh No Production Is Broken" Notification

I also run smoke tests after Cloudflare finishes deploying to production. These only send a notification on failure, because I don't need a pat on the head every time something works correctly. I'm not a golden retriever.

- name: Send Discord notification on failure
  if: failure()
  env:
    DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK_URL }}
  run: |
    GH_RUN="https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}"

    .github/scripts/discord-notify.sh \
      --title "🚨 Smoke Test Failed" \
      --color 15158332 \
      --description "One or more smoke tests failed against production." \
      --button "View Run|$GH_RUN" \
      --button "Production|https://democracy-direct.com" \
      --button "Cloudflare|https://dash.cloudflare.com"

Three buttons: one to the GitHub Action run, one to production so I can see if it's actually broken, and one to Cloudflare in case I need to roll back. Everything I need to start debugging, right there in the notification.

"But There Are GitHub Actions For This Already"

There are, and they're fine for simple cases. I didn't use them because:

First, there's no official Discord action. These are all third-party, which means you're trusting some random developer's JavaScript (or Docker container) to run in your CI pipeline with access to your secrets. The most popular one even recommends pinning to a specific commit SHA for "stability purposes," which is really security advice dressed up in polite language. I'd rather just use curl.

Second, it's literally just curl and jq, both of which are already installed on GitHub runners. No dependencies to install, no Docker images to pull, no supply chain to worry about.

Third, I can actually read it. The whole notification logic is right there in my repo where I can see it. Want to change something? Just change it. Want to copy it to another project? Copy and paste.

Why Discord Instead of Slack

If your company is already paying for Slack and you have SSO requirements and compliance needs and all 2,600 of those integrations, then by all means, use Slack.

But if you're a solo dev working on open source projects, or a small team that doesn't want to pay per-seat pricing for a chat app:

Discord is actually free, not "free but we delete your message history after 90 days" free
No per-seat pricing, which matters less when you're one person but matters a lot if your project grows and you want to bring on contributors
Mobile notifications work great, which is really all I wanted in the first place

The tradeoff is that Discord doesn't have deep integrations with Jira or Salesforce or whatever enterprise tools you might use at a day job. For a project that lives entirely in GitHub and deploys to Cloudflare, I genuinely do not care about that.

Go Look at the Actual Files

The complete workflow files and the notification script are in the Democracy Direct repo if you want to see how everything fits together:

discord-notify.sh - The reusable notification script
refresh-data.yml - Daily sync with detailed status reporting
smoke-test.yml - Post-deploy verification that only alerts on failure
sync-sponsored-bills.yml - Weekly job with summary notifications

They're not pristine examples of software engineering. The jq pipelines are kind of dense if you're not familiar with the syntax. But they work, and you're welcome to steal whatever parts are useful to you.

Democracy Direct is an open source civic engagement platform. Check it out on GitHub.

The Eyes Have It: Closing the Agentic Design Loop

Aaron Ross — Tue, 03 Feb 2026 23:05:56 +0000

The thing that makes LLMs actually work for coding, aside from reviewing the output carefully, is tight feedback loops.

Something that can be unit tested is easy to get an LLM to complete. You describe the acceptance criteria, have it write the tests, then follow TDD until the task is done. Review, look for vulnerabilities and edge cases, repeat as necessary. You can even take the human out of parts of this loop with automated code review on PRs. Let the bots fight it out until they're satisfied, then bring in the human to verify.

I've been a developer for almost 10 years. I've worked across stacks and languages. I've had clients patent my work. I'm not saying this to brag, I'm saying it because when I tell you that front-end design has been the single most frustrating part of using language models for coding, I want you to know it's not because I don't know what I'm doing.

The UI Feedback Loop is Broken

When it comes to user experience, the feedback loop has historically been really frustrating. It goes something like this:

You: "Center the modal and add some padding"
AI: changes code
You: "It's centered but now there's way too much padding"
AI: "How much padding would you like?"
You: "Less. Like, half that. Also the close button is too close to the edge now"
AI: changes code
You: "The padding is better but you broke the close button positioning"
AI: "Can you describe what's wrong with the close button?"
You: gives up, opens the CSS file, fixes it in 30 seconds

I usually don't make it past step 5. It ends up being way faster for me to just make the styling edits manually because I know CSS and the robot often doesn't do things in a modern or holistic way.

(I've seen more !important flags from Claude and Cursor than from all of the junior devs I've worked with combined. Reward hacking is a real problem with LLMs.)

You can paste screenshots into the chat, and that helps. But then you're doing it manually every time, and you have to remember to do it, and you're still the one who has to notice something looks off before you think to take a screenshot. It's better than pure description, but it's still a lot of back and forth where you, the human, are the bottleneck.

Closing the Loop

Claude Code has a --chrome flag that connects it to a browser extension. This gives it tools to take screenshots, resize the viewport, click around, and generally interact with your browser. The workflow changes:

You: "Make the contact form button more prominent"
AI: changes code, takes screenshot, notices the double border it just introduced
AI: "Done. I also noticed the border change created a double-border issue where the preview container meets the button area, so I fixed that too."

Or even better: you notice something wrong and say "the preview tab has a double border." Instead of guessing at why, the agent can go to the page, click the preview button, and take a screenshot. Context is king, and what it looks like is the most valuable UI context there is.

How to Set This Up

Install the Claude in Chrome extension
Log into claude.ai in Chrome
Start Claude Code with claude --chrome

The browser tools become available automatically. This gives Claude Code the ability to take screenshots, click and scroll around the page, resize the viewport to test responsive breakpoints, and record interactions as GIFs (useful for docs or sharing progress).

A few things worth knowing: you need a dev server running since Claude can't refresh the browser for you. Auth-gated pages work fine as long as you're already logged in when you start the session. Hot reload works great with this setup (that's kind of the whole point).

Real Example: Redesigning Democracy Direct's Contact Flow

Democracy Direct is a civic engagement tool I've been building. You find your representatives and write them letters. The main interface is the ContactFlow component, and it needed work.

The old layout:

Everything stacked vertically: user info fields at top, editor, preview, "Send Your Letter" button, then a whole separate "Print & Mail" section with address fields and formatting checkboxes. Problems were everywhere. Editor and Preview stacked vertically meant lots of scrolling. Actions buried at the bottom. Print options always visible even though most people use the digital flow. On mobile, you'd scroll past the entire letter to find "Send."

The new layout:

Two-column layout with the sidebar on the right. View mode buttons (Edit/Preview/Print Preview) replace the stacked editor and preview. Actions are always visible at the bottom (disabled when empty, not hidden). Print formatting options only appear in Print Preview mode. "Send via Contact Form" is now the hero action, impossible to miss.

On mobile:

The sidebar ("Your Information") appears above the editor via CSS order utilities. Users fill in their info before scrolling to the letter. Action buttons stack into a 2-column grid.

Where Visual Feedback Actually Helped

A few specific moments from the session where having screenshots made a real difference:

Mobile reordering. The sidebar needed to appear above the editor on mobile (so users fill in their info before scrolling to the letter) but beside it on desktop. I could have described this verbally and hoped Claude understood, but it was faster to just have it resize the viewport to 375px wide and verify the CSS order utilities worked correctly. Screenshot, confirm, move on.

The double border. When we wrapped the <LetterPreview /> in a container with its own border, we got a double border where it met the existing preview border. Claude caught this on the screenshot immediately ("I notice there's a double border issue") and fixed it in the same response. This is exactly the kind of thing I'd notice ten minutes later while testing something else.

Button layout on mobile. Getting the action buttons to form a sensible 2-column grid on mobile while staying in a row on desktop required iteration. Being able to resize the viewport and screenshot after each change made this converge quickly instead of becoming a back-and-forth about what "the buttons look weird on mobile" meant.

Closing Thoughts

This isn't revolutionary technology. It's just closing a feedback loop that was previously open. LLMs work well when they can verify their own output. For most code, that means tests. For UI, that means screenshots.

The result is fewer rounds of "what do you mean by weird spacing" and more rounds of actual iteration. For a civic engagement tool where the UI directly impacts whether someone successfully contacts their representative, that matters.

Democracy Direct is an open source project focused on making civic engagement more accessible. Check it out on GitHub.

I built a civic engagement platform because contacting your representatives shouldn't be this hard

Aaron Ross — Sun, 01 Feb 2026 06:21:48 +0000

A few weeks ago I was doomscrolling and feeling some type of way about... waves indiscriminately at the state of the world. The thing that always gets me during times like these is feeling like there's nothing I can do about any of it.

So I had a good think about what I actually can do. And I landed on something that's been bugging me for years: contacting your elected representatives is unreasonably hard. You have to dig through multiple government websites to figure out who represents you, find contact info in outdated directories, and then stare at a blank text box wondering what to even say. It's enough friction that most people just... don't.

I'm a software engineer with almost 10 years of web development experience. I can't fix policy but I can fix a bad user experience. So I built Democracy Direct.

What it does right now

You put in your ZIP code and see your two senators and your representative with their contact info and social media links. You can save your district so you don't have to look it up every time.

The feature I'm most excited about is letter templates. Somebody writes a good letter about healthcare or housing or whatever, and other people can grab it, customize it, and send it. One person's effort becomes a tool for a lot of people. Templates can be public or private, and they include short descriptions so they show up well in search results and social sharing. No account needed to browse or use templates. Your messages never touch the server, everything stays on your device.

What's coming

Next up is voting records and legislation tracking. I want you to be able to see how your reps actually voted, search bills, read plain-language summaries, and link letter templates directly to specific legislation. After that, campaign finance data and an interactive district map. Longer term the goal is to expand beyond federal to cover state legislators and local officials too.

The roadmap is public: democracy-direct.com/roadmap

Privacy first

This was non-negotiable from the start. ZIP code lookups happen entirely in your browser using pre-loaded data. We never see what you search. If you create an account, your email gets hashed with SHA-256 before it's stored. We can't recover it even if we wanted to. Letters you write never touch the server. Analytics are anonymous through PostHog with no session recordings and no way to link usage data back to you.

Cloudflare Turnstile keeps bots from spamming the template system, and I'm using AI moderation to help with content review so one person can actually run this thing without drowning in moderation work.

The stack

I wanted to move fast, ship something that loads fast, and deploy to Cloudflare Pages. That meant Astro with React and TypeScript, which is also the sweet spot for working with AI coding agents. I've been building most of this with Claude Code and experimenting with Ralph loops throughout the project with varying degrees of success. When it works it's like having a junior dev who never sleeps. When it doesn't you're cleaning up some truly creative messes.

The database is Neon PostgreSQL. On-demand compute, easy branching and replication per PR, and a generous free tier. Authentication is OTP codes via AWS SES. No passwords to manage, no passwords to forget, no credential stuffing to worry about.

Representative data comes from public sources: unitedstates/congress-legislators for federal, Open States for state legislators, and the U.S. Census Bureau for ZIP code mapping.

Building in public

The whole thing is open source under AGPL because civic infrastructure should be auditable and forkable. No ads, no sponsors, no premium tier, no data sales. Funded by donations if you're into that sort of thing.

Democracy Direct is independent. No party, no PAC, no nonprofit. Just a frustrated engineer who decided to build something instead of doomscroll.

Code's at github.com/anomalousventures/democracy-direct. Contributions welcome, whether that's code, templates, bug reports, or whatever. If it's useful to you, share it with someone who'd use it. The whole point is making it easier for people to be heard.