Github Action: Repository Insight Tracker

This GitHub Action updates the repository statistics including the number of stargazers, commits, contributors, traffic views, and clones. The results are stored in a JSON or CSV file and committed to a specified branch in the repository.

1. Collects statistics on stargazers, commits, contributors, traffic views, and clones using the Github Rest API and GraphQL API.
2. Writes the statistics to a JSON or CSV file under <directory>/<owner>/<repository>/stats.<format>.
3. Commits the file to a specified branch in the repository.
4. Pipes the data as output to the next action, for further processing.

Inputs

Input Name	Description	Required	Default
github-token	GitHub token to authenticate the action.	Yes	${{ secrets.GITHUB_TOKEN }}
owner	The organization or owner of the repository to get insights for.	No	${{ github.owner }}
repository	The repository to get insights for.	No	${{ github.repository }}
branch	The branch where the stats file will be committed.	No	repository-insights
directory	The root directory where the stats file will be stored.	No	./.insights
format	The format of the stats file. Options are json or csv.	No	csv

Outputs

Output Name	Description
stargazers	The total number of stargazers for the repository.
commits	The total number of commits in the default branch.
contributors	The total number of unique contributors to the repository.
traffic_views	The total number of views from yesterday.
traffic_uniques	The total number of unique visitors from yesterday.
clones_count	The total number of clones from yesterday.
clones_uniques	The total number of unique cloners from yesterday.

How to use?

1. Generate a Github Token

The action requires the repository to fetch a Github token other than the tone generated by the action itself, as it accesses traffic/views and clones. This access can only be granted through a private token.

To generate this and apply this token, follow the steps below:

1. Go to Github Settings in the upper right corner,

2. Go to Developer Settings,

3. Generate a new token,

   • In the developer settings, click on Personal Access Token,
   • Click Generate new token,
   • Give your token a descriptive name (e.g., Repository Stats Action),
   • Under Select scopes, choose the following scopes:
     • repo: Full control of private repositories. Required if your repository is private.
     • workflow: Update GitHub Action workflows.
   • Click Generate token
   • Copy the token to your clipboard. You won’t be able to see it again.

4. Add the Token to Your Repository:

   • Navigate to your repository on GitHub.
   • Go to Settings > Secrets and variables > Actions > New repository secret.
   • Name the secret TOKEN (or another name of your choice).
   • Paste the token you copied earlier and click Add secret.

2. Add a workflow file

To use this action in your repository, create a workflow file (e.g., .github/workflows/update-stats.yml) with the contents below.

This is the minimum configurable parameters to run the job, and will collect insights daily, on the repository that the workflow sits in, and store these as a CSV file, on the branch repository-insights, in directory /.insights/<owner>/<repository>/stats.csv.

2.1 Simple example

name: Collect repository insights

on:
  schedule:
    - cron: '0 0 * * *' # Runs daily at midnight
  workflow_dispatch:

jobs:
  update-stats:
    runs-on: ubuntu-latest
    steps:
      - name: Collect insights
        uses: polygenelubricants/repository-insight-tracker@v1.0.0
        with:
          github-token: ${{ secrets.TOKEN }}

2.2 Example with all input parameters

Here is an example with full configurability in the action, that fetches insights from another repository (that you own), and subsequently writes the output to console.

name: Collect repository insights

on:
  schedule:
    - cron: '0 0 * * *' # Runs daily at midnight
  workflow_dispatch:

jobs:
  update-stats:
    runs-on: ubuntu-latest
    steps:
      - name: Collect insights
        id: collect-insights
        uses: polygenelubricants/repository-insight-tracker@v1.0.0
        with:
          github-token: ${{ secrets.TOKEN }}
          branch: 'repository-insights'
          format: 'csv'
          directory: '.insights'
          owner: 'PolygeneLubricants'
          repository: 'planning-poker'
      - name: Write insights to console
        run: |
          echo "Stargazers: ${{ steps.collect-insights.outputs.stargazers }}"
          echo "Commits: ${{ steps.collect-insights.outputs.commits }}"
          echo "Contributors: ${{ steps.collect-insights.outputs.contributors }}"
          echo "Traffic Views Yesterday: ${{ steps.collect-insights.outputs.traffic_views }}"
          echo "Unique Traffic Views Yesterday: ${{ steps.collect-insights.outputs.traffic_uniques }}"
          echo "Clones Yesterday: ${{ steps.collect-insights.outputs.clones_count }}"
          echo "Unique Clones Yesterday: ${{ steps.collect-insights.outputs.clones_uniques }}"

How to contribute?

• Clone the repository or download the files.
• Make your changes to the action's code in index.js.
• Write your tests in __tests__
• Run the tests with npm test
• Pack changes with the following commands:
  • npm run build
• The packaged index.js can be found under dist/index.js.
• Open a PR in polygenelubricants/repository-insight-tracker.