CLI Release Artifact URL Contract¶

The bnerd CLI binary is published to the GitLab Generic Package Registry of the cloud/app project. The operator CI (and any other consumer) fetches it via a simple curl without needing a git checkout of the CLI source.

Registry base URL¶

https://git.bnerd.net/api/v4/projects/<PROJECT_ID>/packages/generic/bnerd

Where <PROJECT_ID> is the numeric GitLab project ID of cloud/app/cli (available at Settings → General → Project ID in the GitLab UI).

URL scheme¶

<base>/<channel>/bnerd-linux-amd64        # binary
<base>/<channel>/SHA256SUM                # checksum file

Channels¶

Channel	Trigger	Use case
`edge`	every push to `main`	latest merged CLI; dev/staging operator builds
`ws-v1`	every push to `feature/workspaces-v1`	workspaces release line during active dev
`<tag>`	git tag (e.g. `v0.2.0`)	production; pinned, immutable

Full example URLs¶

# Latest merged binary (rolling, dev/staging):
https://git.bnerd.net/api/v4/projects/<PROJECT_ID>/packages/generic/bnerd/edge/bnerd-linux-amd64

# Workspaces feature branch build (rolling):
https://git.bnerd.net/api/v4/projects/<PROJECT_ID>/packages/generic/bnerd/ws-v1/bnerd-linux-amd64

# Pinned production release:
https://git.bnerd.net/api/v4/projects/<PROJECT_ID>/packages/generic/bnerd/v0.2.0/bnerd-linux-amd64

Authentication¶

The registry requires a token. From CI pipelines use a deploy token with read_package_registry scope:

curl --fail \
     --header "DEPLOY-TOKEN: ${CLI_DEPLOY_TOKEN}" \
     -o bnerd \
     "https://git.bnerd.net/api/v4/projects/<PROJECT_ID>/packages/generic/bnerd/edge/bnerd-linux-amd64"
chmod +x bnerd

Operator CI wiring¶

In the workspace operator's build-cli job, replace the git-clone fallback with a direct curl fetch:

build-cli:
  stage: build
  image: alpine:3.20
  variables:
    CLI_CHANNEL: "ws-v1"          # or "edge" / a pinned tag like "v0.2.0"
    CLI_PROJECT_ID: "<PROJECT_ID>"
  script:
    - apk add --no-cache curl
    - |
      curl --fail \
           --header "DEPLOY-TOKEN: ${CLI_DEPLOY_TOKEN}" \
           -o images/workspace/bnerd \
           "https://git.bnerd.net/api/v4/projects/${CLI_PROJECT_ID}/packages/generic/bnerd/${CLI_CHANNEL}/bnerd-linux-amd64"
      chmod +x images/workspace/bnerd
      ./images/workspace/bnerd version
  artifacts:
    paths:
      - images/workspace/bnerd
    expire_in: 1 hour

Set CLI_DEPLOY_TOKEN as a masked CI variable in the operator project.

Version convention¶

Tags follow semver: v<MAJOR>.<MINOR>.<PATCH> (e.g. v0.2.0). The tag value comes from the VERSION file at the repo root.
Rolling channels (edge, ws-v1) are overwritten on every push — they are not immutable. Always use a pinned tag for production images.
The SHA256SUM file next to each binary contains the git commit SHA on line 1 and the sha256sum output on line 2, for audit/verification.