Configuration and Troubleshooting

Configuration and troubleshooting

Most repositories only need token, window_days, output_branch, and output_path. The remaining inputs support another target repository, API caching, or chart presentation.

Core inputs

Input	Default	Meaning
token	Empty	Token for GitHub API reads and output writes. Pass ${{ secrets.GITHUB_TOKEN }} for the current repository.
owner	Workflow owner	Repository owner to measure and publish into
repo	Workflow repository	Repository name to measure and publish into
window_days	45	Number of dated totals retained, from 1 through 3650
enable_hourly_profile	false	Labels the profile as hourly; use with an hourly schedule
output_branch	gh-pages	Branch containing generated files
output_path	gh-dl/downloads.json	Repository-relative JSON path
min_refresh_minutes	0	Reuses a sufficiently recent previous total instead of querying all releases, from 0 through 10080 minutes
publish_chart	false	Enables primary and matrix SVG publication

min_refresh_minutes changes API freshness, not workflow frequency. A cached run still processes and republishes the snapshot model when its material output changes, but total_source reports cache instead of api.

Chart inputs

Input	Default	Allowed values or range
chart_output_path	gh-dl/downloads-trend.svg	Repository-relative SVG path
chart_types	total-trend	total-trend, daily, weekly, monthly
chart_themes	slate	black, slate, orange
charts_output_dir	gh-dl/charts	Repository-relative directory
chart_width	1000	640 through 4096 pixels
chart_height	360	240 through 2160 pixels
chart_zero_baseline	true	Boolean
chart_y_ticks	6	2 through 12 intervals
chart_x_label_every_days	0	0 through 365 days; 0 selects automatic spacing
chart_show_value_labels	false	Boolean
chart_date_label_format	yyyy-mm-dd	yyyy-mm-dd, yy/mm/dd, dd/mm, mm/dd, none
chart_show_generated_at	true	Boolean
chart_title_mode	default	default, custom, none
chart_title_text	Empty	Required for custom title mode, up to 120 characters

The JSON path cannot overlap the primary chart or any matrix chart path. Branch names and output paths are validated, and absolute paths, empty segments, and parent-directory traversal are rejected.

Action outputs

Later workflow steps can read the action outputs after assigning an id to the step:

- name: Publish download statistics
  id: downloads
  uses: justagwas/github-downloads-action@v1
  with:
    token: ${{ secrets.GITHUB_TOKEN }}

- name: Report result
  run: |
    echo "Total: ${{ steps.downloads.outputs.total }}"
    echo "Published: ${{ steps.downloads.outputs.published }}"

Available outputs include:

• resolved owner and repo;
• generated_at, total, day, week, and month;
• partial_day, partial_week, and partial_month;
• total_source, either api or cache;
• published, indicating whether downloads.json materially changed;
• chart publication status, counts, and generated file paths;
• resolved output branch and paths.

Troubleshooting

Symptom	Cause and response
Workflow requests a token	Pass token: ${{ secrets.GITHUB_TOKEN }} and keep permissions: contents: write.
GitHub API returns 403	Check workflow permissions, token scope, organization policy, and API rate limits. A cross-repository target needs a token authorized for that target.
Write to gh-pages fails	Branch protection or repository policy is blocking Actions. Permit the workflow to write there or select a compatible output branch.
Raw JSON returns 404	Run the workflow once, then confirm output_branch and output_path in the run summary. Check capitalization in the owner and repository URL.
Badge displays resource not found	The JSON is not anonymously readable, commonly because the repository is private. Open the JSON source URL in a signed-out browser to verify public access.
Badge still shows an older value	GitHub Raw, jsDelivr, or Shields is serving a cached response. Confirm the JSON first and allow the display cache to expire.
partial.week or partial.month is true	Snapshot history is still warming up or the exact baseline date is missing. Continue scheduled runs and retain a sufficient window.
Day, week, or month appears low	The value may be partial, an asset may have been removed, or the repository has little release-asset activity. Compare the current total and snapshot series.
Workflow produces no commit	published=false means the JSON had no material change. This is expected for a same-day rerun with the same total and snapshot settings.
Chart files are absent	Set publish_chart: "true", then verify chart paths do not overlap output_path.
Custom chart title fails validation	Set chart_title_mode: "custom" and provide a nonempty chart_title_text no longer than 120 characters.

API and publication behavior

The action retries temporary GitHub API failures, rate limits, timeouts, and concurrent content-write conflicts within bounded limits. A persistent permissions error or invalid input stops the workflow rather than publishing incomplete data.

When charts are enabled, each changed chart is written as a separate branch update. A large type and theme matrix can therefore create several small commits during one run. Request only the chart combinations that will actually be embedded.