Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/upptime/upptime/llms.txt

Use this file to discover all available pages before exploring further.

Upptime uses GitHub Issues to manage incidents. When a site goes down, an issue is automatically opened. When it comes back up, the issue is automatically closed. This provides a transparent, git-based incident management system.

​
How It Works

When the uptime workflow detects a site is down:
  1. A GitHub Issue is automatically opened
  2. The issue is labeled with the site name
  3. Team members can be automatically assigned
  4. Subsequent checks update the issue
  5. When the site recovers, the issue is automatically closed
All incidents are tracked in your repository’s Issues tab, providing complete transparency and history.

​
Issue Templates

Upptime includes built-in issue templates for different scenarios:

​
Automatic Downtime Issues

When Upptime detects downtime, it opens an issue with:
  • Site name and URL
  • Current status code or error
  • Timestamp of the incident
  • Link to the status page

​
Manual Maintenance Events

You can manually create scheduled maintenance issues using the template:
.github/ISSUE_TEMPLATE/maintainance-event.md
---
name: Maintenance Event
about: Schedule a work window
title: "[Scheduled Maintenance] Site down for Maintenance"
labels: maintenance
assignees: ''
---

<!--
start: 2021-08-24T13:00:00.220Z
end: 2021-08-24T14:00:00.220Z
expectedDown: google, hacker-news
-->

**Additional context**
Who/what/when/where/why is this maintenance happening
The HTML comments in the template contain structured data that Upptime uses to schedule maintenance windows.

​
Bug Reports

For reporting issues with Upptime itself:
.github/ISSUE_TEMPLATE/bug_report.md
---
name: Bug report
about: Create a report to help us improve
title: ''
labels: 'bug'
assignees: 'AnandChowdhary'
---

**Describe the bug**
A clear and concise description of what the bug is.

**To Reproduce**
Steps to reproduce the behavior

**Expected behavior**
A clear and concise description of what you expected to happen.

​
Issue Configuration

​
Assignees

Automatically assign team members to incident issues:
.upptimerc.yml
assignees:
  - username1
  - username2
When a site goes down, these users will be assigned to the incident issue.

​
Labels

Customize labels for better organization:
.upptimerc.yml
status-website:
  labels:
    - name: incident
      color: "dc3545"
    - name: maintenance  
      color: "ffc107"

​
Incident Workflow

When Upptime detects a site is down:
  1. Checks if an open issue already exists for this site
  2. If not, creates a new issue
  3. Applies labels and assignees
  4. Posts initial status to the issue

​
Incident Reports

Team members can add incident updates by commenting on the issue:
Post updates directly as issue comments:
We're investigating reports of slow response times. The issue appears to be related to database performance.
These updates automatically appear on the status page.
Document findings for future reference:
**Root Cause**: Database connection pool exhaustion
**Fix Applied**: Increased pool size from 10 to 50 connections
**Prevention**: Added monitoring alerts for pool usage
Keep stakeholders informed:
**Update 10:30 AM**: Engineering team is aware and investigating
**Update 11:15 AM**: Issue identified, deploying fix
**Update 11:45 AM**: Fix deployed, monitoring for stability

​
Scheduled Maintenance

Schedule planned maintenance to prevent false alarms: 
<!--
start: 2026-03-10T02:00:00.000Z
end: 2026-03-10T04:00:00.000Z
expectedDown: 
  - google
  - wikipedia
-->

Scheduled database migration. Services will be unavailable during this window.
During scheduled maintenance windows, sites marked as expectedDown won’t trigger incident issues.

​
Issue Permissions

By default, issues are configured to:
  • Allow issue creation by the workflow
  • Lock issues to prevent spam
  • Allow team members to comment
  • Automatically close when resolved

​
Locking Issues

To prevent non-team members from commenting on sensitive incidents:
.upptimerc.yml
workflowSchedule:
  uptime: "*/5 * * * *"
  
issues:
  lock: true

​
Integration with Status Page

Incidents tracked in GitHub Issues automatically appear on your status page:

Active Incidents

Open issues appear prominently at the top of the status page

Incident History

Closed issues are listed in the history section

Update Timeline

Issue comments appear as incident updates

Downtime Duration

Calculated from issue open/close timestamps

​
Benefits of GitHub Issues

Using GitHub Issues for incident management provides:
All incidents are publicly visible (for public repos), building trust with users.
Complete history of all incidents with timestamps and updates.
Team members can discuss and coordinate in issue comments.
Works with GitHub’s notification system, mobile apps, and API.
No need for separate incident management software.

​
Issue Template Configuration

Customize issue templates in .github/ISSUE_TEMPLATE/config.yml:
.github/ISSUE_TEMPLATE/config.yml
blank_issues_enabled: true
contact_links:
  - name: Feature requests and ideas
    url: https://github.com/orgs/upptime/discussions/new?category=ideas
    about: Suggest an idea for this project
  - name: Questions
    url: https://github.com/orgs/upptime/discussions/new?category=q-a
    about: Please ask and answer questions here

​
Best Practices

Add Context

Use issue comments to document investigation steps and findings

Tag Team Members

@mention relevant team members to notify them of incidents

Link Related Issues

Reference related incidents or PRs for context

Update Regularly

Post status updates every 30-60 minutes during active incidents

​
Next Steps