Templates
Create, build and inspect sandbox templates with @tektona/sdk.
tek.template manages templates, their builds, tags and versions.
A template belongs to a project by default. The calls use the client's default
org and project, and every call can override them. Pass { scope: 'org' }
for an org template; it needs only org.
A call that takes a template name also takes the reference that list returns:
org/<name> for an org template, project/<name> for a project template, and
tektona/<name> for a platform template. A platform template is read-only:
get, listTags, getTag, listVersions and getVersion work, and update
and delete throw an InvalidArgumentError.
List
list returns one Page; listAll auto-pages. A
project list also contains the org templates and the tektona/ templates, so
read scope on each item:
const page = await tek.template.list({ q: 'go' });
for await (const t of tek.template.listAll()) console.log(t.reference, t.scope);Get
const t = await tek.template.get('go-dev');
const orgTemplate = await tek.template.get('org/go-dev');
const desktop = await tek.template.get('tektona/desktop');Create
A new template has no versions. Start a build to make one:
await tek.template.create({
metadata: { name: 'go-dev', display_name: 'Go dev', description: 'Go 1.24' },
});Update
update replaces the display name and the description. A field that you leave
out is cleared. The call makes no version and starts no build:
await tek.template.update('go-dev', {
display_name: 'Go development',
description: 'Go 1.24',
});Delete
delete removes the template with all of its versions and tags, and cancels a
pending or running build. It resolves to the number of build records the
template had. Each one stays readable by its build id for 90 days. The API refuses the
delete with a ConflictError while a sandbox uses one of the versions. A
template that is not in the scope of the call gives a NotFoundError. For an
org template from a project list, pass its reference: delete('org/go-dev').
const { builds } = await tek.template.delete('go-dev');Build
build queues a build and resolves before the build finishes. Read the result
with getBuild until status is succeeded, failed or cancelled. On
success, tag points at the new version.
let build = await tek.template.build({
template: 'go-dev',
tag: 'stable',
build: { image: 'ghcr.io/acme/go-dev:1.4.0' },
});
while (!['succeeded', 'failed', 'cancelled'].includes(build.status)) {
await new Promise((r) => setTimeout(r, 5_000));
build = await tek.template.getBuild(build.id);
}listBuilds lists the builds of the project or org, newest first. With
scope: 'org', the list shows only the builds of org templates. Pass
template to show the builds of one template:
const builds = await tek.template.listBuilds({ template: 'go-dev', limit: 10 });Build log
buildLogs reads one page of a build log. Pass direction: 'backward' to start
at the end, where a failed build shows its error. Pass level to show only one
level.
const page = await tek.template.buildLogs(build.id, { direction: 'backward', limit: 50 });
for (const line of page.items) console.log(line.step_index, line.level, line.message);Tags and versions
const tags = await tek.template.listTags('go-dev');
const stable = await tek.template.getTag('go-dev', 'stable'); // { tag, version }
const versions = await tek.template.listVersions('go-dev', { state: 'active', tagged: false });
const version = await tek.template.getVersion('go-dev', stable.version.id);To list every page, wrap the call in paginate:
import { paginate } from '@tektona/sdk';
for await (const v of paginate((cursor) => tek.template.listVersions('go-dev', { cursor }))) {
console.log(v.id);
}The SDK does not wrap the other template calls yet: activate, archive, cancel a
build, move or delete a tag, prune or delete versions, and the lifecycle
settings. Call them through the generated export.