@wtf/release-oci
v4.0.1
Published
The OCI images of a repo released and tagged in their registry, of no release tool and no rebuild, each function by the platform it is given: the ecosystem of OCI images, its default export (., ./ecosystem), a releasing ecosystem of the contract of @wtf/r
Maintainers
Readme
@wtf/release-oci
Releases the OCI images of a repo, with no release tool and no rebuild. A pipeline builds and tests
an image; a release copies that tested image, by its digest, to the tag of its version in the
registry, and points the tags that move at it, so the bytes released are the bytes tested. This
library reads the images of a repo, finds the tested image of each, and copies it by
crane. It is the
library of @wtf/semantic-release-oci, with no dependency on
semantic-release nor on the trains; each function runs git and crane by the platform its caller
gives it, in the folder of the repo, as @wtf/release has them.
The ecosystem
Its default export is the ecosystem of OCI images, ociEcosystem of ./ecosystem, a
ReleasingEcosystem of @wtf/release/contract, which a config names in
ecosystems as '@wtf/release-oci'. The trains then read the images of the repo as they read npm
packages and crates: which train holds each, the order of the trains, and the checks of a release
(Ecosystems).
packagesgives a package for each folder of a file an image is built of that git tracks: aDockerfileor aContainerfile, or a.devcontainer/devcontainer.json, which the devcontainer CLI builds. A folder of more than one of them is one image. Its name is its repository in the registry: the registry image of the project,CI_REGISTRY_IMAGEof a pipeline, for an image at the root, and that and its folder for another, as GitLab names the images of a project; its folder where the environment names no registry image. Every image is published, and none depends on another: aFROMor a base pins a tag of a registry, not a package of the repo. It reads the working tree by default, or a commit bygit ls-tree.resolvegives the tag a release publishes, the version itself:1.4.0for1.4.0.satisfiestakes a tag of the one version it names.
import type { ReleasePlatform, RepoContext } from '@wtf/release'
import oci from '@wtf/release-oci'
oci.resolve('0.0.0', '1.4.0') // '1.4.0'
oci.satisfies('1.4.0', '1.4.0') // true
/** The images of the repo at the tag of a release, as the trains read them. */
export const imagesAt = (repo: RepoContext<ReleasePlatform>, tag: string) =>
oci.packages({ ...repo, ref: tag })A release of images
No version is written into git: the tags of the registry are the versions. A driver, as runStep
of @wtf/release/driver, runs the steps of the ecosystem over the images of the plan it gives,
plan.own, each with the same options, OciOptions:
| Option | What it is |
| ----------- | ------------------------------------------------------------------------------------------- |
| moving | The tags that move to the version, as ['1.4', '1'] or ['12.12', 'latest']: [] of none |
| source | The tested image of each: its repository, {image} the image's own, and its tag |
| platforms | The platforms each tested image must be of, as linux/amd64: any by default |
| crane | The command of crane: crane by default |
Each step:
verifychecks that the version and each tag ofmovingis a tag of an image (EOCIVERSION), and that each image has a repository (EOCIIMAGE). It asks the registry nothing.smokefinds the tested image of each by its digest (crane digest), and the platforms of its index (crane manifest). A source the registry has not, or of fewer platforms thanplatformsnames, fails (EOCISMOKE).publishsmokes each image, then copies the digest of its tested image to the tag of the version,crane copy <source>@<digest> <image>:<version>, which mounts each blob of the source's repository rather than moving it. It gives each image, aReleasedof@wtf/release/forge: of its page on Docker Hub or Quay, which its URL alone names; else of its registry, of the typecontainer, whose page the forge of the release knows, as the container registry of GitLab orghcr.ioof GitHub (./pages). An image is linked where it lives, never uploaded.movepoints each tag ofmovingat the digest the registry has of the version,crane copy <image>@<digest> <image>:<tag>. A version the registry has not fails (EOCIMOVE).
The tag of the version is copied once: a registry that has it at the same digest is skipped, so a
release that stopped part way is finished by running it again, and at another digest is refused
(EOCIRETAG), as a released version never moves. The tags that move are copied every time. A dry
run, release.dryRun, asks the registry, and copies nothing. The ecosystem
writes nothing into git, so it has no prepare.
import type { Plan, Release } from '@wtf/release/contract'
import { runStep } from '@wtf/release/driver'
import oci from '@wtf/release-oci'
/** The images of `plan` released as `12.12-wtf.1`, `12.12` and `latest`, of a tested image. */
export async function release(of: Release, plan: Plan, tag: string) {
const plans = new Map([['oci', plan]])
const options = { moving: ['12.12', 'latest'], source: { repository: '{image}/snapshot', tag } }
const ecosystems = [[oci, options]] as const
await runStep(of, plans, ecosystems, 'verify')
const { released } = await runStep(of, plans, ecosystems, 'publish')
await runStep(of, plans, ecosystems, 'move')
return released
}The tags of a release
The ecosystem takes the tags of a release as they are given: the version, the tag that is copied
once and never moved, and moving, each tag copied on every run, [] of none. It derives none: a
release of a semver version, as the plugin makes it, moves its minor and its major, and a release of
a version that is no semver, as 12.12-wtf.1 of an image of Debian 12.12, names its own. Each is a
tag an image can have, [A-Za-z0-9_][A-Za-z0-9_.-]{0,127}, none given twice, as checkReleaseTags
of ./tags checks.
The functions the steps build on take each image of its repository and its source, of no plan:
smokeImages, publishImages and moveImages of ./publish.
import type { RepoPlatform } from '@wtf/release'
import { moveImages, publishImages } from '@wtf/release-oci/publish'
/** The base image of Debian 12.12, its first build of ours, as `12.12-wtf.1`, `12.12` and `latest`. */
export async function release(platform: RepoPlatform, source: string) {
const repository = 'registry.gitlab.com/acme/images/base'
await publishImages({
context: { platform },
images: [{ repository, source: { repository, tag: source } }],
version: '12.12-wtf.1'
})
await moveImages({
context: { platform },
repositories: [repository],
version: '12.12-wtf.1',
moving: ['12.12', 'latest']
})
}The version in an image
A release stamps nothing: the image a pipeline tested is the image it publishes. A pipeline that
labels an image of the version it will be, as org.opencontainers.image.version, reads the next
version of its train of the dotenv semantic-release-info of
@wtf/semantic-release-trains writes, and passes it to the
build as an argument of its own.
Subpaths
| Subpath | What it is |
| ------------- | ------------------------------------------------------------------------------------------------------------------ |
| . | OciImage, and the ecosystem as the default export |
| ./ecosystem | ociEcosystem, OciOptions, repositoriesOf, packagesOfImages, packagesOfRepo, resolveTag, satisfiesTag |
| ./images | readImages, imagesAt, imagesOf, imageDirOf, repositoryOf |
| ./tags | checkReleaseTags, isImageTag |
| ./publish | smokeImages, publishImages, moveImages, digestOf, platformsOf |
| ./pages | releasedImage, imagePageOf, repositoryParts |
| ./errors | OciError, OCI_ERRORS |
Errors
| Code | Means |
| --------------- | --------------------------------------------------------------------------------------- |
| EOCIECOSYSTEM | ecosystems lists neither @wtf/semantic-release-oci/ecosystem nor this |
| EOCIIMAGE | An image has no repository: neither image nor CI_REGISTRY_IMAGE names one |
| EOCISOURCE | The tested image has no tag: neither sourceTag nor CI_COMMIT_REF_SLUG, nor source |
| EOCIVERSION | The version, or a tag that moves, is no tag of an image, or a tag is given twice |
| EOCISMOKE | The registry has not the tested image, or crane cannot ask it |
| EOCIRETAG | The registry has the version already, at another digest |
| EOCITAG | crane cannot copy the tested image to a tag |
| EOCIMOVE | The registry has not the version, which the tags that move would point at |
