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.

Related

• Self-Hosting Uptime Kuma with Docker Compose
• Self-Hosting Gatus with Docker Compose
• Best Self-Hosted Monitoring & Uptime Tools
• Self-Hosting Grafana with Docker Compose
• Docker Compose Basics
• Reverse Proxy Setup
• Self-Hosting Healthchecks with Docker Compose