README.md

Templates Plugin

Hapi templates plugin for the Screwdriver API

Usage

Register plugin

const Hapi = require('@hapi/hapi');
const server = new Hapi.Server();
const templatesPlugin = require('./');

server.connection({ port: 3000 });

server.register({
    register: templatesPlugin,
    options: {}
}, () => {
    server.start((err) => {
        if (err) {
            throw err;
        }
        console.log('Server running at:', server.info.uri);
    });
});

Routes

Template

Get all templates

GET /templates

Can filter by template namespace: GET /templates?namespace=chef

Can search by keyword in template name, namespace, and description: GET /templates?search=screwdriver

Can list all distinct template namespaces: GET /templates?distinct=namespace

Can use additional options for sorting, pagination and get total count: GET /templates?sort=ascending&sortBy=name&page=1&count=50&getCount=true

Get a single template

You can get a single template by providing the template name and the specific version or the tag.

GET /templates/{name}/{tag} or GET /templates/{name}/{version}

Arguments

'name', 'tag' or 'version'

• name - Name of the template
• tag - Tag of the template (e.g. stable, latest, etc)
• version - Version of the template

Get a single template using templateId

You can get a single template by providing the template id.

GET /templates/{id}

Arguments

'id'

• id - Id of the template

Create a template

Creating a template will store the template data (config, name, version, description, maintainer) into the datastore.

version will be auto-bumped. For example, if mytemplate@1.0.0 already exists and the version passed in is 1.0.0, the newly created template will be version 1.0.1.

Note: This endpoint is only accessible in build scope and the permission is tied to the pipeline that first creates the template.

POST /templates

Arguments

'name', 'namespace', 'version', 'description', 'maintainer', 'labels'

• name - Name of the template
• namespace - (Optional) Namespace of the template
• version - Version of the template
• description - Description of the template
• maintainer - Maintainer of the template
• labels - Labels of the template. This field is optional and should be an array.
• config - Config of the template. This field is an object that includes steps, image, and optional secrets, environments. Similar to what's inside the job

Example payload:

{
  "name": "build",
  "namespace": "screwdriver",
  "labels": ["stable"],
  "version": "1.7.3",
  "description": "this is a template",
  "maintainer": "foo@bar.com",
  "config": {
      "steps": [{
          "echo": "echo hello"
      }]
  }
}

Delete a template

Deleting a template will delete a template and all of its associated tags and versions.

DELETE /templates/{name}

Arguments

• name - Name of the template

Delete a version

Delete the template version and all of its associated tags. If the deleted version was the last published, the API would set the latest attribute of the previous version to true.

DELETE /templates/{name}/versions/{version}

Arguments

'name', 'version'

• name - Name of the template
• version - Version of the template

Get Report of Pipelines that use a template version

GET /templates/{name}/{version}/usage/pipelines

Arguments

'name', 'version'

• name - Name of the template
• version - Version of the template

Example response

[
    {
        id: 4,
        name: 'nathom/sd-uses-template',
        scmRepo: {
          branch: 'main',
          name: 'nathom/sd-uses-template',
          url: 'https://github.com/nathom/sd-uses-template/tree/main/pipe2',
          rootDir: 'pipe2',
          private: false
        },
        lastRun: '2023-07-31T17:15:37.510Z',
        admins: { nathom: true }
    },
]

Template Tag

Template tag allows fetching on template version by tag. For example, tag mytemplate@1.1.0 as stable.

Create/Update a tag

If the template tag already exists, it will update the tag with the new version. If the template tag doesn't exist yet, this endpoint will create the tag.

Note: This endpoint is only accessible in build scope and the permission is tied to the pipeline that creates the template.

PUT /templates/{templateName}/tags/{tagName} with the following payload

• version - Exact version of the template (ex: 1.1.0)

Delete a tag

Delete the template tag. This does not delete the template itself.

Note: This endpoint is only accessible in build scope and the permission is tied to the pipeline that creates the template.

DELETE /templates/{templateName}/tags/{tagName}