Skip to main content

Get Started


We currently only recommend using Stoat for public repos!

Paid authentication for private repos is on our roadmap. Until it's released, all files, all metrics, and all other data you publish to Stoat for templating will be publicly accessible!

1. Install GitHub Application

Go to the Stoat GitHub application page and install the application for your repository.

The application requires the following permissions:

User emailsReadNecessary for user identification and authentication.
MetadataReadEnabled by default.
ActionsReadCurrently not used. Necessary to read GitHub job logs.
Pull requestsWriteNecessary to create and update comments in pull requests.

If you have any questions or concerns about the permissions, or run into any problems, please let us know.

2. Install CLI


  • Node/NPM
  • Mac/Linux

To install, run:

npm i -g stoat

3. Initialize Stoat for a Git Repository

To initialize a Stoat project within a Git repository, run:

stoat init

The initialization command will create a configuration file for Stoat at .stoat/config.yaml and will give you the option to add the Stoat GitHub action as the final step in all GitHub jobs.

4. Configure Stoat

To start pushing data to Stoat, you will need to add additional configuration.

We have comprehensive examples and guides for different types of users:

We also have tutorials explaining how to enable specific functionality: