Setup and Publishing

Setup and publishing

The action runs inside the repository that owns the release assets, queries GitHub with the workflow token, and writes the resulting files to a dedicated branch. The recommended @v1 reference follows compatible releases in the current major version.

Choose a workflow profile

The repository provides three maintained templates:

Template	Schedule	Published result
gh-dl-daily.yml	Daily at 03:00 UTC	JSON for badges
gh-dl-hourly.yml	At the start of every hour	More frequently refreshed JSON
gh-dl-daily-with-chart.yml	Daily at 03:00 UTC	JSON, primary chart, and chart matrix

Download the selected template and save it under .github/workflows/ in the repository being measured. Commit and push the workflow, then open the repository's Actions tab and run it once through Run workflow. The manual first run avoids waiting for the next scheduled trigger.

Minimal daily workflow

This is the essential configuration used by the daily JSON profile:

name: gh-dl-daily

on:
  schedule:
    - cron: "0 3 * * *"
  workflow_dispatch:

permissions:
  contents: write

jobs:
  publish-downloads:
    runs-on: ubuntu-latest
    steps:
      - name: Publish download statistics
        uses: justagwas/github-downloads-action@v1
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          window_days: "45"
          output_branch: "gh-pages"
          output_path: "gh-dl/downloads.json"

contents: write is required because the action creates or updates files in the repository. GITHUB_TOKEN is generated for the workflow run and is the recommended token when the workflow measures and publishes within its own repository.

What happens on the first run

1. The action resolves the owner and repository from the workflow context.
2. It verifies that the token can read the repository and its releases.
3. It creates gh-pages from the default branch if the output branch does not exist.
4. It sums current release asset download counters.
5. It creates the first dated snapshot and publishes gh-dl/downloads.json.
6. If chart publishing is enabled, it writes the requested SVG files.
7. It adds a summary of totals, partial flags, and published paths to the workflow run.

The first snapshot cannot describe earlier daily activity because GitHub provides cumulative asset counters rather than a historical download event stream. The action begins building its own history from this run onward.

Verify the output

For a public repository using the defaults, open:

https://raw.githubusercontent.com/OWNER/REPOSITORY/gh-pages/gh-dl/downloads.json

Replace OWNER and REPOSITORY exactly. The response should be JSON containing stats, partial, snapshots, and profile. You do not need to enable a GitHub Pages website for this raw file URL.

If the workflow succeeds but the URL returns 404, confirm the output branch and path in the run summary. A protected branch or insufficient workflow permissions can prevent publication even when the statistics calculation itself succeeds.

Measuring another repository

The optional owner and repo inputs can target a repository other than the workflow repository. The token must then be permitted to read releases and write the output branch in that target repository. The normal GITHUB_TOKEN is scoped to its own repository, so cross-repository publication generally requires a carefully scoped personal access token or GitHub App token stored as a secret.