Setting Up Upptime: GitHub-Powered Status Page

What Is Upptime?

Upptime is an open-source uptime monitor and status page powered entirely by GitHub. It uses GitHub Actions to check your sites every 5 minutes, GitHub Issues for incident tracking, and GitHub Pages for the public status page. No server, no database, no Docker — just a GitHub repository. It replaces StatusPage.io, UptimeRobot, and Pingdom for basic monitoring needs, at zero cost.

Official site: upptime.js.org | GitHub

How It Works

Component	Powered By	Purpose
Monitoring	GitHub Actions	Checks endpoints every 5 minutes
Incidents	GitHub Issues	Auto-opens when downtime detected, closes on recovery
Status page	GitHub Pages	Public-facing dashboard with uptime history
Data storage	Git commits	Response times stored as YAML in `history/` directory
Graphs	GitHub Actions	Daily response time charts generated automatically

Everything runs inside GitHub’s free tier. No external dependencies.

Setup

1. Create from Template

Go to github.com/upptime/upptime and click “Use this template” → “Create a new repository.”

Name it something like status or upptime. Make it public (required for GitHub Pages on free plans) or use a GitHub Pro/Team account for private repos.

2. Configure Sites to Monitor

Edit .upptimerc.yml in your new repository:

owner: your-github-username
repo: status

sites:
  - name: Main Website
    url: https://example.com
  - name: API
    url: https://api.example.com
    method: POST
    headers:
      - "Content-Type: application/json"
    body: '{"test": true}'
    expectedStatusCodes:
      - 200
      - 201
  - name: Internal Service
    url: $INTERNAL_URL
    port: 443
    __dangerous__insecure: true

status-website:
  cname: status.example.com
  logoUrl: https://example.com/logo.svg
  name: Example Status
  introTitle: "**Example** is up and running"
  introMessage: Real-time status powered by [Upptime](https://github.com/upptime/upptime).
  navbar:
    - title: Status
      href: /
    - title: GitHub
      href: https://github.com/$OWNER/$REPO

3. Set Up Repository Secrets

In your repository Settings → Secrets → Actions, add:

GH_PAT — a GitHub Personal Access Token with repo scope (needed for the Actions workflow to commit data)

For private URLs or secrets in your config, add them as repository secrets and reference with $SECRET_NAME.

4. Enable GitHub Pages

Go to Settings → Pages:

Source: Deploy from a branch
Branch: gh-pages / (root)

The status page will be live at https://your-username.github.io/status/ (or your custom domain if cname is set).

5. Verify Workflows Are Running

Go to the Actions tab. You should see workflows running:

Uptime CI — runs every 5 minutes
Response Time CI — records response times every 6 hours
Graphs CI — generates charts daily
Static Site CI — builds the status page

Configuration Reference

Site Monitoring Options

sites:
  - name: Website Name
    url: https://example.com
    method: GET                    # HTTP method (default: GET)
    headers:                       # Custom headers
      - "Authorization: Bearer token"
    body: '{"key": "value"}'       # Request body (for POST/PUT)
    expectedStatusCodes:           # Expected response codes
      - 200
      - 301
    maxResponseTime: 5000          # Alert if response > 5s (ms)
    assignees:                     # GitHub users notified on incident
      - username1
      - username2
    icon: https://example.com/favicon.ico

Notifications

Upptime supports notifications through GitHub Actions integrations:

notifications:
  - type: slack
    channel: C0XXXXXXXXX
    token: $SLACK_TOKEN
  - type: discord
    webhookUrl: $DISCORD_WEBHOOK
  - type: email
    address: [email protected]

Monitoring Frequency

The default check interval is 5 minutes. To change it, edit .github/workflows/uptime.yml:

schedule:
  - cron: "*/5 * * * *"  # Every 5 minutes (default)
  - cron: "*/1 * * * *"  # Every minute (uses more Actions minutes)

Comparison with Docker-Based Status Pages

Feature	Upptime	Gatus	Uptime Kuma
Infrastructure	None (GitHub)	Docker	Docker
Cost	Free	Free	Free
Monitoring frequency	5 min (configurable)	Configurable (seconds)	1-min minimum
Alerting	Slack, Discord, email	Slack, Discord, PagerDuty, 20+	90+ notification types
TCP/ICMP checks	Yes	Yes	Yes
Incident management	GitHub Issues	Built-in	Manual
Dashboard	Static (GitHub Pages)	Dynamic web UI	Dynamic web UI
API monitoring	Basic	Advanced (conditions)	Basic
Self-hosted server	Not needed	Required	Required

Limitations

5-minute minimum interval on GitHub’s free tier (1-minute costs more Actions minutes)
Public repository required for GitHub Pages on free plans
No real-time dashboard — the status page is a static site, rebuilt on each check
GitHub Actions minutes — free tier gives 2,000 minutes/month (sufficient for ~5 sites at 5-min intervals)
No complex alerting rules — if you need escalation policies or on-call rotation, use Gatus or Uptime Kuma instead

Troubleshooting

Workflows Not Running

Symptom: No uptime checks in the Actions tab.

Fix: Ensure the GH_PAT secret is set with repo scope. Also verify the repository isn’t archived — GitHub doesn’t run Actions on archived repos.

Status Page Not Updating

Symptom: The GitHub Pages site shows stale data.

Fix: Check that the gh-pages branch exists and GitHub Pages is configured to deploy from it. Run the “Static Site CI” workflow manually from the Actions tab.

False Downtime Alerts

Symptom: Sites reported as down when they’re actually up.

Fix: GitHub Actions runners may have network issues. Add maxResponseTime: 30000 to allow slower responses. For sites behind Cloudflare or similar CDNs, add expected status codes (e.g., 403 for blocked GitHub IPs).

Resource Requirements

Server: None required
GitHub Actions: ~500 minutes/month for 5 sites at 5-min intervals
Storage: A few MB in your repository (YAML history files)

Verdict

Upptime is the perfect monitoring solution if you want a status page without running another server. The GitHub-native approach means zero maintenance and zero cost. The trade-off is flexibility — for complex alerting, sub-minute checks, or internal network monitoring, Uptime Kuma or Gatus are better choices. Use Upptime for public-facing status pages where simplicity wins. Use Docker-based monitors when you need real-time dashboards and advanced alerting.

Frequently Asked Questions

Does Upptime require a server or VPS?

No. Upptime runs entirely on GitHub Actions and GitHub Pages. Your monitoring checks run as scheduled GitHub Actions workflows, and the status page is hosted on GitHub Pages. This makes it completely serverless and free within GitHub’s free tier limits.

How frequently can Upptime check my sites?

The default check interval is every 5 minutes, configured via GitHub Actions cron. You can increase it to every minute, but frequent checks consume more GitHub Actions minutes. The free tier includes 2,000 minutes per month — at 5-minute intervals, monitoring 5 sites uses about 500 minutes monthly.

Can Upptime monitor internal or private services?

No. GitHub Actions runs on GitHub’s infrastructure, so it can only monitor publicly accessible endpoints. For internal network monitoring, use Uptime Kuma or Gatus deployed on your local network instead.

How does Upptime compare to Uptime Kuma?

Uptime Kuma is a Docker-based monitor with a real-time dashboard, 90+ notification types, and sub-minute checks. Upptime is serverless, free, and zero-maintenance but limited to public endpoints and 1-minute minimum intervals. Choose Upptime for simple public status pages; choose Uptime Kuma for comprehensive monitoring with advanced alerting.

Can I customize the Upptime status page appearance?

Yes. The status page is a static site generated from your GitHub repository. You can customize the logo, colors, layout, and content through the .upptime.yml configuration file. The page supports custom domains via GitHub Pages CNAME configuration.

Does Upptime send notifications when a site goes down?

Yes. Upptime supports notifications through GitHub Issues (created automatically on downtime), email, Slack, Discord, Telegram, and other services via GitHub Actions integrations. Configure notification channels in your .upptime.yml file.