How to Run Synthetic Tests in GitHub Actions

Problem

You want to validate that your application's critical endpoints are working before deploying to production. Running synthetic tests in your CI/CD pipeline catches issues early and prevents broken deployments.

Solution

openstatus provides a GitHub Action that runs your configured monitors as part of your CI/CD workflow. This guide shows you how to set it up.

Prerequisites

An openstatus account
A GitHub repository
At least one monitor configured in openstatus
Admin access to your GitHub repository (for secrets)

Step-by-step guide

1. Create a configuration file

Create a file named openstatus.config.yaml in your repository root:

tests:
  ids:
    - 1
    - 2

Finding monitor IDs:

Go to your openstatus dashboard
Click on a monitor
The ID is in the URL: https://www.openstatus.dev/app/[workspace]/monitors/[ID]

Tip: Start with your most critical monitors and expand from there.

2. Get your openstatus API key

Go to your openstatus workspace settings
Navigate to the API section
Create a new API key or copy an existing one
Store it securely - you'll need it for the next step

3. Add your API key to GitHub Secrets

Secure your API key as a GitHub secret:

Go to your GitHub repository
Click Settings → Secrets and variables → Actions
Click New repository secret
Name: OPENSTATUS_API_KEY
Value: Your openstatus API key
Click Add secret

4. Create the GitHub Action workflow

Create .github/workflows/openstatus.yml:

name: Run openstatus Synthetics CI

on:
  workflow_dispatch:  # Manual trigger
  push:
    branches: [ main ]  # Trigger on push to main
  pull_request:        # Run on PRs (optional)

jobs:
  synthetic_ci:
    runs-on: ubuntu-latest
    name: Run openstatus Synthetics CI
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        
      - name: Run openstatus Synthetics CI
        uses: openstatushq/openstatus-github-action@v1
        with:
          api_key: ${{ secrets.OPENSTATUS_API_KEY }}

5. Commit and push

git add openstatus.config.yaml .github/workflows/openstatus.yml
git commit -m "Add openstatus synthetic tests to CI"
git push origin main

The GitHub Action will run automatically on the next push to main.

What you've accomplished

Great work! You've successfully:

✅ Integrated openstatus into your CI/CD pipeline
✅ Automated synthetic testing on every deployment
✅ Added a safety check before production releases
✅ Set up continuous validation of critical endpoints

Customization options

Run on different branches

on:
  push:
    branches: [ main, staging, develop ]

Run on pull requests

on:
  pull_request:
    types: [opened, synchronize, reopened]

Run on a schedule

on:
  schedule:
    - cron: '0 */4 * * *'  # Every 4 hours

Multiple configuration files

- name: Run openstatus Synthetics CI
  uses: openstatushq/openstatus-github-action@v1
  with:
    api_key: ${{ secrets.OPENSTATUS_API_KEY }}
    config_file: .openstatus/production.yaml

Best practices

Start small: Begin with 2-3 critical monitors
Fail fast: Run synthetic tests early in your pipeline
Monitor the monitors: Track your synthetic test success rate
Environment-specific: Use different monitors for staging vs production
Document failures: Investigate and document any CI failures

Troubleshooting

Action fails with authentication error:

Verify OPENSTATUS_API_KEY secret is set correctly
Check that your API key hasn't expired

Monitors not found:

Confirm monitor IDs are correct in openstatus.config.yaml
Ensure monitors are active in your openstatus dashboard

Tests timing out:

Check that your endpoints are accessible from GitHub's runners
Consider increasing timeouts in monitor configuration

Next steps

Monitor Your MCP Server - Advanced monitoring examples
Monitoring as Code - Manage monitors with YAML
CLI Reference - Automate monitor management
Export Metrics - Send data to your observability platform

GitHub Action on Marketplace - Official action
Example Repository - Working examples
Join Discord - Get help from the community