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.
Before you start
Section titled “Before you start”- Create a Heartbeat Monitor, and copy the Heartbeat URL on its Checks card.
- In your GitHub repository, open Settings, then Secrets and variables, then Actions, and press New repository secret.
- 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.
A scheduled workflow
Section titled “A scheduled workflow”This workflow runs a backup each night at 03:00, then calls the Monitor:
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.
After a deploy
Section titled “After a deploy”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:
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.
Inputs
Section titled “Inputs”| 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@v1When the call does not get through
Section titled “When the call does not get through”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.
Without the Action
Section titled “Without the Action”The Action makes one call to the URL. A run step with curl does the same, and Heartbeat examples shows it.