Repository

To use Stethoscope to track your health and life data, 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 from stethoscope-js/stethoscope. Alternately, you can follow these steps:

  1. Visit the Stethoscope repository on GitHub: https://github.com/stethoscope-js/stethoscope
  2. Click on the "Use this template" button on the top-right
  3. Enter a name for your new repository
  4. 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.

note

Stethoscope commits the data points you enable to this repository. Treat choosing a public repository and enabling GitHub Pages as explicit consent to publish that data. All data points are opt-in, so enable only what you intend to collect and share.

For private tracking, use a private repository and leave GitHub Pages disabled. For public sharing, use a separate repository containing only the data points you are comfortable publishing. See Setting repository visibility.

After creating your repository

The following steps apply to your new repository, not the stethoscope-js/stethoscope template repository.

Enable publishing

To access your public data endpoints, enable publishing using GitHub Pages. This publishes the repository's generated data, not just a dashboard, so review the enabled integrations and existing data/ files first.

  1. Go to your repository settings page
  2. Scroll to "GitHub Pages" settings
  3. Under "Source", change "None" to "master"
  4. Click on "Save"

After saving, you will see confirmation text "Your site is ready to be published at...". For more information on enabling GitHub Pages, see the article on the GitHub website: Configuring a publishing source for your GitHub Pages site.

If you do not want a public data site, do not enable GitHub Pages and keep the repository private.

Deleting sample data

There is sample data available in the data directory. You have to start by deleting the data directory in your new repository. To delete the directory, perform the following steps (source):

  1. Clone your newly created repository (see Cloning a repository)
  2. Enter the directory (cd stethoscope) in a terminal window
  3. Ensure you are in the default branch: git checkout master
  4. Recursively remove the folder: git rm -r data
  5. Commit the change: git commit -m ":fire: Remove sample data"
  6. Push the change to your remote repository: git push origin master

Update configuration

The .stethoscoperc.yml file is used as the central configuration store. In that file, you can specify which services you want to connect to using Integrations.

Enter the slug of each service you intend to use. For example, these four integrations fetch enabled data each day:

.stethoscoperc.yml
integrations:
rescuetime:
frequency: "daily"
all: true
last-fm:
frequency: "daily"
all: true
wakatime:
frequency: "daily"
all: true
clockify:
frequency: "daily"
all: true

Google Fit, Pocket Casts, Goodreads, and Twitter/X appear in older repositories and remain documented for reading existing data, but are not recommended for new setups. See the integration status notes before enabling a service; a successful scheduled action run alone does not prove that each adapter succeeded. Check the latest run manifest for per-adapter outcomes.

Add tracking data points

All data points are opt-in, so you have to individually enable which items to track for each Integration.

For example, if you have enabled the RescueTime integration, you can track your overview, top categories, and top activities. In this example, we are enabling the overview and top categories, but not top activities in the .stethoscoperc.yml file. A sample file is available in the repository: .stethoscoperc.yml.

.stethoscoperc.yml
integrations:
rescuetime:
overview: true
categories: true
activities: false

Detailed documentation about which data points are available for each service is present in Integrations.

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).

For example, if you have enabled the RescueTime integration, you need to provide the API key. Specify the environment variable RESCUETIME_API_KEY by adding it as a repository secret.

Detailed documentation about which environment variables are required for each service are available in Integrations.

Next steps

  1. Start tracking data by performing a manual trigger.
  2. Optionally, add older data from your integrations using by migrating old data
  3. Create embeds to add visualization to your website
Edit this page