docs(releases): template GoReleaser URLs from the runner-provided GITHUB_API_URL and GITHUB_SERVER_URL

commit: 993fa25853254a30231614da8a874281357ce9a0
author: brice · 12h ago · 2026-10-22 00:45 UTC
parent: 53e25a3
signature: GPG VerifiedCD88F9E564E0102646FB6077A1A07C7C7C3E349D · arch-gpg Verified for the committer email

2 files · +57 -5

M docs/releases.md +44 -5


@@ -57,21 +57,60 @@ the S3 endpoint. Stored-token publishers need `release:write` and, for private
57	57		repository reads, `repo:read`. The owner component is `ERMITE_OWNER` (`owner` by
58	58		default).
59	59
60		-	GoReleaser configuration (replace the host and repository):
	60	+	GoReleaser does not read `GITHUB_API_URL` or `GITHUB_SERVER_URL` by itself, so
	61	+	template `github_urls` from them (replace the fallback host and repository):
61	62
62	63		```yaml
63	64		version: 2
	65	+	# In CI the runner sets GITHUB_API_URL and GITHUB_SERVER_URL to the address the
	66	+	# job can reach; the public URLs are the fallback for a local run.
64	67		github_urls:
65		-	api: https://git.example.org/-/github/api/
66		-	upload: https://git.example.org/-/github/api/uploads/
67		-	download: https://git.example.org/
	68	+	api: '{{ or (index .Env "GITHUB_API_URL") "https://git.example.org/-/github/api" }}/'
	69	+	upload: '{{ or (index .Env "GITHUB_API_URL") "https://git.example.org/-/github/api" }}/uploads/'
	70	+	download: '{{ or (index .Env "GITHUB_SERVER_URL") "https://git.example.org" }}/'
68	71		release:
69	72		github:
70	73		owner: owner
71	74		name: app
72	75		```
73	76
74		-	Run `GITHUB_TOKEN=<token> goreleaser release --clean` from a tagged checkout.
	77	+	In a CI job the runner rewrites the server and API URLs to an origin the job
	78	+	can reach, which may differ from the public URL (for example `http://ermite:7341`
	79	+	with a relayed forge). Sandboxes block private and CGNAT ranges, so a job that
	80	+	targets only the public URL times out (`dial tcp 100.x:443: i/o timeout`). A
	81	+	plain-http relay needs no TLS option. The API base gets `api/v3/` appended by
	82	+	the client; ermite accepts that alias. Locally, run
	83	+	`GITHUB_TOKEN=<token> goreleaser release --clean` from a tagged checkout; the
	84	+	fallbacks apply.
	85	+
	86	+	Workflow:
	87	+
	88	+	```yaml
	89	+	name: release
	90	+	on:
	91	+	push:
	92	+	tags: ['v*']
	93	+	permissions:
	94	+	contents: write
	95	+	jobs:
	96	+	release:
	97	+	runs-on: ubuntu-latest
	98	+	steps:
	99	+	- uses: actions/checkout@v4
	100	+	with:
	101	+	fetch-depth: 0
	102	+	- uses: actions/setup-go@v5
	103	+	with:
	104	+	go-version-file: go.mod
	105	+	- uses: goreleaser/goreleaser-action@v6
	106	+	with:
	107	+	args: release --clean
	108	+	env:
	109	+	GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
	110	+	```
	111	+
	112	+	An existing GitHub workflow must be enabled on ermite:
	113	+	`ermite workflow enable <repo> .github/workflows/release.yml`.
75	114
76	115		On an ermite runner, the job supplies `GITHUB_API_URL`, `GITHUB_SERVER_URL` and
77	116		`GITHUB_TOKEN`; no endpoint override is needed for action-gh-release:


@@ -57,21 +57,60 @@ the S3 endpoint. Stored-token publishers need `release:write` and, for private
57		repository reads, `repo:read`. The owner component is `ERMITE_OWNER` (`owner` by	57		repository reads, `repo:read`. The owner component is `ERMITE_OWNER` (`owner` by
58		default).	58		default).
59			59
60	-	GoReleaser configuration (replace the host and repository):	60	+	GoReleaser does not read `GITHUB_API_URL` or `GITHUB_SERVER_URL` by itself, so
			61	+	template `github_urls` from them (replace the fallback host and repository):
61			62
62		```yaml	63		```yaml
63		version: 2	64		version: 2
			65	+	# In CI the runner sets GITHUB_API_URL and GITHUB_SERVER_URL to the address the
			66	+	# job can reach; the public URLs are the fallback for a local run.
64		github_urls:	67		github_urls:
65	-	api: https://git.example.org/-/github/api/	68	+	api: '{{ or (index .Env "GITHUB_API_URL") "https://git.example.org/-/github/api" }}/'
66	-	upload: https://git.example.org/-/github/api/uploads/	69	+	upload: '{{ or (index .Env "GITHUB_API_URL") "https://git.example.org/-/github/api" }}/uploads/'
67	-	download: https://git.example.org/	70	+	download: '{{ or (index .Env "GITHUB_SERVER_URL") "https://git.example.org" }}/'
68		release:	71		release:
69		github:	72		github:
70		owner: owner	73		owner: owner
71		name: app	74		name: app
72		```	75		```
73			76
74	-	Run `GITHUB_TOKEN=<token> goreleaser release --clean` from a tagged checkout.	77	+	In a CI job the runner rewrites the server and API URLs to an origin the job
			78	+	can reach, which may differ from the public URL (for example `http://ermite:7341`
			79	+	with a relayed forge). Sandboxes block private and CGNAT ranges, so a job that
			80	+	targets only the public URL times out (`dial tcp 100.x:443: i/o timeout`). A
			81	+	plain-http relay needs no TLS option. The API base gets `api/v3/` appended by
			82	+	the client; ermite accepts that alias. Locally, run
			83	+	`GITHUB_TOKEN=<token> goreleaser release --clean` from a tagged checkout; the
			84	+	fallbacks apply.
			85	+
			86	+	Workflow:
			87	+
			88	+	```yaml
			89	+	name: release
			90	+	on:
			91	+	push:
			92	+	tags: ['v*']
			93	+	permissions:
			94	+	contents: write
			95	+	jobs:
			96	+	release:
			97	+	runs-on: ubuntu-latest
			98	+	steps:
			99	+	- uses: actions/checkout@v4
			100	+	with:
			101	+	fetch-depth: 0
			102	+	- uses: actions/setup-go@v5
			103	+	with:
			104	+	go-version-file: go.mod
			105	+	- uses: goreleaser/goreleaser-action@v6
			106	+	with:
			107	+	args: release --clean
			108	+	env:
			109	+	GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
			110	+	```
			111	+
			112	+	An existing GitHub workflow must be enabled on ermite:
			113	+	`ermite workflow enable <repo> .github/workflows/release.yml`.
75			114
76		On an ermite runner, the job supplies `GITHUB_API_URL`, `GITHUB_SERVER_URL` and	115		On an ermite runner, the job supplies `GITHUB_API_URL`, `GITHUB_SERVER_URL` and
77		`GITHUB_TOKEN`; no endpoint override is needed for action-gh-release:	116		`GITHUB_TOKEN`; no endpoint override is needed for action-gh-release:

M skills/ermite/SKILL.md +13 -0


@@ -85,6 +85,19 @@ docker run -d -p 127.0.0.1:7341:7341 -v ermite-data:/data \
85	85		- Owner web access: `ermite web login` prints a one-time link (about 60 s, 12 h session).
86	86		- If a page or a read looks wrong, set `ERMITE_GIT_READER=cli` and restart: every read then uses the `git` binary.
87	87
	88	+	## Releases from CI
	89	+
	90	+	In a CI job, `GITHUB_API_URL` and `GITHUB_SERVER_URL` point at an address the job can reach (not necessarily the public URL). `softprops/action-gh-release` uses them as is. GoReleaser and other tools with hard-coded GitHub URLs must take them from these variables, never the public URL alone (the job times out):
	91	+
	92	+	```yaml
	93	+	github_urls:
	94	+	api: '{{ or (index .Env "GITHUB_API_URL") "https://git.example.org/-/github/api" }}/'
	95	+	upload: '{{ or (index .Env "GITHUB_API_URL") "https://git.example.org/-/github/api" }}/uploads/'
	96	+	download: '{{ or (index .Env "GITHUB_SERVER_URL") "https://git.example.org" }}/'
	97	+	```
	98	+
	99	+	The workflow needs `permissions: contents: write` and `GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}`. Enable an existing one with `ermite workflow enable <repo> .github/workflows/release.yml`. Full example: `docs/releases.md` in the ermite repository.
	100	+
88	101		## Output conventions
89	102
90	103		`--json` prints stable field names, listed in each command's `--help`. Errors are one line on standard error (`ermite: ...`) with exit status 1. `ermite completion bash\|zsh\|fish` completes repository names.


@@ -85,6 +85,19 @@ docker run -d -p 127.0.0.1:7341:7341 -v ermite-data:/data \
85	- Owner web access: `ermite web login` prints a one-time link (about 60 s, 12 h session).	85		- Owner web access: `ermite web login` prints a one-time link (about 60 s, 12 h session).
86	- If a page or a read looks wrong, set `ERMITE_GIT_READER=cli` and restart: every read then uses the `git` binary.	86		- If a page or a read looks wrong, set `ERMITE_GIT_READER=cli` and restart: every read then uses the `git` binary.
87		87
		88	+	## Releases from CI
		89	+
		90	+	In a CI job, `GITHUB_API_URL` and `GITHUB_SERVER_URL` point at an address the job can reach (not necessarily the public URL). `softprops/action-gh-release` uses them as is. GoReleaser and other tools with hard-coded GitHub URLs must take them from these variables, never the public URL alone (the job times out):
		91	+
		92	+	```yaml
		93	+	github_urls:
		94	+	api: '{{ or (index .Env "GITHUB_API_URL") "https://git.example.org/-/github/api" }}/'
		95	+	upload: '{{ or (index .Env "GITHUB_API_URL") "https://git.example.org/-/github/api" }}/uploads/'
		96	+	download: '{{ or (index .Env "GITHUB_SERVER_URL") "https://git.example.org" }}/'
		97	+	```
		98	+
		99	+	The workflow needs `permissions: contents: write` and `GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}`. Enable an existing one with `ermite workflow enable <repo> .github/workflows/release.yml`. Full example: `docs/releases.md` in the ermite repository.
		100	+
88	## Output conventions	101		## Output conventions
89		102
90	`--json` prints stable field names, listed in each command's `--help`. Errors are one line on standard error (`ermite: ...`) with exit status 1. `ermite completion bash\|zsh\|fish` completes repository names.	103		`--json` prints stable field names, listed in each command's `--help`. Errors are one line on standard error (`ermite: ...`) with exit status 1. `ermite completion bash\|zsh\|fish` completes repository names.