Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions docs/UPDATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,31 @@ Installer scripts download the matching release asset for the local platform and
verify its `.sha256` file. If Zero is already installed, run `zero upgrade`
instead of reinstalling.

## Authentication

Unauthenticated GitHub API requests are subject to strict
[rate limits](https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api).
If you see `403 Forbidden` during update checks, set a GitHub personal access token:

| Environment variable | Role |
|---|---|
| `ZERO_GITHUB_TOKEN` | Used for update checks (takes precedence) |
| `GITHUB_TOKEN` | Fallback when `ZERO_GITHUB_TOKEN` is empty after trimming |

Surrounding whitespace is removed from both token values before use.

Note: `GITHUB_TOKEN` is also used by the GitHub Models provider
(the `github` descriptor in `internal/providercatalog/catalog.go`); both
recipients are GitHub so no trust boundary is crossed, but a token set for
the provider will also be sent on update checks.

Tokens are only sent to HTTPS URLs with the hostname `api.github.com`, including
URLs selected through `--endpoint` or `ZERO_UPDATE_RELEASE_URL`. Other hosts
and plain HTTP URLs never receive credentials. Redirects that downgrade to
`http` after a token-eligible GitHub API request are refused, so the bearer
token is never sent in cleartext (Go's standard library would otherwise copy
`Authorization` on same-host redirects based on host alone).

## Windows recovery state (standalone installs)

This section describes Windows only. On Linux and macOS a standalone update
Expand Down
6 changes: 5 additions & 1 deletion internal/cli/app_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -1596,11 +1596,15 @@ func TestRunUpdateHelpDocumentsCheckFlag(t *testing.T) {
if exitCode != exitSuccess {
t.Fatalf("expected exit code %d, got %d: %s", exitSuccess, exitCode, stderr.String())
}
for _, want := range []string{"--check", "--repo", "--endpoint", "--timeout", "--target"} {
for _, want := range []string{"--check", "--repo", "--endpoint", "--timeout", "--target", "ZERO_GITHUB_TOKEN", "ZERO_UPDATE_RELEASE_URL"} {
if !strings.Contains(stdout.String(), want) {
t.Fatalf("expected update help to document %s, got %q", want, stdout.String())
}
}
// The fallback entry must have its own line, apart from the precedence prose.
if !strings.Contains(stdout.String(), "\n GITHUB_TOKEN ") {
t.Fatalf("expected update help to document a standalone GITHUB_TOKEN entry, got %q", stdout.String())
}
if stderr.Len() != 0 {
t.Fatalf("expected empty stderr, got %q", stderr.String())
}
Expand Down
7 changes: 7 additions & 0 deletions internal/cli/update.go
Original file line number Diff line number Diff line change
Expand Up @@ -207,6 +207,13 @@ Flags:
--timeout <duration> Release check timeout (default 5s)
--target <platform> Release target to verify with --check (for example windows-x64); not valid with --apply
-h, --help Show this help

Environment:
ZERO_GITHUB_TOKEN Token for update checks (takes precedence over GITHUB_TOKEN)
Only sent to HTTPS URLs on api.github.com, including endpoint overrides;
never sent to other hosts or plain HTTP
GITHUB_TOKEN Fallback token when ZERO_GITHUB_TOKEN is empty after trimming
ZERO_UPDATE_RELEASE_URL Override the release API URL (same as --endpoint)
`)
return err
}
Loading
Loading