Configuration Reference

The .upptimerc.yml file is the central configuration file for Upptime. It defines which sites to monitor, how to present your status page, and various monitoring behaviors.

Basic Configuration

Repository Settings

owner

string

required

Your GitHub username or organization name where this repository lives

repo

string

required

The name of this repository

Example:

owner: upptime
repo: upptime

Sites Configuration

sites

array

required

Array of sites to monitor. Each site is an object with the following properties.

Site Object

sites[].name

string

required

Display name for the site (used in status page and issues)

sites[].url

string

required

URL or hostname to monitor. Can be a full URL (with protocol) or just a hostname for TCP checks.

sites[].check

string

default:"http"

Type of check to perform:

http - HTTP/HTTPS request (default)
tcp-ping - TCP port connectivity check
dns - DNS resolution check

sites[].port

number

Port number for TCP checks (only used with check: "tcp-ping")

sites[].ipv6

boolean

default:false

Whether to use IPv6 for the check

sites[].method

string

default:"GET"

HTTP method to use (GET, POST, PUT, etc.)

sites[].headers

array

Custom HTTP headers to send with requests. Format: ["Header-Name: value"]

sites[].body

string

Request body for POST/PUT requests

sites[].expectedStatusCodes

array

Array of acceptable HTTP status codes. Site is considered up if response code matches any in this array.

sites[].assignees

array

GitHub usernames to assign to issues when this site goes down

sites[].slug

string

Custom slug for the site (auto-generated from name if not provided). Used in URLs and file names.

sites[].maxResponseTime

number

default:30000

Maximum time (in ms) to wait for a response before timing out

sites[].maxRedirects

number

default:5

Maximum number of redirects to follow

Example:

sites:
  - name: Google
    url: https://www.google.com
  
  - name: Wikipedia
    url: https://en.wikipedia.org
    expectedStatusCodes:
      - 200
      - 301
  
  - name: Hacker News
    url: https://news.ycombinator.com
    method: GET
    headers:
      - "User-Agent: Upptime"
  
  - name: Test Broken Site
    url: https://thissitedoesnotexist.koj.co
  
  - name: IPv6 test
    url: forwardemail.net
    port: 80
    check: "tcp-ping"
    ipv6: true

Status Website Configuration

status-website

object

Configuration for the status website hosted on GitHub Pages

Basic Website Settings

status-website.cname

string

Custom domain for your status page (e.g., status.example.com). Omit if using GitHub Pages default domain.

status-website.baseUrl

string

Base URL path for the site. Use /{repo-name} if not using a custom domain. Omit if using a custom domain.

status-website.logoUrl

string

URL to your logo image (PNG, SVG, etc.)

status-website.name

string

Name of your status page

status-website.introTitle

string

Title text on the homepage (supports Markdown)

status-website.introMessage

string

Introduction message on the homepage (supports Markdown)

Navigation links in the header. Each item has title and href properties.

status-website.theme

string

default:"light"

Color theme: light, dark, or auto

status-website.favicon

string

URL to your favicon

status-website.faviconSvg

string

URL to your SVG favicon

status-website.metaDescription

string

Meta description for SEO

Example:

status-website:
  cname: demo.upptime.js.org
  logoUrl: https://raw.githubusercontent.com/upptime/upptime.js.org/master/static/img/icon.svg
  name: Upptime
  introTitle: "**Upptime** is the open-source uptime monitor and status page"
  introMessage: This is a sample status page which uses **real-time** data
  navbar:
    - title: Status
      href: /
    - title: GitHub
      href: https://github.com/$OWNER/$REPO
  theme: light

Internationalization (i18n)

status-website.i18n

object

Internationalization settings for the status page

status-website.i18n.activeIncidents

string

Custom text for “Active Incidents”

status-website.i18n.allSystemsOperational

string

Custom text for “All Systems Operational”

status-website.i18n.incidentReport

string

Custom text for “Incident Report”

status-website.i18n.activeIncidentSummary

string

Custom text for active incident summary

status-website.i18n.previousIncidents

string

Custom text for “Previous Incidents”

Example:

status-website:
  i18n:
    activeIncidents: Active Incidents
    allSystemsOperational: All Systems Operational
    incidentReport: Incident Report for $SITE

Notification Configuration

notifications

array

Array of notification integrations. Each notification type has different configuration options.

Slack Notifications

notifications[].type

string

Set to "slack" for Slack notifications

notifications[].webhookUrl

string

Slack webhook URL (use $SECRET_NAME to reference GitHub secrets)

Example:

notifications:
  - type: slack
    webhookUrl: $SLACK_WEBHOOK_URL

Discord Notifications

notifications[].type

string

Set to "discord" for Discord notifications

notifications[].webhookUrl

string

Discord webhook URL

Example:

notifications:
  - type: discord
    webhookUrl: $DISCORD_WEBHOOK_URL

Telegram Notifications

notifications[].type

string

Set to "telegram" for Telegram notifications

notifications[].botToken

string

Telegram bot token

notifications[].chatId

string

Telegram chat ID

Example:

notifications:
  - type: telegram
    botToken: $TELEGRAM_BOT_TOKEN
    chatId: $TELEGRAM_CHAT_ID

Email Notifications

notifications[].type

string

Set to "email" for email notifications

notifications[].to

string

Email address to send notifications to

notifications[].smtpHost

string

SMTP server hostname

notifications[].smtpPort

number

SMTP server port

notifications[].smtpUsername

string

SMTP username

notifications[].smtpPassword

string

SMTP password

Example:

notifications:
  - type: email
    to: alerts@example.com
    smtpHost: smtp.gmail.com
    smtpPort: 587
    smtpUsername: $SMTP_USERNAME
    smtpPassword: $SMTP_PASSWORD

Advanced Settings

assignees

array

Default GitHub usernames to assign to all issues (can be overridden per-site)

skipDescriptionUpdate

boolean

default:false

Skip updating the repository description with uptime percentage

skipTopicsUpdate

boolean

default:false

Skip updating repository topics

skipHomepageUpdate

boolean

default:false

Skip updating the repository homepage URL

skipDeleteCommand

boolean

default:false

Skip the automatic cleanup/delete commands

commitMessages

object

Custom commit message templates

commitMessages.commitAuthorName

string

default:"Upptime Bot"

Git commit author name

commitMessages.commitAuthorEmail

string

default:"73812536+upptime-bot@users.noreply.github.com"

Git commit author email

workflowSchedule

object

Custom cron schedules for workflows

workflowSchedule.uptime

string

default:"*/5 * * * *"

Cron schedule for uptime checks (default: every 5 minutes)

workflowSchedule.responseTime

string

default:"0 23 * * *"

Cron schedule for response time updates (default: daily at 11 PM UTC)

workflowSchedule.graphs

string

default:"0 0 * * *"

Cron schedule for graph generation (default: daily at midnight UTC)

workflowSchedule.site

string

default:"0 1 * * *"

Cron schedule for site generation (default: daily at 1 AM UTC)

Example:

assignees:
  - AnandChowdhary
  
skipDescriptionUpdate: false

commitMessages:
  commitAuthorName: "Custom Bot Name"
  commitAuthorEmail: "bot@example.com"

workflowSchedule:
  uptime: "*/10 * * * *"  # Every 10 minutes
  responseTime: "0 */6 * * *"  # Every 6 hours
  graphs: "0 2 * * *"  # Daily at 2 AM

User Agent

user-agent

string

Custom User-Agent header for all requests. Use $secret_name to reference secrets.

Example:

user-agent: "UptimeBot/1.0 (+https://upptime.js.org)"

PAT (Personal Access Token)

PAT

string

Reference to GitHub Personal Access Token stored in secrets. Required for private repositories.

Example:

PAT: ${{ secrets.GH_PAT }}

Complete Example

# Repository settings
owner: upptime
repo: upptime

# Sites to monitor
sites:
  - name: Google
    url: https://www.google.com
  
  - name: Wikipedia
    url: https://en.wikipedia.org
  
  - name: Hacker News
    url: https://news.ycombinator.com
  
  - name: Test Broken Site
    url: https://thissitedoesnotexist.koj.co
  
  - name: IPv6 test
    url: forwardemail.net
    port: 80
    check: "tcp-ping"
    ipv6: true

# Status website
status-website:
  cname: demo.upptime.js.org
  logoUrl: https://raw.githubusercontent.com/upptime/upptime.js.org/master/static/img/icon.svg
  name: Upptime
  introTitle: "**Upptime** is the open-source uptime monitor and status page, powered entirely by GitHub."
  introMessage: This is a sample status page which uses **real-time** data from our [GitHub repository](https://github.com/upptime/upptime).
  navbar:
    - title: Status
      href: /
    - title: GitHub
      href: https://github.com/$OWNER/$REPO

# Notifications (optional)
# notifications:
#   - type: slack
#     webhookUrl: $SLACK_WEBHOOK_URL

# Assignees (optional)
# assignees:
#   - AnandChowdhary

Validation

When you push changes to .upptimerc.yml, the Setup workflow automatically validates your configuration and regenerates all workflow files. If there are errors, check the workflow logs in the Actions tab.

Environment Variables

You can use special variables in your configuration:

$OWNER - Replaced with the repository owner
$REPO - Replaced with the repository name
$SECRET_NAME - Replaced with the value from GitHub Secrets

Next Steps

API Overview

Learn about accessing uptime and response time data

GitHub Actions API

Explore workflow commands and triggers

Reference

Documentation Index

​Basic Configuration

​Repository Settings

​Sites Configuration

​Site Object

​Status Website Configuration

​Basic Website Settings

​Internationalization (i18n)

​Notification Configuration

​Slack Notifications

​Discord Notifications

​Telegram Notifications

​Email Notifications

​Advanced Settings

​User Agent

​PAT (Personal Access Token)

​Complete Example

​Validation

​Environment Variables

​Next Steps

API Overview

GitHub Actions API

Basic Configuration

Repository Settings

Sites Configuration

Site Object

Status Website Configuration

Basic Website Settings

Internationalization (i18n)

Notification Configuration

Slack Notifications

Discord Notifications

Telegram Notifications

Email Notifications

Advanced Settings

User Agent

PAT (Personal Access Token)

Complete Example

Validation

Environment Variables

Next Steps