GitLab CI + Sandglass: Heartbeat Monitoring for Scheduled Pipelines

Q: Should I put the heartbeat ping in after_script or in the main script?

It depends on what you want to monitor. Main script: the ping only fires when all preceding commands succeed, so a missing heartbeat means the job failed or did not run. after_script: the ping fires regardless of job outcome, which is useful if you want to confirm the pipeline ran at all and handle success/failure separately.

Q: Does this work with GitLab pipeline schedules that use only_if or rules?

Yes. The heartbeat step runs as part of the job, so it respects whatever conditions control the job itself. If the job is skipped by a rule, the heartbeat is not sent, and Sandglass opens an incident after the window expires.

Q: What if my GitLab runner does not have outbound internet access?

The runner needs to reach sandglass.it on port 443. If your runners are in a private network, you may need to allow outbound HTTPS to sandglass.it in your firewall or proxy rules. Alternatively, route the ping through a proxy using curl's --proxy flag.

Q: Can I monitor a multi-project pipeline with one heartbeat check?

Yes. Add the heartbeat ping to the final downstream job in the pipeline chain. That job only runs when all upstream projects complete, so one ping confirms the full chain ran successfully.

Q: How do I handle pipelines that run on multiple branches with different schedules?

Create a separate heartbeat check for each branch/schedule combination. Each gets its own URL and interval. Store multiple URLs as separate CI/CD variables (e.g., SANDGLASS_HEARTBEAT_MAIN, SANDGLASS_HEARTBEAT_STAGING) and reference the right one per job.

Scheduled pipelines that stop running are invisible failures. Make them visible.

Ping Sandglass at the end of every GitLab CI scheduled pipeline so you know it ran. When a pipeline silently stops executing, Sandglass opens an incident instead of letting the failure go unnoticed.

Requirements

A GitLab project with at least one pipeline schedule configured under CI/CD > Schedules
Maintainer or Owner access to add CI/CD variables to the project
A Sandglass heartbeat check with its URL stored as the SANDGLASS_HEARTBEAT_URL CI/CD variable
A Sandglass account on any plan

How to connect

Step 1: Create a heartbeat check in Sandglass

Add a new Heartbeat check in Sandglass and set the expected interval to match your pipeline schedule. For a daily pipeline, 25 hours gives a comfortable buffer. Copy the heartbeat URL after saving.

Tip

Use a descriptive name like "gitlab-nightly-etl" so the Sandglass incident subject is immediately actionable when it lands in your inbox.

Step 2: Store the URL as a masked CI/CD variable

In GitLab, go to Settings > CI/CD > Variables and add a new variable named SANDGLASS_HEARTBEAT_URL. Paste the heartbeat URL as the value and check "Mask variable" so it never appears in job logs.

Step 3: Add the heartbeat ping in after_script

In your .gitlab-ci.yml, add an after_script block to the job (or a dedicated final stage) that runs: "curl -fsS -m 10 --retry 3 \"$SANDGLASS_HEARTBEAT_URL\"". Use after_script only if you want the ping to fire even on failure; put it in the main script block if you want it to fire only on success.

Tip

For explicit failure reporting, add a separate script line that curls the /fail variant of the URL when the job exits non-zero. Combine both for full coverage: success pings the normal URL, failure pings /fail.

Step 4: Confirm the first scheduled run

Trigger the pipeline manually from CI/CD > Schedules > Run pipeline, then check the Sandglass dashboard. The heartbeat check should flip to "Up" within seconds of the job completing. If it stays pending, open the job log and confirm the curl line ran and returned HTTP 200.

What you can do

Detect missed pipeline schedules: GitLab does not notify you when a scheduled pipeline stops running. Sandglass does. Whether the runner goes offline, the schedule gets accidentally disabled, or the job fails before the ping step, Sandglass opens an incident.
Works across self-managed and GitLab.com: The heartbeat curl works identically on GitLab.com and self-managed GitLab instances. As long as the runner has outbound internet access to sandglass.it, the integration works.
Per-pipeline granularity: Create one heartbeat check per scheduled pipeline. Each has its own interval, its own incident history, and its own alert channels. You can group related pipelines under a single Sandglass group to share notification settings.
Explicit failure signaling: The /fail suffix on the heartbeat URL opens a Sandglass incident immediately rather than waiting for the heartbeat window to expire. Useful for pipelines where you want instant alerting on job failure, not just on missed runs.

Frequently Asked Questions

Should I put the heartbeat ping in after_script or in the main script?

Does this work with GitLab pipeline schedules that use only_if or rules?

What if my GitLab runner does not have outbound internet access?

Can I monitor a multi-project pipeline with one heartbeat check?

How do I handle pipelines that run on multiple branches with different schedules?

Stop flying blind on scheduled pipeline failures

Start free

Free plan, no credit card required.