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:

1. Go to your openstatus dashboard
2. Click on a monitor
3. 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

1. Go to your openstatus workspace settings
2. Navigate to the API section
3. Create a new API key or copy an existing one
4. 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:

1. Go to your GitHub repository
2. Click Settings → Secrets and variables → Actions
3. Click New repository secret
4. Name: OPENSTATUS_API_KEY
5. Value: Your openstatus API key
6. 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

1. Start small: Begin with 2-3 critical monitors
2. Fail fast: Run synthetic tests early in your pipeline
3. Monitor the monitors: Track your synthetic test success rate
4. Environment-specific: Use different monitors for staging vs production
5. 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

Related resources

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