Quickstart

Get Upptime monitoring your services in under 5 minutes

Quickstart

Get your Upptime instance up and running in under 5 minutes. This guide will walk you through the fastest path to a working uptime monitor.

This quickstart uses the Upptime template repository. For a more detailed setup, see the Installation guide.

1. Create repository from template

   Go to the Upptime template repository and click “Use this template” to create a new repository in your GitHub account.

   Choose a repository name (e.g., upptime or status) and set it to Public (required for free GitHub Actions minutes and Pages).

   The repository must be public to use GitHub’s free tier. Private repositories have limited Actions minutes.

2. Enable GitHub Actions

   After creating your repository, GitHub Actions should be enabled by default. Verify by going to the Actions tab in your repository.

   If Actions are disabled, enable them in your repository settings under Settings > Actions > General.

3. Configure your sites

   Edit the .upptimerc.yml file in your repository to add the websites you want to monitor.

   Update the owner and repo fields with your GitHub username and repository name:

   owner: your-github-username
   repo: upptime
   

   Then add your sites to monitor:

   sites:
     - name: My Website
       url: https://mywebsite.com
     - name: API Endpoint
       url: https://api.mywebsite.com/health
     - name: Documentation
       url: https://docs.mywebsite.com
   

   Commit this change directly to the main branch.

4. Create a GitHub Personal Access Token

   Upptime needs a Personal Access Token (PAT) to create issues and update your repository.

   1. Go to GitHub Settings > Developer settings > Personal access tokens > Tokens (classic)
   2. Click “Generate new token (classic)”
   3. Give it a descriptive name like “Upptime”
   4. Set expiration to “No expiration” (or your preferred duration)
   5. Select these scopes:
      • repo (Full control of private repositories)
      • workflow (Update GitHub Action workflows)
   6. Click “Generate token” and copy the token

   Save this token securely - you won’t be able to see it again!

5. Add the token to repository secrets

   Store your Personal Access Token as a repository secret:

   1. Go to your repository Settings > Secrets and variables > Actions
   2. Click “New repository secret”
   3. Name it GH_PAT
   4. Paste your Personal Access Token as the value
   5. Click “Add secret”
6. Enable GitHub Pages

   Enable GitHub Pages to host your status page:

   1. Go to Settings > Pages
   2. Under “Source”, select “Deploy from a branch”
   3. Under “Branch”, select gh-pages and / (root)
   4. Click “Save”

   The gh-pages branch will be created automatically when the setup workflow runs.

7. Trigger the setup workflow

   The setup workflow runs automatically when you edit .upptimerc.yml, but you can also trigger it manually:

   1. Go to the Actions tab
   2. Click on “Setup CI” workflow
   3. Click “Run workflow”
   4. Select the main branch and click “Run workflow”

   This workflow will:

   • Generate all necessary GitHub Actions workflows
   • Create initial response time data
   • Build and deploy your status page to GitHub Pages
   • Update the README with your status summary
8. Access your status page

   After the setup workflow completes (usually 2-3 minutes), your status page will be live!

   Access it at: https://your-username.github.io/your-repo-name

   For example: https://mycompany.github.io/upptime

What happens next?

Once setup is complete, Upptime runs automatically:

• Every 5 minutes: The Uptime CI workflow checks all your sites
• Every 6 hours: Response times are recorded and committed
• Daily: Graphs are regenerated with the latest data
• When downtime occurs: A GitHub Issue is automatically opened
• When service recovers: The issue is automatically closed

Customize your status page

You can customize the status page by editing .upptimerc.yml:

status-website:
  cname: status.mywebsite.com  # Use your custom domain
  logoUrl: https://mywebsite.com/logo.svg
  name: My Company Status
  introTitle: "Welcome to **My Company** status page"
  introMessage: Real-time monitoring of our services
  navbar:
    - title: Status
      href: /
    - title: Main Site
      href: https://mywebsite.com
    - title: GitHub
      href: https://github.com/$OWNER/$REPO

After editing .upptimerc.yml, the Setup CI workflow runs automatically to regenerate your workflows and status page.

Add a custom domain

To use a custom domain like status.mywebsite.com:

1. Add the cname field to your .upptimerc.yml:

   status-website:
     cname: status.mywebsite.com
   

2. Add a CNAME record in your DNS settings pointing to:

   your-username.github.io
   

3. Commit the changes and wait for the Setup CI workflow to complete

Next steps

• Configure advanced monitoring options
• Set up notifications
• Customize your status page
• Learn about incident tracking

Troubleshooting

Setup workflow failed?

• Verify your GH_PAT secret is set correctly
• Check that the token has repo and workflow scopes
• Ensure the repository is public or has sufficient Actions minutes

Status page not showing?

• Wait 5-10 minutes after the first setup workflow completes
• Check that GitHub Pages is enabled and set to the gh-pages branch
• Look for errors in the “Static Site CI” workflow logs

Sites showing as down incorrectly?

• Verify the URLs in .upptimerc.yml are correct and accessible
• Check if the sites require authentication or have CORS restrictions
• Review the workflow logs in the Actions tab for specific errors