Uptime Monitoring

Learn how Upptime monitors your websites using GitHub Actions and scheduled workflows

Upptime uses GitHub Actions to monitor your websites and APIs at regular intervals. The monitoring system runs completely serverless, with no external infrastructure required.

How It Works

The uptime monitoring workflow runs on a cron schedule, checking your configured endpoints and recording their status.

By default, Upptime checks your sites every 5 minutes. This is configurable in the workflow file.

The Uptime Workflow

The uptime check is powered by the uptime.yml workflow:

.github/workflows/uptime.yml

name: Uptime CI
on:
  schedule:
    - cron: "*/5 * * * *"
  repository_dispatch:
    types: [uptime]
  workflow_dispatch:
jobs:
  release:
    name: Check status
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          ref: ${{ github.head_ref }}
          token: ${{ secrets.GH_PAT || github.token }}
      - name: Check endpoint status
        uses: upptime/uptime-monitor@v1.41.0
        with:
          command: "update"
        env:
          GH_PAT: ${{ secrets.GH_PAT || github.token }}
          SECRETS_CONTEXT: ${{ toJson(secrets) }}

Workflow Triggers

The uptime workflow can be triggered in three ways:

Scheduled (Cron)

Runs automatically every 5 minutes:

schedule:
  - cron: "*/5 * * * *"

You can customize this schedule using standard cron syntax.

Repository Dispatch

Can be triggered programmatically via the GitHub API:

repository_dispatch:
  types: [uptime]

Manual Trigger

Can be manually triggered from the GitHub Actions UI:

workflow_dispatch:

Configuring Sites to Monitor

Sites are configured in your .upptimerc.yml file:

.upptimerc.yml

sites:
  - name: Google
    url: https://www.google.com
  - name: Wikipedia
    url: https://en.wikipedia.org
  - name: Hacker News
    url: https://news.ycombinator.com

Advanced Check Types

Upptime supports different types of health checks:

HTTP/HTTPS

The default check type for web endpoints:

sites:
  - name: My Website
    url: https://example.com

TCP Ping

For checking TCP connectivity to ports:

sites:
  - name: IPv6 test
    url: forwardemail.net
    port: 80
    check: "tcp-ping"
    ipv6: true

Custom Headers

Add custom headers to your requests:

sites:
  - name: API Endpoint
    url: https://api.example.com
    headers:
      - "Authorization: Bearer $SECRET_TOKEN"

What Gets Checked

For each configured site, Upptime:

1. Sends a request to the URL
2. Records the HTTP status code (200, 404, 500, etc.)
3. Measures response time in milliseconds
4. Commits the result to the repository’s history
5. Opens or closes issues based on up/down status

All check results are stored in YAML files under the history/ directory, creating a complete audit trail.

Status Detection

Upptime determines if a site is up or down based on:

• HTTP status codes: 2xx and 3xx are considered “up”
• Network connectivity: Connection timeouts or DNS failures mark sites as “down”
• Response time: Sites that don’t respond within the timeout are marked as “down”

History Files

Each monitored site gets its own history file:

history/google.yml

url: https://www.google.com
status: up
code: 200
responseTime: 131
lastUpdated: 2026-03-02T23:16:08.212Z
startTime: 2020-08-10T07:54:39.000Z
generator: Upptime <https://github.com/upptime/upptime>

GitHub Actions Benefits

Using GitHub Actions for monitoring provides:

Zero Cost

Free for public repositories, included in GitHub Free minutes for private repos

No Server Required

Completely serverless - no infrastructure to maintain

Git-Based History

All monitoring data is versioned in git with complete history

Transparent

All workflow runs are visible in the Actions tab

Frequency and Limits

GitHub Actions has usage limits. The free tier includes:

• 2,000 minutes/month for private repositories
• Unlimited minutes for public repositories

With checks every 5 minutes, you’ll use approximately 8,640 workflow minutes per month per monitored site.

Next Steps

• Learn about Response Time Tracking
• Configure Incident Management
• Set up Notifications