@arc-e-tect/api-only-publisher 0.14.4 → 0.16.0

package/README.adoc

@@ -6,7 +6,7 @@
 :source-highlighter: rouge
 // The released version of this component: its snippets use it. The release
 // workflow updates it; do not change it by hand.
-:api-only-publisher-version: 0.14.4
+:api-only-publisher-version: 0.16.0
 
 [NOTE]
 .About this documentation
@@ -182,7 +182,7 @@ At a terminal it asks the same shape of question `init` would, offering what is
 Without `--target`, it also fails on a fragment no target reaches, as <<unreferenced,A fragment no target reaches fails the lint §>> describes.
 
 |`targets`
-|List the declared targets, what each one builds, and whether it is published.
+|List the declared targets, what each one builds, whether it is published, and to which channels.
 
 |`closure [--target <t>]...`
 |Show each target's dependency closure: how many files it reaches, and the hash of their content.
@@ -195,7 +195,7 @@ A target whose closure is untouched needs no new version, however much else in t
 |Archive each built, published target with a `manifest.json`, at the version its version file declares.
 
 |`publish [--pre-release <ids>] [--target <t>]... [--channel <c>]... [--out <dir>]`
-|Pack once, then ship those same bytes to every configured channel, or to each `--channel`.
+|Pack each target once, then ship those same bytes to each of its channels, or only to those of them each `--channel` names (<<channel-routing,Which channels a target goes to §>>).
 
 |`split [--out <dir>] [--by kind\|target]`
 |Make the library safe to break into separate repositories.
@@ -641,7 +641,7 @@ Not a distribution mechanism between repositories: it makes the pipeline testabl
 Publishing a version again writes it again and keeps the others (<<idempotent,Publishing the same version again §>>); with `clean: true` only the version being published is kept, for a directory that is a build output rather than a record of releases.
 
 |`maven`
-|A path publishes into a repository layout on disk; an `http(s)` URL deploys to a remote repository with an HTTP `PUT` per file and a bearer token.
+|A path publishes into a repository layout on disk; an `http(s)` URL deploys to a remote repository with an HTTP `PUT` per file, and keeps its `maven-metadata.xml` (<<maven-remote,Publishing to a remote Maven repository §>>).
 Native for Gradle consumers: version resolution, caching and conflict handling come free, which is what lets the Subscriber carry no HTTP client of its own.
 
 |`npm`
@@ -651,11 +651,52 @@ Native for Gradle consumers: version resolution, caching and conflict handling c
 |The language-neutral floor: immutable per tag, works for private repositories with a token, readable by a consumer with no JVM and no Node.js.
 No dependency-resolution semantics and no update notification, which is why it is the fallback rather than the default.
 
+|`gitlab-package`
+|A GitLab project's Generic Package Registry: the archive and `manifest.json` as a generic package per target, on gitlab.com or a self-managed GitLab.
+In a GitLab CI job it needs no settings at all. See <<gitlab-package,The `gitlab-package` channel §>>.
+
 |`nuget`
 |A path writes a `.nupkg` into a local feed; an `http(s)` URL -- the feed's service index -- pushes to a remote one.
 Native for .NET consumers: a `PackageReference` at a version, restored from a feed. See <<nuget,The `nuget` channel §>>.
 |===
 
+[#channel-routing]
+=== Which channels a target goes to
+
+A channel has a *name*, the key under `channels`, and a *type*, one of those above.
+A channel named after a type is that type; any other name -- lowercase words joined by single hyphens, such as `partner-a` -- says its type with `type`.
+So one `apionly.yaml` can hold several channels of one type, each with its own destination, settings and token:
+
+[source,yaml]
+----
+channels:
+  maven:                                # a Maven channel, named after its type
+    groupId: com.example.api
+    repository: https://maven.example.com/internal
+  partner-a:                            # another one, for one partner
+    type: maven
+    groupId: com.example.partner
+    repository: https://maven.partner-a.example
+    tokenEnv: PARTNER_A_TOKEN
+
+targets:
+  orders:
+    channels: [maven, partner-a]        # published to these two
+    openapi:
+      bundle: bundles/orders_openapi_structure.yaml
+  billing:                              # no list: every configured channel
+    openapi:
+      bundle: bundles/billing_openapi_structure.yaml
+----
+
+* A target with a `channels` list is published to those channels; a target without one, to every configured channel.
+* Everything is checked when `apionly.yaml` is read: a channel name that is not kebab-case, a name that is not a type without a `type`, a `type` that is not one, a type name given another `type`, and a target that lists a channel `apionly.yaml` does not configure, lists one twice, lists none (`channels: []`, where `publish: false` is meant), or is never published -- `publish: false`, or an aggregate.
+* `--channel` narrows each target to the named channels it is routed to.
+A target that is not routed to one is skipped, and `publish` says so: `payments: not published to npm (not in targets.payments.channels)`.
+A run that would publish nothing at all fails instead of succeeding quietly.
+* A `--channel` that `apionly.yaml` does not configure is refused, unless it is a type's name: `--channel github-release` is that channel with no settings, as it has always been.
+* `targets` lists each published target with its channels.
+
 [#idempotent]
 === Publishing the same version again
 
@@ -674,13 +715,46 @@ What happens when the destination already has the version:
 |`file`; `maven` and `nuget` to a directory; `npm` with `publish: false`
 |Written again. With the same content the bytes are the same; with different content the version is replaced, and every subscriber whose lockfile recorded the old bytes fails its build until the change is published as a new version.
 
-|`maven` and `nuget` to a URL, `npm`, `github-release`
+|`maven` and `nuget` to a URL, `npm`, `github-release`, `gitlab-package`
 |The same bytes: nothing is sent, and the log says `already published, identical`. Different bytes: `publish` fails, naming the version -- a published version is never replaced, so publish the change as a new version.
+`maven` and `gitlab-package` read back every file before uploading any, so a run interrupted half-way is completed by the next one; a GitLab registry that allows duplicate packages, as it does by default, would otherwise replace a version.
 `github-release` compares the asset it would upload with the one the release has, and never overwrites one.
 `npm` compares the integrity hash the registry records, or the tarball's SHA-1 where it records only that, as GitLab's does; its files are packed with fixed modes, so the package is the same bytes whatever the umask of the machine that publishes it.
 A NuGet feed that cannot return the package it has, so there is nothing to compare, fails as a different one would.
 |===
 
+[#remote-switch]
+=== Refusing remote publishing
+
+A channel's *local mode* writes files: `file`, `maven` and `nuget` to a directory, `npm` with `publish: false`.
+Its *remote mode* sends them somewhere: `maven` and `nuget` to a URL, `npm` with publishing, `github-release`, `gitlab-package`.
+
+`API_ONLY_PUBLISHER_REMOTE` decides whether `publish` may use a remote mode:
+
+[cols="1,3", options="header"]
+|===
+| Value | Effect
+
+| `allow`, or unset
+| Every channel works. The default outside the Docker image.
+
+| `never`
+| `publish` refuses a run that would use any remote channel, naming each of them, before it reads a version or packs anything; the local modes work as always.
+The Publisher then contacts nothing. The default in the Docker image (<<docker-network,Nothing phones home §>>).
+|===
+
+[source,text]
+----
+Error: API_ONLY_PUBLISHER_REMOTE=never refuses the remote channels maven, github-release, so nothing was built, packed or sent. Publish with their local modes, or set API_ONLY_PUBLISHER_REMOTE=allow where this run may contact them.
+----
+
+Any other value fails `publish`, whatever its channels: a typo in a switch that keeps the Publisher sealed is not ignored.
+Only the channels a run would publish to are checked, by type: a channel named `partner-a` with `type: maven` and a URL is remote; `publish --channel file`, or a target routed only to local channels, succeeds under `never`, whatever else `apionly.yaml` configures.
+The Publisher used as a library keeps the same rule.
+
+The switch is a promise the Publisher keeps, not an enforcement: whoever runs it can change the variable.
+Where contacting nothing must be guaranteed, isolate the job's network on the platform as well -- `docker run --network none`, or a network policy for the runner.
+
 [#handoff]
 === The hand-off: what a `publish` run wrote
 
@@ -691,7 +765,7 @@ Every `publish` run lists each file its channels wrote locally, with its SHA-256
 | File | Content
 
 | `packages.json`
-| `schemaVersion`, and `files`: for each file, its `path`, `sha256`, `target`, `version` and `channel`.
+| `schemaVersion`, and `files`: for each file, its `path`, `sha256`, `target`, `version`, `channel` -- the channel's name -- and `type`, the channel's type.
 
 | `packages.sha256`
 | The same files in the format `sha256sum -c` checks.
@@ -706,15 +780,15 @@ The hand-off is for a later step that publishes those files itself -- the second
 [#channel-text]
 === What a package says about itself
 
-The Maven POM, the npm `package.json`, the NuGet `.nuspec` and a GitHub release all describe the contract.
+The Maven POM, the npm `package.json`, the NuGet `.nuspec`, a GitHub release and a GitLab release all describe the contract.
 By default each says `API description documents for <target>.`, and a GitHub release is titled `<target> <version>`.
-`channels.<channel>.description` replaces the description, and `channels.github-release.title` and `notes` the release's title and notes (notes default to the description); `{target}` and `{version}` are filled in, as in `tagFormat`.
+`channels.<channel>.description` replaces the description, and `title` and `notes` on `channels.github-release` and `channels.gitlab-package` the release's title and notes (notes default to the description); `{target}` and `{version}` are filled in, as in `tagFormat`.
 
 npm publishes a release under the dist-tag `latest` and a pre-release under `next`.
 `channels.npm.releaseTag` and `prereleaseTag` name others: publishing a patch to an older line under `releaseTag: v1` keeps `latest` on the newest line, which publishing it under `latest` would move back.
 
 Credentials are read from the environment, never from configuration.
-`channels.maven.tokenEnv` names the variable, `MAVEN_TOKEN` by default, and `channels.nuget.tokenEnv` the NuGet API key's, `NUGET_API_KEY` by default; a configuration file gets committed, and a credential in a committed file is a credential that has leaked.
+`channels.maven.tokenEnv` names the variable, `MAVEN_TOKEN` by default, `channels.nuget.tokenEnv` the NuGet API key's, `NUGET_API_KEY` by default, and `channels.gitlab-package.tokenEnv` the GitLab token's, `GITLAB_TOKEN` by default, with `CI_JOB_TOKEN` when that is unset; a configuration file gets committed, and a credential in a committed file is a credential that has leaked.
 
 link:../docs/reference/how-publisher-and-subscriber-work-together.adoc#channels[How the Publisher and the Subscriber work together →] lists each channel's layout and options.
 
@@ -784,6 +858,88 @@ Until a `.targets` file places and verifies the documents for a .NET build, a co
 The same packed archive always produces a byte-identical package: entries in a fixed order, a fixed timestamp.
 Since `pack` is reproducible, publishing the same commit again produces the same package too, so a republish to a local feed can be checked as unchanged.
 
+[#gitlab-package]
+=== The `gitlab-package` channel
+
+It publishes each target to a GitLab project's Generic Package Registry, on gitlab.com or a self-managed GitLab, without any GitLab tooling: a package is a few HTTP requests the Publisher sends itself.
+
+[source,yaml]
+----
+channels:
+  gitlab-package:                          # in a GitLab CI job, nothing below is needed
+    # url: https://gitlab.example.com/api/v4  # default: $CI_API_V4_URL, else https://gitlab.com/api/v4
+    # project: group/subgroup/api-library     # an ID or a path; default: $CI_PROJECT_ID
+    # tokenEnv: GITLAB_TOKEN                  # default; when unset, $CI_JOB_TOKEN is used
+    # tokenType: private                      # private (default), deploy or job
+    # packageName: "{target}"                 # default
+    # release: false                          # true: also the tag's GitLab release
+    # tagFormat: "{target}-v{version}"        # for release: true
+    # title, notes, description               # as for github-release
+----
+
+*The package* is named after the target, at the contract's version, and holds two files: `<target>-<version>.tgz` and `manifest.json`, the ones the `file` channel writes.
+A consumer downloads them from `<url>/projects/<project>/packages/generic/<target>/<version>/<file>`, or from the project's *Deploy › Package registry* page.
+
+*In a GitLab CI job* the channel needs no settings: the API URL, the project and the job's token come from GitLab's predefined variables `CI_API_V4_URL`, `CI_PROJECT_ID` and `CI_JOB_TOKEN`.
+link:pipelines/gitlab-ci.yml[The reference pipeline →] publishes this way, from the Docker image, in one job (<<docker-gitlab,Reference pipeline: GitLab CI §>>).
+
+*The credential* is the first of these the environment holds:
+
+[cols="2,2,3", options="header"]
+|===
+| Variable | Sent as | For
+
+| The one `tokenEnv` names, `GITLAB_TOKEN` by default
+| `PRIVATE-TOKEN`; with `tokenType: deploy`, `DEPLOY-TOKEN`; with `tokenType: job`, `JOB-TOKEN`
+| A personal or project access token with the `api` scope, or a deploy token with `write_package_registry` (and `read_package_registry`, for the read-back).
+
+| `CI_JOB_TOKEN`
+| `JOB-TOKEN`
+| A GitLab CI job publishing to its own project.
+|===
+
+Without either, `publish` fails before anything is sent, naming both.
+A deploy token is the least privilege for packages alone: it reaches one project's package registry and nothing else.
+
+*The same version again.*
+GitLab allows duplicate packages by default: it accepts a different file under a version it already has, and serves that one from then on.
+So the channel reads every file back before uploading any: an identical file is left alone, a missing one is uploaded, and a different one fails `publish` (<<idempotent,Publishing the same version again §>>).
+Turning *Allow duplicates* off for generic packages, in the group's *Settings › Packages and registries*, makes GitLab refuse a replaced file too, from every client; the Publisher keeps a version immutable either way.
+
+*`release: true`* also creates the tag's GitLab release, tagging `$CI_COMMIT_SHA` or, outside CI, the checkout's `HEAD`, and links both files as packages.
+An existing release keeps everything it has, and only gets the links it lacks.
+A pre-release publishes the package and no release: GitLab has no pre-release flag, so the release would become the project's latest.
+A deploy token cannot create a release -- GitLab gives it the package registry only -- so `release: true` with `tokenType: deploy` is refused before anything is sent.
+
+link:../docs/guides/publishing-to-gitlab/overview.adoc[Publishing to GitLab →] covers the rest: job-token permissions, self-managed instances and their certificates, and how consumers read the packages.
+
+[#maven-remote]
+=== Publishing to a remote Maven repository
+
+An `http(s)` `repository` deploys with an HTTP `PUT` per file: the artifact, its POM, and `-manifest.json`.
+
+[source,yaml]
+----
+channels:
+  maven:
+    groupId: com.example.api
+    repository: https://gitlab.example.com/api/v4/projects/1234/packages/maven
+    tokenEnv: CI_JOB_TOKEN    # default: MAVEN_TOKEN
+    tokenHeader: Job-Token    # default: Authorization, as a bearer token
+    # metadata: false         # leave maven-metadata.xml to a repository that generates it
+----
+
+*The token* goes as a bearer token, `Authorization: Bearer <token>`, unless `tokenHeader` names another header, which then carries it as it is.
+GitLab's Maven registry takes a job token as `Job-Token`, a personal or project access token as `Private-Token`, and a deploy token as `Deploy-Token`; a GitLab Maven repository URL needs the project's numeric ID, since Gradle reads `%2F` in a path as `/`.
+
+*Every file is read back* before any is uploaded: identical is left alone, missing is uploaded, different fails `publish`, naming the file.
+
+*`maven-metadata.xml`* lists an artifact's versions, which is how Gradle resolves a version range and how Renovate and Dependabot see a new version.
+Nexus, Artifactory and GitHub Packages keep it themselves; GitLab does not for files uploaded this way.
+So after a version's files, the channel adds the version to it, as `mvn deploy` does: `latest` is the highest version, `release` the highest that is not a pre-release, and `lastUpdated` the time of the commit, so the same commit writes the same file.
+It is written only when it lacks the version, or its `latest` or `release` would change.
+A repository that refuses it fails `publish`, naming `metadata: false`; the version's files are published by then, and a re-run retries only the metadata.
+
 [#why-registries]
 === Why npm, Maven and NuGet rather than release assets alone
 
@@ -871,6 +1027,7 @@ channels:
 
 targets:
   orders:
+    # channels: [file]   # the channels it is published to; default: every one
     # versionFile: versions/orders.properties
     #              default: orders.bundle.properties beside the first bundle root
     openapi:
@@ -999,7 +1156,7 @@ Two questions decide how a library is configured:
 * *How many targets?*
 A target is one contract with a version of its own and consumers of its own: what gets shipped.
 * *How many channels?*
-A channel is one way of shipping it -- `file`, `maven`, `npm`, `nuget` or `github-release` -- chosen to suit the technology of whoever consumes it: how it reaches them.
+A channel is one way of shipping it -- `file`, `maven`, `npm`, `nuget`, `github-release` or `gitlab-package` -- chosen to suit the technology of whoever consumes it: how it reaches them.
 
 Each recipe below answers both, for a situation in which the answer is typical.
 They are starting points, not boundaries: the situations describe where each shape usually turns up, and nothing stops a shape being used elsewhere.
@@ -1042,20 +1199,30 @@ They are starting points, not boundaries: the situations describe where each sha
 [#recipes-two-facts]
 === Two facts every recipe rests on
 
-*A channel is named after its type.*
-`channels.maven` is the Maven channel, `channels.npm` the npm channel, and so on, so one `apionly.yaml` has at most one channel of each type, with one destination each.
-Two consumers who both read Maven get the same Maven repository; <<recipe-business-partners,Business partners §>> shows what to do when they each need their own.
+*A channel has a name and a type.*
+A channel named after a type is that type -- `channels.maven` is a Maven channel -- and any other name says its type with `type`, so one `apionly.yaml` can hold two channels of one type, each with a destination of its own:
 
-*`apionly.yaml` says which channels exist, not which target goes where.*
-Without `--channel`, `publish` ships every published target to every configured channel, packing each target once and sending the same bytes everywhere.
-`--target` and `--channel` narrow a run, and both may be repeated:
+[source,yaml]
+----
+channels:
+  partner-a: { type: maven, groupId: com.example.partner, repository: https://maven.partner-a.example }
+  partner-b: { type: maven, groupId: com.example.partner, repository: https://maven.partner-b.example }
+----
 
-[source,console]
+*`apionly.yaml` says which target goes where.*
+A target with a `channels` list is published to those channels; a target without one is published to every configured channel.
+`publish` packs each target once, and sends the same bytes to each of its channels:
+
+[source,yaml]
 ----
-npm run apionly -- publish --target payments --channel nuget
+targets:
+  payments:
+    channels: [partner-a]
+    openapi:
+      bundle: bundles/payments_openapi_structure.yaml
 ----
 
-So when different targets go to different channels, the routing lives in the commands that run `publish`, as <<recipe-ecosystem,Eco-system §>> shows, and not in `apionly.yaml`.
+`--target` and `--channel` narrow a run, and both may be repeated; `--channel` publishes each target only to the named channels it is routed to, and says which targets it skipped (<<channel-routing,Which channels a target goes to §>>).
 
 The excerpts below show only `channels` and `targets`; the rest of `apionly.yaml` is as <<configuration,Configuration §>> describes, and as `init` writes it.
 Every published target also needs its version file, as <<versions,Versions §>> describes, and a `build` before its `publish`.
@@ -1093,7 +1260,8 @@ This publishes `com.example.contracts:orders:<version>@tgz`, which a build fetch
 *Variations.*
 
 * A library that lives in the same repository as its implementation needs no repository at all: the `file` channel, with `directory: build/publish`, is what `init` writes, and the Subscriber reads it from there.
-* A consumer that is not a JVM build takes a different channel in place of `maven`: `npm` for a Node.js or TypeScript build, `nuget` for .NET, `github-release` for anything else.
+* A consumer that is not a JVM build takes a different channel in place of `maven`: `npm` for a Node.js or TypeScript build, `nuget` for .NET, `github-release` or `gitlab-package` for anything else.
+* A library hosted on GitLab publishes to its own project's registries: `gitlab-package`, which needs no settings in a GitLab CI job, and `maven` to the project's Maven registry with `tokenHeader: Job-Token` (<<gitlab-package,The `gitlab-package` channel §>>).
 
 [#recipe-microservices]
 === Microservice architecture: several targets, one channel
@@ -1189,9 +1357,10 @@ One run publishes `com.example.partner:partner-api`, `@example-partner/partner-a
 * `--channel` publishes to one of them on its own, for instance when one partner's feed was unreachable during the release: `npm run apionly -- publish --channel nuget`.
 The other channels already have the version, and would leave it alone anyway.
 * A pre-release, `publish --pre-release rc.1`, is how a partner gets an unfinished contract to start building against, without any partner's production build picking it up by accident (<<pre-releases,Pre-releases §>>).
-* Each channel takes its credential from the environment, never from `apionly.yaml`: `MAVEN_TOKEN` and `NUGET_API_KEY` by default, npm's own configuration for `npm`, and the GitHub CLI's for `github-release` (<<channel-text,What a package says about itself §>>).
-* Partners that each need a repository of *the same type* -- two Maven repositories, one per partner -- cannot be two `maven` channels.
-Publish to a local destination instead, `repository` or `directory` set to a directory, and let the pipeline copy the files it lists in `packages.sha256` to each partner's repository, as <<handoff,The hand-off §>> describes.
+* Each channel takes its credential from the environment, never from `apionly.yaml`: `MAVEN_TOKEN`, `NUGET_API_KEY` and `GITLAB_TOKEN` by default, npm's own configuration for `npm`, and the GitHub CLI's for `github-release` (<<channel-text,What a package says about itself §>>).
+* A partner without a package manager gets a download: `github-release` where the library is on GitHub, `gitlab-package` where it is on GitLab.
+* Partners that each need a repository of *the same type* -- two Maven repositories, one per partner -- are two channels with names of their own and `type: maven`, as <<recipes-two-facts,the two facts §>> show.
+* A partner that may see only some contracts gets only those: list its channel on those targets (<<recipe-ecosystem,Eco-system §>>).
 
 [#recipe-platform]
 === Platform: several targets, several channels, every target on every channel
@@ -1270,7 +1439,7 @@ Start from a routing table: which target goes to which channel.
 |`payments` |Yes |    |Yes
 |===
 
-`apionly.yaml` declares the channels and the targets, as for a <<recipe-platform,platform §>>:
+The routing table goes into `apionly.yaml` as it stands: each target lists the channels it is published to.
 
 .apionly.yaml (excerpt)
 [source,yaml]
@@ -1288,52 +1457,39 @@ channels:
 
 targets:
   catalog:
+    channels: [maven, npm]
     openapi:
       bundle: bundles/catalog_openapi_structure.yaml
   customers:
+    channels: [maven]
     openapi:
       bundle: bundles/customers_openapi_structure.yaml
   orders:
+    channels: [maven, npm]
     openapi:
       bundle: bundles/orders_openapi_structure.yaml
   payments:
+    channels: [maven, nuget]
     openapi:
       bundle: bundles/payments_openapi_structure.yaml
 ----
 
-The routing table becomes one `publish` per channel, each naming its targets.
-Keeping those commands as scripts in the library's `package.json` keeps the routing in one place, reviewed with the library, rather than spread across pipeline files:
-
-.package.json (excerpt)
-[source,json]
-----
-{
-  "scripts": {
-    "apionly": "api-only-publisher",
-    "publish:maven": "api-only-publisher publish --channel maven",
-    "publish:npm": "api-only-publisher publish --channel npm --target catalog --target orders",
-    "publish:nuget": "api-only-publisher publish --channel nuget --target payments",
-    "publish:all": "npm run publish:maven && npm run publish:npm && npm run publish:nuget"
-  }
-}
-----
-
 [source,console]
 ----
 npm run apionly -- build
-npm run publish:all
+npm run apionly -- publish
 ----
 
-`publish:maven` names no target, because every target goes there; a channel that takes only some names each of them.
+One `publish` sends each target to its own channels, packing it once.
+`npm run apionly -- targets` lists each target with its channels, so the routing can be read back.
 
 *Worth knowing.*
 
-* A new target goes only where a script sends it.
-`publish:maven` picks it up because it names no target; the npm and NuGet consumers do not see it until it is added to their script, which is the deliberate step an eco-system wants.
-* Each script passes its arguments on: `npm run publish:npm -- --pre-release rc.1` publishes a pre-release of the npm targets alone.
-* Each run packs again, and the archives are the same bytes every time (<<idempotent,Publishing the same version again §>>), so a target on two channels is identical on both.
-* Each run replaces the hand-off files in the packages directory (<<handoff,The hand-off §>>).
-A pipeline that publishes the files itself gives each run its own `--out`, such as `--out build/packages/npm`, and keeps every channel's list.
+* A target without a `channels` list goes to every configured channel.
+In an eco-system, give every target a list: a new target then goes nowhere until someone decides where, which is the deliberate step an eco-system wants.
+* `--channel` publishes to one channel alone, say after its registry was unreachable: `npm run apionly -- publish --channel npm` sends `catalog` and `orders`, says that it skipped `customers` and `payments`, and fails if it would publish nothing at all.
+* The routing is checked when `apionly.yaml` is read: a target that lists a channel `apionly.yaml` does not configure is refused, naming both, before anything is built.
+* A third party that needs a registry of a type another party already uses -- a second Maven repository -- gets a channel of its own, with `type: maven` (<<recipes-two-facts,the two facts §>>).
 
 [#behaviour]
 == Behaviour worth knowing about
@@ -1539,13 +1695,45 @@ The Publisher is also a Docker image, for CI pipelines that may run only what ha
 |===
 
 Vetting the npm package does not vet what it runs: it fetches Redocly CLI and AsyncAPI CLI with `npx` when it runs.
-The image is one artefact, with one digest, holding one Publisher version *and* its toolchain, and it is *sealed*: it downloads nothing, and contacts nothing, when it runs.
+The image is one artefact, with one digest, holding one Publisher version *and* its toolchain, and it is *sealed*: it downloads nothing when it runs, and contacts nothing unless a job allows it to publish.
 It can be pulled by digest, its signature verified, its SBOM and provenance read, scanned, and mirrored, and then a pipeline knows exactly what it runs.
 
 Both registries serve the same image, with the same digest: Docker Hub gets a copy of what GHCR was given, never a rebuild.
 
 link:../docs/guides/publishing-from-ci/overview.adoc[Publishing from CI with the image →] is the guide, with prompts that set up the pipeline in your own repository.
 
+Publishing from the image takes one job or two:
+
+[cols="1,2,2", options="header"]
+|===
+| | One job | Two steps
+
+| What runs
+| The image, and nothing else.
+| The image packages; a job per registry publishes with that registry's own client, on an image of its own.
+
+| Credentials and network
+| The publishing job allows the image to contact the registry (`API_ONLY_PUBLISHER_REMOTE: allow`) and hands it the token.
+| The image never holds a credential, and runs with no network.
+
+| Channels
+| `gitlab-package`, and `maven` to a URL: the remote modes the image is tested with.
+| Every channel, in its local mode.
+
+| Reference pipeline
+| <<docker-gitlab,GitLab CI §>>
+| <<docker-github-actions,GitHub Actions §>>, and the <<docker-gitlab,GitLab CI §>> variant
+|===
+
+[#docker-one-job]
+=== One job: the image publishes
+
+The job runs `build`, `lint` and `publish` in the image, with `API_ONLY_PUBLISHER_REMOTE: allow` and the registry's token in its environment.
+Nothing else runs, so the image is the only artefact to vet, mirror and pin; the publishing clients and their images that two steps need are not.
+The image stays sealed in every other job, and the job contacts only the destinations `apionly.yaml` configures.
+
+The remote modes the image is tested with are `gitlab-package` and `maven` to a URL: its smoke test publishes with both, as a non-root user on a read-only root, to a GitLab stand-in on a network with no route out (<<docker-verifying,Running the smoke test §>>).
+
 [#docker-two-steps]
 === Two steps: package in the image, publish with the platform's tools
 
@@ -1556,14 +1744,15 @@ It needs no network and no credential.
 Every `publish` run writes a hand-off, <<handoff,The hand-off §>>, listing each file it wrote with its SHA-256.
 The publishing job checks the files against it, and publishes exactly those bytes: the bytes in the registry are the bytes the vetted tool produced.
 
-Credentials never enter the image.
+In two steps, credentials never enter the image.
 
 [IMPORTANT]
-.What the image does not do yet
+.What the image does not publish itself yet
 ====
-The image does not publish to a remote registry itself.
-The channels' remote modes -- `maven` or `nuget` to a URL, `npm` with publishing, `github-release` -- may work from inside it, but they are neither tested nor supported there.
-Publish in a second step, as <<docker-pipelines>> shows.
+The image refuses every remote mode unless a job sets `API_ONLY_PUBLISHER_REMOTE: allow` (<<remote-switch,Refusing remote publishing §>>).
+Allowed, it supports `gitlab-package` and `maven` to a URL.
+`nuget` to a URL, `npm` with publishing and `github-release` may work from inside it too, but they are neither tested nor supported there yet -- `github-release` needs the GitHub CLI, which the image does not hold.
+Publish those in a second step, as <<docker-pipelines>> shows.
 ====
 
 [#docker-tags]
@@ -1803,6 +1992,10 @@ The image makes no outbound connection: it sets, in its environment, what switch
 
 This is tested, not assumed: the whole smoke test was run on a network whose every packet was captured, and the image sent none.
 
+Nor does `publish` contact anything: the image sets `API_ONLY_PUBLISHER_REMOTE=never`, so a run that would use a remote channel fails before it packs anything, naming the channels (<<remote-switch,Refusing remote publishing §>>).
+A pipeline that publishes from the image sets `API_ONLY_PUBLISHER_REMOTE: allow` on that job: a visible line, reviewed like any other.
+The variable is the Publisher's promise; a pipeline that must be sure the job contacts nothing also runs it without a network, `docker run --network none`.
+
 [#docker-ci-job]
 ==== As a CI job image
 
@@ -1850,19 +2043,24 @@ Each publishing step checks for the version first, compares the bytes, and publi
 [#docker-gitlab]
 ==== Reference pipeline: GitLab CI
 
-[WARNING]
-====
-*Not exercised.*
-This pipeline is validated against GitLab's published CI schema only; no GitLab pipeline has run it yet.
-====
+One job, on a `v*` tag, as the GitHub Actions pipeline: the image builds, lints and publishes the targets to the project's Generic Package Registry with `gitlab-package`, and, where `apionly.yaml` configures it, to the project's Maven registry, both with the job's `CI_JOB_TOKEN`.
+`apionly.yaml` needs no GitLab settings for it; the pipeline's header says what to add for the Maven registry.
+Copy it to `.gitlab-ci.yml`, then set the digest and the targets.
+The tag pattern keeps out the tag a GitLab release puts on the commit, `<target>-v<version>`, which would otherwise start the pipeline a second time; a library that tags its releases otherwise changes the rule, and keeps that one out.
 
-The same two steps: `package` runs in the image, and one `publish:*` job per registry publishes to the project's package registry with `CI_JOB_TOKEN`: npm, Maven and NuGet, and the archives to the generic package registry.
+It has run on gitlab.com: with the job token, it published to the project's generic and Maven registries, created the release, and, run again, found everything published and changed nothing.
+It is validated against GitLab's published CI schema, the image's smoke test publishes as this job does to a GitLab stand-in, and the link:../.github/workflows/api-only-publisher-image-e2e.yml[end-to-end workflow →] publishes the same way to a gitlab.com test project, with a deploy token.
 
 [source,yaml]
 ----
 include::pipelines/gitlab-ci.yml[]
 ----
 
+link:../docs/guides/publishing-to-gitlab/overview.adoc[Publishing to GitLab →] is the guide: tokens, a self-managed GitLab, and what consumers need.
+
+*The two-step variant*, link:pipelines/gitlab-ci-two-step.yml[`pipelines/gitlab-ci-two-step.yml` →], keeps the image sealed: `package` runs in the image, and one `publish:*` job per registry publishes to the project's package registry with that registry's own client and `CI_JOB_TOKEN`: npm, Maven and NuGet, and the archives to the generic package registry.
+It is validated against GitLab's published CI schema only; no GitLab pipeline has run it yet.
+
 [#docker-mirror-in-pipelines]
 ==== Using a mirrored image
 
@@ -1956,12 +2154,14 @@ docker build -t api-only-publisher:local --build-arg VERSION=0.0.0-local .
 docker/smoke-test.sh api-only-publisher:local 0.0.0-local
 ----
 
-It runs every step with no network, a read-only root and your own user: the version, the help, the toolchain labels against what is installed and against `init`'s pins, a library with two targets built, linted and packaged to every local channel in one run, ownership, byte-identical packaging twice, the hand-off, a foreign toolchain pin failing at once, the shell mode, and a build as an arbitrary UID.
+It runs every step with a read-only root and your own user, and all but the last with no network: the version, the help, the toolchain labels against what is installed and against `init`'s pins, a library with two targets built, linted and packaged to every local channel in one run, ownership, byte-identical packaging twice, the hand-off, a foreign toolchain pin failing at once, a remote channel refused while sealed, the shell mode, and a build as an arbitrary UID.
+The last step publishes with `gitlab-package` and `maven` to a GitLab stand-in, run from the same image, on a Docker network it creates with no route out (`docker network create --internal`) and removes afterwards; it checks every request went to the project's package registries with the job token, and that a re-run uploads nothing.
 
 link:../.github/workflows/api-only-publisher-image-e2e.yml[`api-only-publisher-image-e2e.yml` →] runs the GitHub Actions reference pipeline for real, by hand only.
 link:test/docker.test.js[`test/docker.test.js` →] holds it to what the link:pipelines/[reference pipelines →] do, the same actions, commands, inputs and environment, but not to the versions they pin.
 The reference pipelines are examples, maintained on their own, and the end-to-end workflow is maintained with this repository's other workflows, so a new version of an action in one never fails the Publisher's build while the other has not moved.
 Give it an image by digest; it publishes version `0.<run>.<attempt>` of two scratch targets, `apionly-e2e-alpha` and `apionly-e2e-beta`, to npm, Maven and NuGet on GitHub Packages and to a scratch release, publishes again to prove a re-run is safe, resolves each package with its own client and with the Subscriber, and removes what it published.
+Its `gitlab` job publishes the same targets from the image, in one job, to a gitlab.com test project's Generic Package Registry and Maven registry with a deploy token (secret `GITLAB_E2E_DEPLOY_TOKEN`), publishes again, checks GitLab serves the image's bytes and lists the version in `maven-metadata.xml`, and resolves a contract with the Subscriber; a deploy token cannot delete packages, so the run's summary lists the scratch versions to delete by hand.
 The image workflow, dispatched by hand, is the release's dry run: its defaults are the scratch names `ghcr.io/arc-e-tect/api-only-publisher-scratch` and `arcetect/api-only-publisher-scratch`, and it builds from the branch's source.
 
 [#adapting]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arc-e-tect/api-only-publisher",
-  "version": "0.14.4",
+  "version": "0.16.0",
   "description": "Builds, packs and publishes API description documents from a library of reusable fragments.",
   "license": "MIT",
   "author": "Arc-E-Tect",

package/src/channel-types.js

@@ -0,0 +1,13 @@
+"use strict";
+
+// The channel types, in a module of their own so that the configuration can check a
+// channel's type without requiring the channels themselves.
+
+const CHANNEL_TYPES = Object.freeze(["file", "maven", "npm", "github-release", "nuget", "gitlab-package"]);
+
+/** The types as a sentence names them: "file, maven, ... or gitlab-package". */
+function describeTypes() {
+    return `${CHANNEL_TYPES.slice(0, -1).join(", ")} or ${CHANNEL_TYPES[CHANNEL_TYPES.length - 1]}`;
+}
+
+module.exports = { CHANNEL_TYPES, describeTypes };

package/src/channels.js

@@ -12,9 +12,11 @@ const os = require("os");
 const path = require("path");
 const { execFileSync } = require("child_process");
 
-const { isPrerelease, npmDistTag } = require("./version-policy");
+const { parse, compare, isPrerelease, npmDistTag } = require("./version-policy");
 const { ChannelError } = require("./channel-error");
 const { publishNuget } = require("./nuget");
+const { publishGitlabPackage } = require("./gitlab");
+const { refuseRemote } = require("./remote");
 
 /** What every package and release says it is, unless `description` says otherwise. */
 const DEFAULT_DESCRIPTION = "API description documents for {target}.";
@@ -301,11 +303,11 @@ function publishGithubRelease(archive, manifest, options, log) {
  * configuration file gets committed, and a credential in a committed file is a
  * credential that has leaked.
  */
-async function putFile(url, body, token, contentType) {
+async function putFile(url, body, auth, contentType) {
     const response = await fetch(url, {
         method: "PUT",
         headers: {
-            "Authorization": `Bearer ${token}`,
+            ...auth,
             "Content-Type": contentType,
             "Content-Length": String(body.length),
         },
@@ -322,8 +324,8 @@ async function putFile(url, body, token, contentType) {
 }
 
 /** What a Maven repository holds at `url`, or null when it holds nothing there. */
-async function getFile(url, token) {
-    const response = await fetch(url, { headers: { "Authorization": `Bearer ${token}` } });
+async function getFile(url, auth) {
+    const response = await fetch(url, { headers: auth });
     if (response.status === 404) return null;
     if (!response.ok) {
         throw new ChannelError(`GET ${url} failed: ${response.status} ${response.statusText}. ` +
@@ -333,6 +335,54 @@ async function getFile(url, token) {
     return Buffer.from(await response.arrayBuffer());
 }
 
+/** An HTTP header name: RFC 9110's token. */
+const HEADER_NAME = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
+
+/** The highest of `versions` that parse as semver and pass `keep`, or null. */
+function highest(versions, keep = () => true) {
+    const valid = versions.filter((v) => { try { parse(v); return keep(v); } catch { return false; } });
+    return valid.length ? valid.reduce((a, b) => (compare(a, b) >= 0 ? a : b)) : null;
+}
+
+/** The artifact's maven-metadata.xml, as `mvn deploy` keeps it. */
+function metadataXml(groupId, artifactId, versions, lastUpdated) {
+    const latest = highest(versions);
+    const release = highest(versions, (v) => !isPrerelease(v));
+    return '<?xml version="1.0" encoding="UTF-8"?>\n<metadata>\n' +
+        `  <groupId>${groupId}</groupId>\n  <artifactId>${artifactId}</artifactId>\n  <versioning>\n` +
+        (latest ? `    <latest>${latest}</latest>\n` : "") + (release ? `    <release>${release}</release>\n` : "") +
+        `    <versions>\n${versions.map((v) => `      <version>${v}</version>\n`).join("")}    </versions>\n` +
+        `    <lastUpdated>${lastUpdated}</lastUpdated>\n  </versioning>\n</metadata>\n`;
+}
+
+/**
+ * Adds the version to the artifact's maven-metadata.xml, which a repository that does not
+ * generate it -- GitLab's -- otherwise never has, so that update bots never see a new
+ * version. Written only when it lacks the version, or its latest or release would change.
+ */
+async function updateMetadata(url, groupId, artifactId, manifest, auth, log) {
+    const held = await getFile(url, auth);
+    const xml = held ? held.toString("utf8") : "";
+    const block = /<versions>([\s\S]*?)<\/versions>/.exec(xml);
+    const versions = block ? [...block[1].matchAll(/<version>\s*([^<\s]+)\s*<\/version>/g)].map((m) => m[1]) : [];
+    const tag = (name) => ((new RegExp(`<${name}>\\s*([^<\\s]+)\\s*</${name}>`).exec(xml)) || [])[1] || null;
+    const listed = versions.includes(manifest.version) ? versions : [...versions, manifest.version];
+    if (listed === versions && tag("latest") === highest(listed)
+        && tag("release") === highest(listed, (v) => !isPrerelease(v))) {
+        return;
+    }
+    // The commit's time, as the archive's producedAt, so the same commit writes the same file.
+    const lastUpdated = String(manifest.producedAt || new Date().toISOString()).replace(/\.\d+Z$/, "Z").replace(/[-:TZ]/g, "");
+    try {
+        await putFile(url, Buffer.from(metadataXml(groupId, artifactId, listed, lastUpdated), "utf8"), auth, "application/xml");
+    } catch (error) {
+        throw new ChannelError(`the repository refused maven-metadata.xml for ${groupId}:${artifactId}: ${error.message.trim()} ` +
+            "The version's files are published; a re-run retries only the metadata. For a repository that generates " +
+            "its own maven-metadata.xml, set channels.maven.metadata: false.");
+    }
+    log(`-- Listed ${manifest.version} in ${groupId}:${artifactId}'s maven-metadata.xml`);
+}
+
 function publishMavenRemote(archive, manifest, options, log) {
     const tokenEnv = options.tokenEnv || "MAVEN_TOKEN";
     const token = process.env[tokenEnv];
@@ -342,12 +392,20 @@ function publishMavenRemote(archive, manifest, options, log) {
             `Remote publication needs one; set it in the release job's environment.`
         );
     }
+    // A bearer token unless tokenHeader names another header, which then carries the
+    // token as it is: GitLab takes a job, personal or deploy token as Job-Token,
+    // Private-Token or Deploy-Token, and Bearer only for OAuth.
+    if (options.tokenHeader !== undefined && !HEADER_NAME.test(options.tokenHeader)) {
+        throw new ChannelError(`channels.maven.tokenHeader must be an HTTP header name, such as Job-Token, ` +
+            `not ${JSON.stringify(options.tokenHeader)}`);
+    }
+    const auth = options.tokenHeader === undefined ? { "Authorization": `Bearer ${token}` } : { [options.tokenHeader]: token };
 
     const artifactId = options.artifactId || manifest.target;
     const version = manifest.version;
     const extension = options.extension || "tgz";
-    const base = `${options.repository.replace(/\/+$/, "")}/` +
-        `${options.groupId.split(".").join("/")}/${artifactId}/${version}/${artifactId}-${version}`;
+    const artifactDir = `${options.repository.replace(/\/+$/, "")}/${options.groupId.split(".").join("/")}/${artifactId}`;
+    const base = `${artifactDir}/${version}/${artifactId}-${version}`;
 
     const work = (async () => {
         // Idempotent, file by file: each file the repository already has is left alone when
@@ -363,7 +421,7 @@ function publishMavenRemote(archive, manifest, options, log) {
         ];
         const missing = [];
         for (const file of files) {
-            const existing = await getFile(file.url, token);
+            const existing = await getFile(file.url, auth);
             if (!existing) {
                 missing.push(file);
             } else if (!existing.equals(file.bytes)) {
@@ -373,7 +431,10 @@ function publishMavenRemote(archive, manifest, options, log) {
                     "A published version is never replaced; publish the change as a new version.");
             }
         }
-        for (const file of missing) await putFile(file.url, file.bytes, token, file.type);
+        for (const file of missing) await putFile(file.url, file.bytes, auth, file.type);
+        if (options.metadata !== false) {
+            await updateMetadata(`${artifactDir}/maven-metadata.xml`, options.groupId, artifactId, manifest, auth, log);
+        }
         return missing.length === 0;
     })();
 
@@ -392,16 +453,24 @@ function publishMavenRemote(archive, manifest, options, log) {
 
 const CHANNELS = {
     file: publishFile, maven: publishMaven, npm: publishNpm, "github-release": publishGithubRelease, nuget: publishNuget,
+    "gitlab-package": publishGitlabPackage,
 };
 
+/**
+ * Publishes to the channel named `channel`, of the type its settings' `type` names, or
+ * of the type it is named after -- `maven` is a Maven channel, as it has always been.
+ */
 function publish(archive, manifest, channel, options, log = () => {}) {
-    const handler = CHANNELS[channel];
+    const { type = channel, ...settings } = options || {};
+    const handler = CHANNELS[type];
     if (!handler) {
         throw new ChannelError(
             `unknown channel '${channel}'; available channels are ${Object.keys(CHANNELS).join(", ")}`
         );
     }
-    return handler(archive, manifest, options || {}, log);
+    // Here as well as in the CLI, so the Publisher used as a library keeps it too.
+    refuseRemote([channel], { [channel]: options || {} });
+    return handler(archive, manifest, settings, log);
 }
 
 module.exports = { publish, CHANNELS, ChannelError, pom, format, DEFAULT_DESCRIPTION };

package/src/cli.js

@@ -17,6 +17,8 @@ const { pack, PackError } = require("./pack");
 const { changedSince, ChangedError } = require("./changed");
 const { split, SplitError } = require("./split");
 const { publish, ChannelError } = require("./channels");
+const { refuseRemote } = require("./remote");
+const { CHANNEL_TYPES } = require("./channel-types");
 const { VersionError: PolicyError, describe } = require("./version-policy");
 const { versionOf, BundleVersionError } = require("./bundle-version");
 const { unreferenced } = require("./unreferenced");
@@ -323,7 +325,9 @@ async function main(argv, io = {}) {
             for (const name of Object.keys(config.targets)) {
                 const kinds = ["openapi", "asyncapi"].filter((k) => config.targets[name][k]);
                 const published = config.isPublished(name) ? "" : "  (publish: false)";
-                console.log(`${name}  [${kinds.join(", ")}]${published}`);
+                const routed = config.isPublished(name) && Object.keys(config.channels || {}).length > 0
+                    ? `  channels: ${config.channelsOf(name).join(", ")}` : "";
+                console.log(`${name}  [${kinds.join(", ")}]${published}${routed}`);
             }
             return 0;
         }
@@ -447,18 +451,43 @@ async function main(argv, io = {}) {
         case "publish": {
             const outDir = options.out ? path.resolve(options.dir, options.out) : config.packagesDir();
             const configured = config.channels || {};
-            const names = options.channels || Object.keys(configured);
-            if (names.length === 0) {
+            for (const name of options.channels || []) {
+                // An unconfigured channel named after a type is that channel with no settings.
+                if (!configured[name] && !(name in configured) && !CHANNEL_TYPES.includes(name)) {
+                    const names = Object.keys(configured);
+                    throw new ConfigError(`--channel '${name}' is not a configured channel; ` +
+                        `apionly.yaml configures ${names.length ? names.join(", ") : "no channels"}`);
+                }
+            }
+            if (!options.channels && Object.keys(configured).length === 0) {
                 throw new ConfigError("no channels configured; add a `channels:` block or pass --channel");
             }
-            const shipped = shippedTargets(config, targets);
+            // Each target's channels: its own list, or every configured one, narrowed by --channel.
+            const shippable = shippedTargets(config, targets);
+            const routes = new Map(shippable.map((target) => {
+                const own = config.targets[target].channels;
+                return [target, options.channels
+                    ? options.channels.filter((name) => !own || own.includes(name))
+                    : config.channelsOf(target)];
+            }));
+            for (const target of shippable) {
+                const own = config.targets[target].channels;
+                for (const name of (own && options.channels) || []) {
+                    if (!own.includes(name)) log(`${target}: not published to ${name} (not in targets.${target}.channels)`);
+                }
+            }
+            const shipped = shippable.filter((target) => routes.get(target).length > 0);
+            if (options.channels && shippable.length > 0 && shipped.length === 0) {
+                throw new ConfigError(`nothing was published: no target in this run is routed to ${options.channels.join(", ")}`);
+            }
+            // Every channel this run uses, before anything is read, packed or sent.
+            refuseRemote([...new Set(shipped.flatMap((target) => routes.get(target)))], configured);
             const versions = versionsOf(config, shipped, options.preRelease);
             const closures = forTargets(config, undefined, shipped);
             let published = 0;
             const handoff = [];
             for (const target of Object.keys(config.targets)) {
-                if (targets && !targets.includes(target)) continue;
-                if (!config.isPublished(target)) continue;
+                if (!shipped.includes(target)) continue;
                 const closure = closures.get(target);
                 // Packed once, then shipped unchanged to every channel.
                 const { archive, manifest } = pack(config, target, {
@@ -466,11 +495,11 @@ async function main(argv, io = {}) {
                     closureSha256: closure ? closure.sha256 : null,
                     outDir, log,
                 });
-                for (const name of names) {
+                for (const name of routes.get(target)) {
                     // A remote channel returns a promise; a local one does not.
                     const result = await publish(archive, manifest, name, { ...(configured[name] || {}), baseDir: config.root }, log);
                     for (const file of result.files || []) {
-                        handoff.push({ file, target, version: manifest.version, channel: name });
+                        handoff.push({ file, target, version: manifest.version, channel: name, type: config.channelType(name) });
                     }
                     published += 1;
                 }

package/src/config.js

@@ -9,6 +9,8 @@ const fs = require("fs");
 const path = require("path");
 const YAML = require("yaml");
 
+const { CHANNEL_TYPES, describeTypes } = require("./channel-types");
+
 const CONFIG_NAME = "apionly.yaml";
 const SUPPORTED_SCHEMA_VERSION = 1;
 
@@ -30,7 +32,7 @@ const REPORTS_KEYS = ["lint"];
 const LINT_KEYS = ["unreferenced", "examples"];
 const LINT_EXAMPLES_KEYS = ["openapi", "asyncapi"];
 const DISTRIBUTION_KEYS = ["root", "layout"];
-const TARGET_KEYS = ["openapi", "asyncapi", "publish", "versionFile"];
+const TARGET_KEYS = ["openapi", "asyncapi", "publish", "versionFile", "channels"];
 const TARGET_KIND_KEYS = ["bundle", "aggregate", "info"];
 const PORTFOLIO_KEYS = ["openapi", "security", "location"];
 const PORTFOLIO_OPENAPI_KEYS = ["paths", "operationIds", "tags"];
@@ -49,6 +51,73 @@ const PATH_STRATEGIES = ["target-prefix", "none"];
 
 class ConfigError extends Error {}
 
+// A channel's name, as init asks of a target's: lowercase words joined by single hyphens.
+const CHANNEL_NAME = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+
+/**
+ * Each configured channel's type, by name. A channel named after a type is that type;
+ * any other name says its type with `type`, which is how one apionly.yaml has two
+ * channels of one type -- a Maven repository per partner.
+ */
+function channelTypes(channels) {
+    if (typeof channels !== "object" || Array.isArray(channels)) {
+        throw new ConfigError("channels must be a mapping of channel names to their settings");
+    }
+    const types = {};
+    for (const [name, settings] of Object.entries(channels)) {
+        if (!CHANNEL_NAME.test(name)) {
+            throw new ConfigError(`channel name '${name}': use lowercase letters and digits, in words joined by single ` +
+                "hyphens, starting with a letter, such as partner-a");
+        }
+        if (settings !== null && (typeof settings !== "object" || Array.isArray(settings))) {
+            throw new ConfigError(`channels.${name} must be a mapping of settings`);
+        }
+        const declared = settings ? settings.type : undefined;
+        if (CHANNEL_TYPES.includes(name)) {
+            if (declared !== undefined && declared !== name) {
+                throw new ConfigError(`channel '${name}' is named after a channel type, so its type is ${name}, ` +
+                    `not ${declared}; give it another name`);
+            }
+            types[name] = name;
+        } else if (declared === undefined) {
+            throw new ConfigError(`channel '${name}' is not a channel type; say which one it is with type: ${describeTypes()}`);
+        } else if (!CHANNEL_TYPES.includes(declared)) {
+            throw new ConfigError(`channels.${name}.type '${declared}' is not a channel type: ${describeTypes()}`);
+        } else {
+            types[name] = declared;
+        }
+    }
+    return types;
+}
+
+/** Refuses a target's `channels` that cannot be what it means. */
+function checkTargetChannels(name, target, channels, isAggregate) {
+    const list = target.channels;
+    if (list === undefined) return;
+    if (!Array.isArray(list) || list.some((c) => typeof c !== "string")) {
+        throw new ConfigError(`targets.${name}.channels must be a list of channel names`);
+    }
+    if (list.length === 0) {
+        throw new ConfigError(`targets.${name}.channels is empty; a target that is published nowhere says so with publish: false`);
+    }
+    if (isAggregate) {
+        throw new ConfigError(`target '${name}' is an aggregate, which is never published, so it has no channels`);
+    }
+    if (target.publish === false) {
+        throw new ConfigError(`target '${name}' is not published (publish: false), so it has no channels`);
+    }
+    const seen = new Set();
+    for (const channel of list) {
+        if (seen.has(channel)) throw new ConfigError(`target '${name}' lists channel '${channel}' twice`);
+        seen.add(channel);
+        if (!Object.prototype.hasOwnProperty.call(channels, channel)) {
+            const configured = Object.keys(channels);
+            throw new ConfigError(`target '${name}' lists channel '${channel}', which apionly.yaml does not configure; ` +
+                `it configures ${configured.length ? configured.join(", ") : "no channels"}`);
+        }
+    }
+}
+
 /** Refuses a key `obj` has that is not in `allowed`, naming the key and where it is. */
 function checkKeys(obj, allowed, where) {
     if (!obj || typeof obj !== "object") return;
@@ -135,6 +204,9 @@ function load(configPath) {
         );
     }
 
+    const channels = parsed.channels || {};
+    const types = channelTypes(channels);
+
     const targets = parsed.targets;
     if (!targets || typeof targets !== "object" || Object.keys(targets).length === 0) {
         throw new ConfigError(`${configPath} declares no targets`);
@@ -176,6 +248,8 @@ function load(configPath) {
             );
         }
 
+        checkTargetChannels(name, target, channels, aggregateKinds.length > 0);
+
         for (const kind of kinds) {
             checkKeys(target[kind], TARGET_KIND_KEYS, `targets.${name}.${kind}`);
             if (target[kind].aggregate !== undefined) {
@@ -238,7 +312,7 @@ function load(configPath) {
         reports,
         lint,
         distribution: parsed.distribution || null,
-        channels: parsed.channels || {},
+        channels,
         portfolio,
         targets,
 
@@ -326,6 +400,15 @@ function load(configPath) {
         // An aggregate is never published either, whether or not it says so --
         // load() already refuses the one case that would contradict this, `publish:
         // true` alongside an aggregate, so nothing here needs to re-check that.
+        // A configured channel's type; a name that is not configured is taken for a type,
+        // as `publish --channel github-release` has always meant that channel unconfigured.
+        channelType(name) {
+            return types[name] || name;
+        },
+        // The channels a target is published to: its own list, or every configured one.
+        channelsOf(target) {
+            return this.targets[target].channels || Object.keys(this.channels);
+        },
         isPublished(target) {
             return this.targets[target].publish !== false && !this.isAggregate(target);
         },

package/src/gitlab.js

@@ -0,0 +1,187 @@
+"use strict";
+
+// `gitlab-package` -- publish to a GitLab project's Generic Package Registry.
+//
+// One generic package per target, at the contract's version, holding the archive and
+// manifest.json: the same two files the `file` channel writes. In a GitLab CI job it
+// needs no settings at all: the API, the project and the job token come from GitLab's
+// own CI variables. `release: true` also creates the tag's GitLab release, linking both
+// files as packages.
+//
+// GitLab allows duplicate versions by default: a different file under a version it has
+// is accepted, and served from then on. So every file is read back before it is
+// uploaded, and the read-back, not GitLab, keeps a published version immutable.
+
+const path = require("path");
+const { execFileSync } = require("child_process");
+
+const { isPrerelease } = require("./version-policy");
+const { ChannelError } = require("./channel-error");
+
+const GITLAB_COM = "https://gitlab.com/api/v4";
+const TOKEN_HEADERS = { private: "PRIVATE-TOKEN", deploy: "DEPLOY-TOKEN", job: "JOB-TOKEN" };
+
+/** The API, the project and the credential, from configuration first and GitLab CI variables second. */
+function channelSettings(options, env = process.env) {
+    const tokenEnv = options.tokenEnv || "GITLAB_TOKEN";
+    let token = env[tokenEnv];
+    let tokenType = options.tokenType || "private";
+    if (!TOKEN_HEADERS[tokenType]) {
+        throw new ChannelError(`channels.gitlab-package.tokenType must be private, deploy or job, not ${JSON.stringify(tokenType)}`);
+    }
+    if (!token && env.CI_JOB_TOKEN) {
+        token = env.CI_JOB_TOKEN;
+        tokenType = "job";
+    }
+    if (!token) {
+        throw new ChannelError(
+            `no token in $${tokenEnv}, which channels.gitlab-package.tokenEnv names, and no $CI_JOB_TOKEN. ` +
+            "Set one in the release job's environment, or run in a GitLab CI job.");
+    }
+    const project = options.project === undefined ? env.CI_PROJECT_ID : String(options.project);
+    if (!project) {
+        throw new ChannelError("the gitlab-package channel needs a project: set channels.gitlab-package.project, " +
+            "or run in a GitLab CI job ($CI_PROJECT_ID)");
+    }
+    const url = (options.url || env.CI_API_V4_URL || GITLAB_COM).replace(/\/+$/, "");
+    return { url, project, tokenType, headers: { [TOKEN_HEADERS[tokenType]]: token } };
+}
+
+/** The commit a new release's tag points at: the CI job's, or the checkout's HEAD. */
+function releaseRef(options, env = process.env) {
+    if (env.CI_COMMIT_SHA) return env.CI_COMMIT_SHA;
+    try {
+        return execFileSync("git", ["-C", path.resolve(options.baseDir || "."), "rev-parse", "HEAD"],
+            { encoding: "utf8", stdio: "pipe" }).trim();
+    } catch {
+        throw new ChannelError("release: true needs the commit to tag: $CI_COMMIT_SHA, or a git checkout to read HEAD from");
+    }
+}
+
+/** The status and GitLab's message, without the status twice: GitLab's messages often start with it. */
+async function answered(response) {
+    const text = await response.text();
+    let message = text;
+    try {
+        const body = JSON.parse(text);
+        message = body.message || body.error || text;
+    } catch {
+        // Not JSON: a proxy's error page, say. Reported as it came.
+    }
+    return message.startsWith(String(response.status)) ? message : `${response.status} ${message}`;
+}
+
+const TOKEN_HINT = " Check the token, and that it may read and write this project's package registry.";
+
+/** GitLab's copy of a package file: its bytes, or null when it has none. */
+async function readBack(fileUrl, name, headers) {
+    const response = await fetch(fileUrl, { headers });
+    if (response.status === 404) return null;
+    if (!response.ok) {
+        throw new ChannelError(`could not read ${name} back from ${fileUrl}: ${await answered(response)}.` +
+            (response.status === 401 || response.status === 403 ? TOKEN_HINT : ""));
+    }
+    return Buffer.from(await response.arrayBuffer());
+}
+
+function notThisOne(name, manifest) {
+    return new ChannelError(`GitLab already has ${name} in ${manifest.target} ${manifest.version}, and it is not this one; ` +
+        "a published version is never replaced, so publish the change as a new version");
+}
+
+/** Uploads one file unless GitLab has it: true when it was already there, identical. */
+async function upload(fileUrl, name, bytes, manifest, headers) {
+    const held = await readBack(fileUrl, name, headers);
+    if (held) {
+        if (held.equals(bytes)) return true;
+        throw notThisOne(name, manifest);
+    }
+    const response = await fetch(fileUrl, { method: "PUT", headers, body: bytes });
+    if (response.ok) return false;
+    const refused = `${await answered(response)}`;
+    // Refused, perhaps as a duplicate another run published meanwhile: compare that one.
+    const now = await readBack(fileUrl, name, headers).catch(() => null);
+    if (now && now.equals(bytes)) return true;
+    if (now) throw notThisOne(name, manifest);
+    throw new ChannelError(`GitLab refused ${name}: ${refused}.` +
+        (response.status === 401 || response.status === 403 ? TOKEN_HINT : ""));
+}
+
+async function api(url, headers, method = "GET", body) {
+    return fetch(url, {
+        method,
+        headers: body === undefined ? headers : { ...headers, "Content-Type": "application/json" },
+        body: body === undefined ? undefined : JSON.stringify(body),
+    });
+}
+
+/** Creates the tag's release, or adds the package links an existing one lacks; never changes anything else. */
+async function release(settings, manifest, options, links, ref, log) {
+    const { format, DEFAULT_DESCRIPTION } = require("./channels");
+    const tag = format(options.tagFormat || "{target}-v{version}", manifest);
+    const releases = `${settings.url}/projects/${encodeURIComponent(settings.project)}/releases`;
+    const existing = await api(`${releases}/${encodeURIComponent(tag)}`, settings.headers);
+    if (existing.status === 404) {
+        const created = await api(releases, settings.headers, "POST", {
+            tag_name: tag,
+            ref,
+            name: format(options.title || "{target} {version}", manifest),
+            description: format(options.notes || options.description || DEFAULT_DESCRIPTION, manifest),
+            assets: { links },
+        });
+        if (!created.ok) throw new ChannelError(`GitLab refused the release ${tag}: ${await answered(created)}`);
+        log(`-- Created the GitLab release ${tag}`);
+        return;
+    }
+    if (!existing.ok) {
+        throw new ChannelError(`could not read the GitLab release ${tag}: ${await answered(existing)}`);
+    }
+    // A release's link names are unique: one already named, or already pointing here, is left as it is.
+    const held = ((await existing.json()).assets || {}).links || [];
+    for (const link of links.filter((l) => !held.some((h) => h.url === l.url || h.name === l.name))) {
+        const added = await api(`${releases}/${encodeURIComponent(tag)}/assets/links`, settings.headers, "POST", link);
+        if (!added.ok) throw new ChannelError(`GitLab refused a link on the release ${tag}: ${await answered(added)}`);
+        log(`-- Linked ${link.name} from the GitLab release ${tag}`);
+    }
+}
+
+function publishGitlabPackage(archive, manifest, options, log) {
+    const { format } = require("./channels");
+    const settings = channelSettings(options);
+    const wantsRelease = options.release === true && !isPrerelease(manifest.version);
+    if (wantsRelease && settings.tokenType === "deploy") {
+        throw new ChannelError("a deploy token cannot create a GitLab release: GitLab gives it the package registry only. " +
+            "Publish with $CI_JOB_TOKEN, or a personal or project access token with the api scope, or set release: false.");
+    }
+    const ref = wantsRelease ? releaseRef(options) : null;
+
+    const packageName = format(options.packageName || "{target}", manifest);
+    const base = `${settings.url}/projects/${encodeURIComponent(settings.project)}/packages/generic/` +
+        `${encodeURIComponent(packageName)}/${encodeURIComponent(manifest.version)}`;
+    const files = [
+        { name: path.basename(archive), bytes: require("fs").readFileSync(archive) },
+        { name: "manifest.json", bytes: Buffer.from(JSON.stringify(manifest, null, 2) + "\n") },
+    ].map((file) => ({ ...file, url: `${base}/${encodeURIComponent(file.name)}` }));
+
+    return (async () => {
+        let identical = 0;
+        for (const file of files) {
+            if (await upload(file.url, file.name, file.bytes, manifest, settings.headers)) identical += 1;
+        }
+        const alreadyPublished = identical === files.length;
+        log(alreadyPublished
+            ? `-- ${packageName} ${manifest.version} is already in GitLab project ${settings.project}, identical; nothing to do`
+            : `-- Published ${packageName} ${manifest.version} to GitLab project ${settings.project}`);
+
+        if (options.release === true && !wantsRelease) {
+            log(`-- no GitLab release for a pre-release: ${manifest.version} would become the latest release`);
+        }
+        if (wantsRelease) {
+            await release(settings, manifest, options,
+                files.map((file) => ({ name: file.name, url: file.url, link_type: "package" })), ref, log);
+        }
+        return { location: files[0].url, ...(alreadyPublished ? { alreadyPublished } : {}) };
+    })();
+}
+
+module.exports = { publishGitlabPackage, channelSettings };

package/src/handoff.js

@@ -25,10 +25,10 @@ const HANDOFF_SCHEMA_VERSION = 1;
  */
 function writeHandoff(root, outDir, entries) {
     const files = entries
-        .map(({ file, target, version, channel }) => ({
+        .map(({ file, target, version, channel, type = channel }) => ({
             path: path.relative(root, file).split(path.sep).join("/"),
             sha256: crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex"),
-            target, version, channel,
+            target, version, channel, type,
         }))
         .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
 

package/src/remote.js

@@ -0,0 +1,64 @@
+"use strict";
+
+// Whether `publish` may contact anything.
+//
+// A channel's local mode writes files; its remote mode sends them somewhere: a
+// repository or feed at a URL, a registry, a release. API_ONLY_PUBLISHER_REMOTE=never
+// refuses every remote mode, so the Publisher contacts nothing. The Docker image sets
+// it, and is sealed unless a pipeline sets allow; outside the image it is unset, and
+// the Publisher behaves as it always has.
+//
+// It is a promise the Publisher keeps, not an enforcement: whoever sets the variable
+// can change it. A guarantee needs the platform to isolate the job's network.
+
+const { ChannelError } = require("./channel-error");
+
+const REMOTE_ENV = "API_ONLY_PUBLISHER_REMOTE";
+
+/** `allow`, the default when unset or empty, or `never`; anything else is refused. */
+function remoteMode(env = process.env) {
+    const value = env[REMOTE_ENV];
+    if (value === undefined || value === "") return "allow";
+    if (value !== "allow" && value !== "never") {
+        throw new ChannelError(`${REMOTE_ENV} must be allow or never, not ${JSON.stringify(value)}`);
+    }
+    return value;
+}
+
+const URL = /^https?:\/\//;
+
+/** Whether `channel`, with these settings, would contact anything. */
+function isRemote(channel, settings = {}) {
+    switch (channel) {
+        case "maven":
+        case "nuget":
+            return URL.test(settings.repository || "");
+        case "npm":
+            return settings.publish !== false;
+        case "github-release":
+        case "gitlab-package":
+            return true;
+        default:
+            return false;
+    }
+}
+
+/**
+ * Refuses, under `never`, a run that would use any remote channel, naming each of them,
+ * before anything is built, packed or sent. Also refuses an invalid value, whatever the
+ * channels: a typo in a switch that keeps the Publisher sealed is not ignored.
+ */
+function refuseRemote(names, configured = {}, env = process.env) {
+    if (remoteMode(env) === "allow") return;
+    // Judged by type: a channel named partner-a may be a Maven repository at a URL.
+    const remote = names.filter((name) => {
+        const settings = configured[name] || {};
+        return isRemote(settings.type || name, settings);
+    });
+    if (remote.length === 0) return;
+    throw new ChannelError(
+        `${REMOTE_ENV}=never refuses the remote channels ${remote.join(", ")}, so nothing was built, packed or sent. ` +
+        `Publish with their local modes, or set ${REMOTE_ENV}=allow where this run may contact them.`);
+}
+
+module.exports = { REMOTE_ENV, remoteMode, isRemote, refuseRemote };

package/src/version-policy.js

@@ -33,6 +33,32 @@ function parse(version) {
     };
 }
 
+/**
+ * Semver precedence: negative when `a` comes before `b`, positive after, 0 when equal.
+ * Build metadata is ignored; a release comes after its pre-releases; pre-release
+ * identifiers compare numerically when both are numbers, a number before a word.
+ */
+function compare(a, b) {
+    const x = parse(a);
+    const y = parse(b);
+    for (const part of ["major", "minor", "patch"]) {
+        if (x[part] !== y[part]) return x[part] - y[part];
+    }
+    if (x.prerelease === y.prerelease) return 0;
+    if (x.prerelease === null) return 1;
+    if (y.prerelease === null) return -1;
+    const xs = x.prerelease.split(".");
+    const ys = y.prerelease.split(".");
+    for (let i = 0; i < Math.min(xs.length, ys.length); i++) {
+        if (xs[i] === ys[i]) continue;
+        const [xn, yn] = [/^\d+$/.test(xs[i]), /^\d+$/.test(ys[i])];
+        if (xn && yn) return Number(xs[i]) - Number(ys[i]);
+        if (xn !== yn) return xn ? -1 : 1;
+        return xs[i] < ys[i] ? -1 : 1;
+    }
+    return xs.length - ys.length;
+}
+
 function isPrerelease(version) {
     // -SNAPSHOT is not semver-legal as Maven spells it, but it is what Maven
     // consumers expect, so it is recognised rather than rejected.
@@ -65,4 +91,4 @@ function describe(version) {
     return { prerelease: true, kind: "other" };
 }
 
-module.exports = { parse, isPrerelease, npmDistTag, describe, VersionError, SEMVER };
+module.exports = { parse, compare, isPrerelease, npmDistTag, describe, VersionError, SEMVER };