Pipeline API

What this is for

One narrow, machine-to-machine surface: a build pipeline telling the platform that a CLI release exists. It is how shortspan upgrade learns there is something to upgrade to, and how a defective release can be withdrawn.

It lives at /api/pipeline/v1, in its own route file and its own middleware group, with its own credential. It is neither a customer token nor an admin session, and it can never inherit either.

Authentication

text

Authorization: Bearer <SHORTSPAN_RELEASE_TOKEN>

bash

php artisan cli:release-token

Generates a token. Set it as SHORTSPAN_RELEASE_TOKEN in the application environment and as a secret in your pipeline.

Endpoints

Method	Path	Does
`GET`	`/api/pipeline/v1/ping`	Verify the token and reachability before a release attempts to publish.
`POST`	`/api/pipeline/v1/cli/releases`	Publish a release: version, notes, status, and per-platform artifacts with checksums.

POST /api/pipeline/v1/cli/releases

{
  "version": "1.4.2",
  "status": "current",
  "release_notes": "Fixes credential zeroing on Windows.",
  "release_url": "https://github.com/shortspan/cli/releases/tag/cli/v1.4.2",
  "artifacts": [
    {
      "os": "darwin",
      "arch": "arm64",
      "url": "https://github.com/.../shortspan_darwin_arm64.tar.gz",
      "checksum": "e3b0c44298fc1c149afbf4c8996fb924…",
      "size": 8412160
    }
  ]
}

Status	Meaning for clients
`current`	The upgrade target. `shortspan upgrade` installs this.
`supported`	Works, but is not offered as an upgrade. Pre-releases publish as this.
`beta`	Available to opt-in testers only.
`blocked`	Withdrawn. Every request from this version is refused with `403 CLI_VERSION_BLOCKED`.

Artifact host allowlist

A download URL must be on a host the application allows, configured by SHORTSPAN_ARTIFACT_HOSTS and defaulting to github.com,objects.githubusercontent.com.

The CLI verifies a SHA-256 checksum before replacing its own binary, but a checksum only proves the bytes match what the manifest claims. Restricting the origin is what stops a compromised manifest pointing a self-updating binary at an arbitrary server.

The release workflow

1

Tag a release

Push a tag matching cli/v*.

bash

git tag cli/v1.4.2 && git push origin cli/v1.4.2

2
The workflow builds it
GoReleaser cross-compiles from cli/, injects version, commit, and date via ldflags, and opens a draft GitHub release with checksums.
3
The publish step reports it
A script turns GoReleaser's artifact manifest and checksums into one POST to this endpoint. It needs the repository variable SHORTSPAN_API_URL and the secret SHORTSPAN_RELEASE_TOKEN; without the variable the step is skipped rather than failing the build.
4
Clients see it
The next shortspan upgrade --check - or the once-a-day background check - reports the new version.

Pre-release tags publish as supported/beta so they never become the upgrade target by accident.

Releases and their download counts are visible in the platform control plane, and the workflow lives in the CLI repository.