Star Trak

Overview

Ever noticed fluctuations in your repository's GitHub star count and wondered what happened? This action helps you track star activity using the List Stargazers API. The data are written in JSON format to a file of your choosing. You can use the EndBug/add-and-commit action to commit the result to your Git repository or even publish it to an external service like S3.

Getting started

Personal Access Token

You'll first need to create a Personal Access Token (PAT) to allow access to the List Stargazers API. Follow these instructions to create your PAT with the public_repo scope.

Next, add the PAT to your repository's encrypted secrets following these instructions. You can choose any name you want; but, if you're looking for a suggestion, GH_ACCESS_TOKEN works well.

Workflow configuration

Note

This section focuses on configuring this particular action. For a complete workflow you can use, see Sample workflow below.

You'll need to add a step like this to your GitHub Actions workflow file.

- uses: nsaunders/star-trak@v1
  with:
    path: .github/stars.json # default
    repo: ${{ github.repository }}
    token: ${{ secrets.GH_ACCESS_TOKEN }}

How it works

When this step runs:

the file at the specified path will be read if it exists;
a new entry containing added and removed stargazers will be added; and
the result will be saved to the file at the specified path.

Note

If the file at the specified path does not exist, it will automatically be created for you.

Inputs

Name	Description	Required?
path	The path (relative to the workspace) where star data will be written in JSON format. If the file does not exist, then it will be created automatically. Otherwise, new data will be added to it while preserving any existing data. If not specified, this setting defaults to .github/stars.json.	optional
repo	The repository whose stars to monitor in <owner>/<repository> format. A typical value, obtained from the github context, would be `${{ github.repository }}`.	required
token	The PAT used to access the List Stargazers API	required

Recommendations

Use a schedule event to run the workflow on a recurring schedule. Weekly is a "sensible default", but you may want to consider running it daily if your repository's stars fluctuate more frequently, in order to ensure that all activity is captured.
Use actions/checkout and EndBug/add-and-commit to ensure that history is saved across workflow runs. Alternatively, you can design any workflow that begins by retrieving your stars.json file (e.g. from a S3 bucket) into your workspace and saving it back to the same place at the end.

Sample workflow

stars.yml:

name: stars

on:
  schedule:
    - cron: "45 23 * * 0"

jobs:
  update:
    name: update

    runs-on: ubuntu-latest

    env:
      STARS_PATH: meta/stars.json

    steps:
      - uses: actions/checkout@v4

      - uses: nsaunders/star-trak@v1
        with:
          path: ${{ env.STARS_PATH }}
          repo: ${{ github.repository }}
          token: ${{ secrets.GH_ACCESS_TOKEN }}

      - uses: EndBug/add-and-commit@v9
        with:
          add: ${{ env.STARS_PATH }}
          author_name: GitHub Actions
          author_email: 41898282+github-actions[bot]@users.noreply.github.com
          message: Log repository stars.