Resolve any GitHub repository's version tags to exact, reproducible commit SHAs.

TagSha is a self-hosted web service that looks up a GitHub repository’s tags and resolves each to its exact commit SHA. This makes it trivially safe to pin any dependency, infrastructure component, or CI action to a specific, immutable commit rather than a floating tag.

Use cases:

• Pinning GitHub Actions to SHA instead of tag
• Auditing infrastructure-as-code dependency versions
• Generating reproducible dependency manifests
• Investigating what commit a release tag actually points to

Browser
  │
  └─► Caddy (TLS termination, static files, reverse proxy)
          │
          ├─► API (Go — chi router, zerolog, prometheus)
          │     └─► Redis (tag cache, rate limit counters)
          │     └─► GitHub API (github.com/api.github.com)
          │
          ├─► Frontend (React + TypeScript, served as static files)
          │
          └─► Grafana (dashboards, served at /grafana)
                └─► Prometheus (metrics scraper)

See docs/architecture.md for full detail.

• Docker 24+ with Compose v2
• Node.js 20+ (for frontend build)
• A GitHub Personal Access Token (optional but recommended)

git clone https://github.com/infamousrusty/tagsha.git
cd tagsha

make secrets-init
# Then edit secrets/github_token with a real token

cp .env.example .env
# Edit .env — set TAGSHA_DOMAIN at minimum

make docker-up

The stack will be available at your configured domain (or http://localhost in dev mode).

Security note: Never set TAGSHA_GITHUB_TOKEN in .env for production. Use the Docker secret file at secrets/github_token instead.

Returns application and dependency health status.

{
  "status": "healthy",
  "version": "v1.2.3",
  "checks": { "redis": "ok" },
  "uptime_seconds": 3600.5
}

Prometheus-compatible metrics endpoint.

Parse any GitHub repository identifier into a canonical owner/repo pair.

Request:

{ "query": "https://github.com/golang/go" }

Response:

{ "owner": "golang", "repo": "go", "redirect_url": "/api/v1/tags/golang/go" }

Returns all tags for a repository with resolved commit SHAs.

Response:

{
  "owner": "golang",
  "repo": "go",
  "total_count": 42,
  "truncated": false,
  "tags": [
    {
      "name": "go1.22.2",
      "sha": "a9a4c73c3e5a87e1f6e3e9f89c4b2d8d6a9f1234",
      "message": "go1.22.2",
      "author_name": "Gopher Bot",
      "date": "2024-03-05T17:00:00Z",
      "commit_url": "https://github.com/golang/go/commit/a9a4c73"
    }
  ],
  "cached_at": "2026-03-15T12:00:00Z",
  "github_rate_limit_remaining": 4987
}

Response headers:

• X-Cache: HIT | MISS | STALE — cache status
• X-Request-ID — unique request identifier for tracing
• X-RateLimit-Limit / X-RateLimit-Remaining — rate limit status

# Run backend tests
make test-backend

# Run frontend tests
make test-frontend

# Start dev stack (hot-reloadable frontend + dockerised backend)
make docker-dev
# Then: cd frontend && npm run dev

# Run integration tests (requires running stack)
TAGSHA_API_URL=http://localhost:8080 go test -tags integration ./tests/integration/...

• All user input is validated against strict regex patterns before use
• SSRF is mitigated at the URL parsing layer and at the HTTP client layer (redirect restriction)
• Rate limiting is enforced per IP via Redis sliding window counters
• Secrets are never logged or embedded in binaries
• Docker containers run as non-root with no Linux capabilities
• Container images are scanned by Trivy on every CI run
• Dependency audits run on every pull request

See docs/security.md for the full security model.

• /health — dependency health checks
• /metrics — Prometheus metrics (requests, latency, cache, GitHub rate limit)
• Structured JSON logs with request IDs
• Grafana dashboard provisioned automatically
• Prometheus alert rules included

See docs/deployment.md for Grafana access details.

MIT