# forge: GitHub and GHCR reads, brokered

> Forge reads on this service's own keys: any public read of GitHub's REST API under `/github`, answered as GitHub answers it, with paging kept on this host and answers stored; the GitHub Container Registry's tags, manifests and files by title under `/ghcr`. GitLab, Codeberg and Repology answer 503 until their legs land.

## Quick card

First call:

```bash
curl -qfsS https://forge.web.pkgforge.dev/github/repos/pkgforge/soar
```

Then `GET /ghcr/{path}`, every tag:

```bash
curl -qfsS "https://forge.web.pkgforge.dev/ghcr/pkgforge/bincache/busybox/glibc/head?tags"
```

Then `GET /gitlab/{path}`, the gitlab leg, not built yet:

```bash
curl -qsS "https://forge.web.pkgforge.dev/gitlab/api/v4/projects/gitlab-org%2Fcli/releases?per_page=1"
```

Failures, by status and `reason`:

- 429 `held`: retry after `Retry-After`
- 400 `bad-request`, `provider-refused`: no retry: fix the request
- 400 `own-account`: no retry unchanged
- 502 `upstream-failed`: retry with backoff
- 502 `providers-failed`: retry only when `retryable` is true

Any request route can also answer 503 `disabled` or 429 `rate-limited`: retry after `Retry-After`.

Headers:

- `x-web-provider`: who answered: `github`, `github-keyless`, or `ghcr`
- `x-web-account`: the label of the account that answered, a short name this service …
- `x-web-cache`: `hit`: a stored answer, no upstream asked

Host: `forge.web.pkgforge.dev`. State: built.

Version: `054b78b68382`, openapi.json's `info.version`, the first 12 hex digits of the SHA-256 of the four root documents (llms.txt, llms-full.txt, openapi.json, SKILL.md, in that order, joined by a newline), each rendered with an empty version; it changes whenever anything a caller reads in them changes.

Cost: free to every caller; no key, no account and no quota (never gated). The one exception is the operator's: a service can be switched off (503, reason `disabled`), and a spend breaker can cap each caller IP at 100 requests per 60 s, and at 10 per 60 s of those that spend Workers AI or Browser Run, for at most 12 hours (429, reason `rate-limited`).

CORS: every answer carries `access-control-allow-origin: *` and exposes the provenance headers; OPTIONS on a listed path is the preflight (204), and it allows every request header the browser names; no credentials.

Every service and its live status: https://web.pkgforge.dev/

When to use:

- read GitHub's REST API without a token or a rate limit of your own: `GET /github/<path>`, e.g. `/github/repos/<owner>/<repo>/releases/latest`
- a GHCR package's tags, its latest tag, a manifest, or one file by its title: `GET /ghcr/<repository path>?tags`, `?tag`, `?manifest`, `?download=<title>`
- page a GitHub list by its `Link` header: each URL names this host
- not for a page or a file anywhere else: use fetch.web.pkgforge.dev for any URL, and read.web.pkgforge.dev for a page's text

## Routes

- [GET /healthz](https://forge.web.pkgforge.dev/openapi.json#/paths/~1healthz/get): service state and the running Worker version
- [GET /](https://forge.web.pkgforge.dev/openapi.json#/paths/~1/get): the index of this service
- [GET /github/{path}](https://forge.web.pkgforge.dev/openapi.json#/paths/~1github~1%7Bpath%7D/get): any public read of GitHub's REST API
- [GET /ghcr/{path}](https://forge.web.pkgforge.dev/openapi.json#/paths/~1ghcr~1%7Bpath%7D/get): GHCR tags, manifests and files by title
- [GET /gitlab/{path}](https://forge.web.pkgforge.dev/openapi.json#/paths/~1gitlab~1%7Bpath%7D/get): GitLab (gitlab.com): not built yet
- [GET /codeberg/{path}](https://forge.web.pkgforge.dev/openapi.json#/paths/~1codeberg~1%7Bpath%7D/get): Codeberg (codeberg.org): not built yet
- [GET /repology/{path}](https://forge.web.pkgforge.dev/openapi.json#/paths/~1repology~1%7Bpath%7D/get): Repology (repology.org): not built yet
- [GET /llms.txt](https://forge.web.pkgforge.dev/llms.txt): llmstxt.org index of this service
- [GET /llms-full.txt](https://forge.web.pkgforge.dev/llms-full.txt): the guide: each route with its common parameters and a call, the headers that matter and the failures
- [GET /openapi.json](https://forge.web.pkgforge.dev/openapi.json): OpenAPI 3.1 for every route
- [GET /SKILL.md](https://forge.web.pkgforge.dev/SKILL.md): one file an agent reads to use this service

## Docs

- [llms-full.txt](https://forge.web.pkgforge.dev/llms-full.txt): the guide: each route with its common parameters and examples, the headers that matter, the failures and the pipeline contract
- [openapi.json](https://forge.web.pkgforge.dev/openapi.json): OpenAPI 3.1, the whole reference: every parameter, header, enum, schema and response
- [SKILL.md](https://forge.web.pkgforge.dev/SKILL.md): one file an agent reads to use this service