Skip to main content
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/[email protected]
        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:
Runs automatically every 5 minutes:
schedule:
  - cron: "*/5 * * * *"
You can customize this schedule using standard cron syntax.
Can be triggered programmatically via the GitHub API:
repository_dispatch:
  types: [uptime]
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:
The default check type for web endpoints:
sites:
  - name: My Website
    url: https://example.com

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us