detached 993fa25

#26 docs(releases): GoReleaser URLs from GITHUB_API_URL in CI

state
merged · 993fa25 · fast-forward
branch
docs/ci-release-urls → main
opened
bnema ·
updated

Document how to publish releases from CI with GoReleaser.

In a job, the public forge URL may be unreachable (sandboxes block private/CGNAT ranges; the runner relays the forge under another origin such as http://ermite:7341). GITHUB_API_URL and GITHUB_SERVER_URL carry the reachable address. action-gh-release uses them; GoReleaser needs its github_urls templated from them.

  • docs/releases.md: templated github_urls, explanation, full workflow, ermite workflow enable.
  • skills/ermite/SKILL.md: new 'Releases from CI' section.

Verified on hexcheck (run 175): GoReleaser v2.18.3 published 6 archives + checksums.

CommitSubjectAuthorDateSignatureStatus
993fa25docs(releases): template GoReleaser URLs from the runner-provided GITHUB_API_URL and GITHUB_SERVER_URLbriceGPG Verified

Checks 0

no checks

2 files · +57 -5
Split
UnifiedSplit
no checks
⋯

Merge settings

modes
fast-forward, squash, merge commit
checks
failing or unfinished checks block the merge
M docs/releases.md +44 -5
@@ -57,21 +57,60 @@ the S3 endpoint. Stored-token publishers need `release:write` and, for private
5757 repository reads, `repo:read`. The owner component is `ERMITE_OWNER` (`owner` by
5858 default).
5959
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):
6162
6263 ```yaml
6364 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.
6467 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" }}/'
6871 release:
6972 github:
7073 owner: owner
7174 name: app
7275 ```
7376
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`.
75114
76115 On an ermite runner, the job supplies `GITHUB_API_URL`, `GITHUB_SERVER_URL` and
77116 `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` by57 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 ```yaml63 ```yaml
63 version: 264 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: owner73 owner: owner
71 name: app74 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` and115 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 \
8585 - Owner web access: `ermite web login` prints a one-time link (about 60 s, 12 h session).
8686 - If a page or a read looks wrong, set `ERMITE_GIT_READER=cli` and restart: every read then uses the `git` binary.
8787
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+
88101 ## Output conventions
89102
90103 `--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 conventions101 ## 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.

Comments0 open / 0

no comments yet.

Keyboard shortcuts

Single-key shortcuts are on. ctrl k and esc work whatever this says.

ctrl k :
go to a section, branch, tag, file or repository
?
this list
j k
move the row cursor down / up
enter
open the row under the cursor; on Files, a directory opens or closes in place
↑ ↓ ← → home end
in the file tree (focus on a row): previous / next row, close / open a directory or go to its parent / first entry, first / last row. They never open a file
l h
on Files: open a directory or a file / close a directory or go up to its parent, then to the parent page. Elsewhere: into the side panel (on a merge request, its files) / back to the content; there j k move between its controls
g g G
first / last row
/
filter the list; on Files, find a file anywhere in the repository (esc clears, enter opens the best match)
b
switch branch or tag
g s g f g c g b g m g i g r g a
tabs: summary, files, commits, branches & tags, merge requests, issues, releases, actions (when available)
g h
home
w
wide mode: use the whole width of the screen, or not (remembered)
y
copy a permalink pinned to the commit
d u x
diff: split / unified / collapse or expand all
e E
diff: the whole file in view / every file, with the lines the hunks hide
n
merge request: next note in the diff
l
merge request: the list of files (j k move, enter opens, esc back)
M
merge request: the merge menu; there 1–3 pick the mode, D deletes the branch, enter merges
R
merge request: mark the head read
esc
close a dialog, leave a field

Branches 2

Tags 42

↑↓ moveenter openesc close