TypeScript SDK

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.

On this page