tiennm99
ad775adffa
`ghglance -serve :8080` runs a web UI from the same binary: submit a username, a background job renders every card in every theme, and /u/<user> shows them again with a theme picker and embed URLs. - Cards are stored on disk with atomic symlink publishing and deleted after -retention (default 24h); -cooldown limits token-less regeneration. - Token-less jobs use a public-only server token with private and org scope forced off; a submitter's own token is used for that job only and never stored or logged. The form links to GitHub's new-token page with the needed scopes pre-ticked. - The CLI and web share one fetch helper; CLI output is unchanged. - compose.yml deploys to Coolify with a data volume and /healthz check.
7.7 KiB
Deployment Guide
Three consumption paths: GitHub Action, prebuilt binaries, go install. The same binary also runs as a self-hosted web UI (section 4).
1. GitHub Action (recommended for README auto-updates)
Workflow template
File: .github/workflows/ghglance.yml in your profile repo.
name: ghglance
on:
schedule:
- cron: "0 0 * * *" # daily at 00:00 UTC
workflow_dispatch:
permissions:
contents: write # needed for commit_changes
jobs:
cards:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
- uses: tiennm99/ghglance@v1
with:
user: ${{ github.repository_owner }}
token: ${{ secrets.GHGLANCE_TOKEN }}
themes: dracula,github_dark,tokyonight
tz: Asia/Saigon
# start_of_week: monday # optional; default sunday — rotates heatmap rows + weekday bars
include_forks: "false"
include_private: "false"
commit_changes: "true"
Required secrets
GHGLANCE_TOKEN: a classic personal access token with at minimum:
| Scope | Needed for |
|---|---|
read:user |
Basic profile fields, contribution calendar |
repo |
Only if include_private: "true" |
Fine-grained PATs and the default ${{ github.token }} lack the introspection scope for contribution calendars in many orgs, so a classic PAT is recommended.
Create one at https://github.com/settings/tokens → "Generate new token (classic)" → select read:user (+ repo if needed) → save as repo secret GHGLANCE_TOKEN.
Embedding in README
The Action commits SVGs to output/<theme>/ on the default branch. GitHub serves them from the raw URL the README references.
2. Prebuilt binaries
Each tag under v* publishes:
- Linux
amd64,arm64 - macOS
amd64,arm64 - Windows
amd64
Released via .github/workflows/release.yml which matrixes GOOS × GOARCH, strips symbols (-ldflags="-s -w"), and uploads tar.gz / zip to the GitHub Release.
Install:
# Linux x86_64 example
curl -L https://github.com/tiennm99/ghglance/releases/latest/download/ghglance_linux_amd64.tar.gz \
| tar xz
./ghglance -user YOUR_USERNAME
3. go install
go install github.com/tiennm99/ghglance@latest
Requires Go 1.26+. Puts the binary in $(go env GOPATH)/bin.
4. Web UI (Docker Compose / Coolify)
compose.yml at the repo root builds the Dockerfile, overrides its
entrypoint to run ghglance -serve :8080 -data-dir /data, stores cards in
the ghglance-data volume, and health-checks /healthz with busybox
wget. It publishes no host port; Coolify routes the domain generated for
SERVICE_FQDN_GHGLANCE_8080 to container port 8080.
| Variable | Needed for |
|---|---|
GHGLANCE_GITHUB_TOKEN |
Required by compose.yml, which passes it to the container as GITHUB_TOKEN for token-less submissions. Must be public-only: a classic PAT with just read:user. A token with repo scope or any private-repo access is refused for token-less jobs (GitHub would count private contributions in totals and calendars). |
Coolify: create a Docker Compose resource from this repo, compose file
/compose.yml, set GHGLANCE_GITHUB_TOKEN, assign the domain, deploy. Server flags
(-cooldown, -retention, -workers, -timeout) are changed by editing command: in
compose.yml. Steps for a plain Docker host and the request-handling rules
are in the README's "Run the web UI" section.
Rollback: redeploy the previous commit. Card sets on the volume are format-stable, so no data migration is involved.
Docker image
Published to ghcr.io/tiennm99/ghglance:<tag> on each v* release via .github/workflows/release.yml (buildx, multi-tag: exact version, major.minor, major, latest).
The Action itself uses a runner-built image by default (image: Dockerfile in action.yml). To switch to the pre-built image for faster cold starts, edit action.yml:
runs:
using: docker
image: docker://ghcr.io/tiennm99/ghglance:v1
Release process
- Tag:
git tag -a v1.2.0 -m "..." && git push origin v1.2.0. release.ymlrunsgo vet+go testas a gate before the docker and binaries jobs. If tests fail, no artifacts ship.- On green, GHCR push + cross-platform binary artifacts happen automatically.
- The
update-major-tagjob force-moves the floating major tag (e.g.v1) to this release's commit after test + docker + binaries all pass. Consumers pinned totiennm99/ghglance@v1pick up the release on their next Action run without a workflow edit. - Docker base images and third-party actions are SHA-pinned (with version comments) so mutable-tag changes upstream can't rewrite a released image.
- Marketplace: the action is listed on the GitHub Marketplace as
ghglance; the listing name comes fromname:inaction.yml. Publishing is a web-UI step — edit the GitHub release and tick "Publish this Action to the GitHub Marketplace" — sinceaction-gh-releasecannot publish it.
Rollback
- Revert the tag:
git push --delete origin v1.2.0, delete GitHub release, delete GHCR tag. - Users pinned to
@v1keep working because the previous patch is still tagged.
Rate limit considerations
| Scenario | GraphQL calls per run | Notes |
|---|---|---|
| Typical user, defaults | 15–40 | Well under 5000 pts/hr |
| Active user (8 years, 30+ seed repos) | 40–80 | Still comfortable |
-include-private=true with 100+ work repos |
80–200 | Fine for daily cron |
| Adversarial user with 500+ committed repos/year | Capped by maxRepositories: 100 per year query |
Long tail drops silently |
No REST calls today. Future -accurate-languages mode will push toward 1000+ REST per run; schedule that mode less frequently (weekly, not daily).
The client auto-handles rate-limit responses: on 429 or 403 with X-RateLimit-Remaining: 0, it sleeps up to 5 minutes (honoring Retry-After / X-RateLimit-Reset) and retries once. A reset window longer than 5 min surfaces as an error so CI can reschedule instead of burning runner time. Use the -timeout flag (default 30m) to cap total fetch duration; SIGINT/SIGTERM cancels in-flight requests cleanly.
Troubleshooting
| Symptom | Check |
|---|---|
| "error: fetch profile: graphql: Could not resolve to a User" | Username typo |
| "http 401" | Token expired or lacks read:user |
| "rate limit resets in 42m (>5m0s max wait)" | Client refused to sleep through a long window; reschedule the Action |
| "http 403" on non-rate-limit path | PAT scope too narrow |
| Blank contribution chart | User has 0 contributions in their window; expected |
| Private repo data missing | -include-private=true not set, or PAT lacks repo |
| Nothing committed by the Action | Check permissions: contents: write in the workflow |