Skip to content

GitHub Action

The You Up? Heartbeat Action tells a Heartbeat Monitor that a GitHub Actions job succeeded, so you hear about a job that failed or never ran. It is listed on the GitHub Marketplace, as uupdev/heartbeat.

Make it the last step of the job. GitHub runs a step only when every step before it succeeded, so a job that fails never calls, and the Monitor goes down once its Grace runs out. To choose how often the job must call, and how late it may be, see Heartbeat Monitors.

  1. Create a Heartbeat Monitor, and copy the Heartbeat URL on its Checks card.
  2. In your GitHub repository, open Settings, then Secrets and variables, then Actions, and press New repository secret.
  3. Name it UUP_HEARTBEAT_URL, paste the URL, and save it.

Keep the URL secret: anyone who has it can call it. The Action hides it in the workflow’s log.

This workflow runs a backup each night at 03:00, then calls the Monitor:

.github/workflows/backup.yml
name: Nightly backup
on:
schedule:
- cron: "0 3 * * *"
jobs:
backup:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: ./backup.sh
# Runs only when every step above succeeded.
- uses: uupdev/heartbeat@v1
with:
url: ${{ secrets.UUP_HEARTBEAT_URL }}

Give the Monitor the same schedule: choose Custom cron, and enter the five fields of the workflow’s cron. GitHub reads a workflow’s cron in UTC. Unless your Project’s timezone is UTC, write the Monitor’s schedule with the same times in the Project’s timezone.

GitHub can start a scheduled workflow some minutes late on a busy day. Give the Monitor a Grace longer than that wait and the job together.

The same step can end a deploy job, so you hear when deploys stop succeeding. Give the deploy its own Heartbeat Monitor and its own secret, such as UUP_HEARTBEAT_URL_DEPLOY:

.github/workflows/deploy.yml
name: Deploy
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: ./deploy.sh
- uses: uupdev/heartbeat@v1
with:
url: ${{ secrets.UUP_HEARTBEAT_URL_DEPLOY }}

A Heartbeat Monitor expects a call in every interval. Set Runs every to the longest time that may pass between two successful deploys, such as a day for a team that deploys each working day. A quiet week with no deploys then shows as down, as a failed deploy does.

Input Default What it does
url empty The Heartbeat URL. Left out, the Action reads the UUP_HEARTBEAT_URL environment variable. When both are empty, the step does nothing and succeeds.
timeout 10 How many seconds to wait for an answer before giving up.
retries 3 How many more times to try when the call gets no answer, or an error from our side.
fail-on-error false Set to true to fail the step when the call does not get through.

An empty URL is how a workflow from a fork behaves: GitHub gives it no secrets, so the step skips the call and the job still passes.

To set the URL for a whole job, put it in the job’s env and leave with out:

jobs:
backup:
runs-on: ubuntu-latest
env:
UUP_HEARTBEAT_URL: ${{ secrets.UUP_HEARTBEAT_URL }}
steps:
- run: ./backup.sh
- uses: uupdev/heartbeat@v1

By default, a call that does not get through writes a warning in the workflow’s log, and your job still passes. The Monitor then goes down once its Grace runs out, as it would for a job that failed, so you still hear about it.

With fail-on-error: true, the step fails instead, and GitHub marks the job as failed.

The step’s status output says what it did: sent, skipped or failed. A later step can read it as steps.<id>.outputs.status, once you give the Action’s step an id.

The Action makes one call to the URL. A run step with curl does the same, and Heartbeat examples shows it.