---
title: Getting started
---

To use Upptime as an uptime monitor and status website generator, you start by creating a repository using the template on GitHub.

## Create a repository from the template

You can click on the following link to generate a repository using the template: [**Create a new repository**](https://github.com/upptime/upptime/generate) from `upptime/upptime`, make sure that you include all branches. Alternatively, you can visit the [Upptime repository on GitHub](https://github.com/upptime/upptime) and click on the "Use this template" button on the top-right. 

In both cases, the next steps are:

1. Enter a name for your new repository.
1. **Important:** Check "Include all branches".
1. Click on "Create repository from template".

For more details on how to create repositories using template, read the article on the GitHub website: [Creating a repository from a template](https://docs.github.com/en/free-pro-team@latest/github/creating-cloning-and-archiving-repositories/creating-a-repository-from-a-template).

**Billing note:** Upptime uses thousands of build minutes every month (approximately 3,000 minutes in the default setting). If you use a public repository, GitHub offers unlimited free build minutes, but if you use a private repository, you'll have to pay for this time.

## After creating your repository

The following steps apply to your new repository, not the `upptime/upptime` template repository.

### Enable workflows

To be able to see and run all the workflows that come with the upptime repo your first step must be to open the `Actions` tab on your fork. There you will find a dialog and a button that will allow you to enable the workflows that come with upptime.

### Enable publishing

To get a static status website, you have to enable GitHub Pages on your new repository.
Upptime's generated Static Site CI publishes the built website to the `gh-pages` branch, so configure Pages to deploy from that branch. Usually GitHub enables Pages automatically as soon as the `gh-pages` branch is detected. If it doesn't, follow these steps:

1. Go to your repository settings page
1. Go to the "Pages" sub-section on the left
1. Under "Source", select "Deploy from a branch" instead of "GitHub Actions"
1. In the Branch dropdown, select `gh-pages` and `/(root)`
1. Click on "Save"

After saving, you will see confirmation text "Your site is live at..." at the top of the page. For more information on enabling GitHub Pages, see the article on the GitHub website: [Configuring a publishing source for your GitHub Pages site](https://docs.github.com/en/free-pro-team@latest/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site).

If you don't want to have a publicly-available status website, you don't have to enable publishing. If that is the case, you can also choose to keep your repository private. It is **not** possible to publish a status website from a private repository without using an API proxy with authentication. See [#54](https://github.com/upptime/upptime/issues/54) and the [Configuration for `apiBaseUrl`](https://upptime.js.org/docs/configuration#custom-api-base-url) to learn how to set up a status website from your private repository.

### Add repository secrets

All sensitive information required, such as API keys, are provided as environment variables. These are stored as GitHub repository secrets (see [Creating and storing encrypted secrets](https://docs.github.com/en/free-pro-team@latest/actions/reference/encrypted-secrets)).

To make commits and publish your website, Upptime needs a token with access to your status repository. You can use either a GitHub App installation token or a personal access token (PAT). Generated workflows prefer the App token, then `GH_PAT`, then the workflow's `GITHUB_TOKEN`.

**GitHub App option:** Install a GitHub App on your status repository with read-write repository permissions for Actions, Contents, Issues, and Workflows. Set repository **variable** `GH_APP_ID` to the App's **Client ID** (not its numeric App ID), and repository **secret** `GH_APP_PRIVATE_KEY` to its private key. The variable name is historical: Upptime passes it to the `client-id` input of `actions/create-github-app-token@v3`. The workflows generate a short-lived installation token for the current repository; you do not need a `GH_PAT` secret when this succeeds. Do not add `GH_APP_PRIVATE_KEY` to the `.upptimerc.yml` `secrets` allowlist: the generated workflow handles it separately. See [GitHub's instructions for creating a GitHub App](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app) and [managing its private keys](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps).

**PAT option:** Store a personal access token with read-write permissions for Actions, Contents, Issues, and Workflows as the repository secret `GH_PAT`. To create a fine-grained PAT:

1. Click on your profile picture on the top-right corner and select "Settings"
2. In the left sidebar, select "Developer settings"
3. In the left sidebar, click "Personal access tokens" > "Fine-grained tokens"
4. Click "Generate new token"
5. Give your token a specific distinct name
6. In the "Expiration" dropdown, select "90 days" or a custom, longer expiry
7. In the "Resource Owner" section select the user or organization your Upptime repository belongs to
8. In the "Repository Access" section select "Only select repositories" and select your Upptime repository
9. In the "Permissions" > "Repository permissions" section enable read-write access to Actions, Contents, Issues and Workflows
10. Skip the "Organization permissions" section
11. Click "Generate token" or "Generate token and request access" (if it is in an org you are not an admin of)

After generating your token, copy it (you will not see it again). Then, add it as a repository secret:

1. In your Upptime repository, select "Settings"
2. In the left sidebar, click "Secrets and variables" followed by "Actions"
3. Press the button "New repository secret"
4. Enter the name of the secret as `GH_PAT`
5. Paste your personal access token into the Value field
6. Be sure there are no spaces before or after the token and/or linebreaks after your token
7. Save your PAT by selecting "Add secret"

For more information on PATs, read article on the GitHub website: [Creating a personal access token](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token).

Generated workflows pass `GH_PAT` separately. For other secrets, add an exact allowlist to `.upptimerc.yml` so Upptime receives only the values it needs:

```yaml title=".upptimerc.yml"
secrets:
  - PRIVATE_API_URL
  - PRIVATE_API_TOKEN
```

Existing repositories without a `secrets` key use automatic compatibility mode, which generates explicit references for supported configuration and Upptime runtime secrets. It does not pass the complete repository secrets context. See [Secret allowlist](/docs/configuration#secret-allowlist) for strict mode, automatic discovery, and troubleshooting.

### Update configuration

The `.upptimerc.yml` file is used as the central configuration store. In that file, you can specify which endpoints you want to monitor and configure your status website. For more information, visit [Configuration](/docs/configuration).

You can start by setting the owner and repo, and adding your endpoints under `sites`:

```yaml title=".upptimerc.yml"
owner: koj-co # GitHub username
repo: upptime # GitHub repository name
sites: # List of endpoints to track
  - name: Google
    url: https://www.google.com
assignees: # Users to assign downtime issues (optional)
  - AnandChowdhary
status-website: # Status website (optional)
  cname: upptime.js.org # Custom domain CNAME
  name: Upptime # Status website title
```

If you're not using a custom domain, you can remove the line starting with `cname:` and instead add the GitHub repository name using the `baseUrl:` setting:

```yaml
status-website:
  baseUrl: /repo # where "repo" is your repository name
  name: Your Status Website
```

Then, your status page may be hosted on https://user.github.io/repo/, where `user` is your GitHub username and `repo` is your repository name.

### Viewing GitHub Actions workflows

After updating the configuration file, Upptime should run workflows using GitHub Actions to update your `README.md` and generate API endpoints and graphs. To view the status, click on the "Actions" tab in your repository. You should see pending or complete workflows. If you don't, you can manually trigger the "Setup CI" using the [Triggers](/docs/triggers) article.

If you've forked the Upptime repository or have rules to disable Actions by default, you'll have to manually enable GitHub Actions, but this should probably not be your case.

### Best practices

Now that you have your Upptime instance fully set up, you should follow these best practices when adding details to outage incidents.

- Upptime will automatically open a new issue when an outage occurs
- If you haven't identified the cause of this outage, you can add a comment like: "**Investigating**: We're currently investigating the cause of this outage, and we'll update the details here shortly."
- Then, you can add some comments with the details of the outage, and change the name of the issue with the details of the outage
- The issue will be automatically closed when the site comes back up, so you can add a last comment with a postmortem of the outage