Skip to content

Latest commit

 

History

History
410 lines (271 loc) · 12.1 KB

README.md

File metadata and controls

410 lines (271 loc) · 12.1 KB
Raw

Pipelines Plugin

Hapi pipelines plugin for the Screwdriver API

Usage

Register plugin

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

server.connection({ port: 3000 });

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

Routes

Get all pipelines

page, count, sort, sortBy, search, and configPipelineId optional search will search for a pipeline with a name containing the search keyword in the scmRepo field

GET /pipelines?page={pageNumber}&count={countNumber}&configPipelineId={configPipelineId}&search={search}

Need to have array format for ids to only return pipelines with matching ids GET /pipelines?search={search}&ids[]=12345&ids[]=55555

Get single pipeline

GET /pipelines/{id}

Create a pipeline

Create a pipeline and create a job called 'main'

POST /pipelines

Arguments

  • checkoutUrl - Source code URL for the application. For a git-based repository, it is typically the SSH endpoint and the branch name, separated by a octothorpe. Must be unique.
  • rootDir - Optional Root directory where the source code lives. Default to empty string.

Example payload:

{
  "checkoutUrl": "[email protected]:screwdriver-cd/data-model.git#master",
  "rootDir": "src/app/component"
}

Update a pipeline

You can update the checkoutUrl of a pipeline.

PUT /pipelines/{id}

Arguments

  • checkoutUrl - Source code URL for the application. For a git-based repository, it is typically the SSH endpoint and the branch name, separated by a octothorpe. Must be unique.
  • rootDir - Optional Root directory where the source code lives. Default to empty string.

Example payload:

{
  "checkoutUrl": "[email protected]:screwdriver-cd/data-model.git#master",
  "rootDir": "src/app/component"
}

Delete a pipeline

DELETE /pipelines/{id}

Synchronize a pipeline

  • Synchronize the pipeline by looking up latest screwdriver.yaml
  • Create, update, or disable jobs if necessary.
  • Store/update the pipeline workflowGraph

POST /pipelines/{id}/sync

Synchronize webhooks

  • Synchronize webhooks for the pipeline
  • Add or update webhooks if necessary

POST /pipelines/{id}/sync/webhooks

Synchronize pull requests

  • Synchronize pull requests for the pipeline
  • Add or update pull request jobs if necessary

POST /pipelines/{id}/sync/pullrequests

Get all pipeline events

Query Params:

  • page - Optional Specific page of the set to return
  • count - Optional Number of items per page
  • sort - Optional Sort rangekey by ascending or descending (default descending)
  • sortBy - Optional Field to sort by
  • type - Optional Get pipeline or pr events (default pipeline)
  • prNum - Optional Return only PR events of specified PR number
  • sha - Optional Search sha and configPipelineSha for events
  • id - Optional Fetch specific event ID; alternatively can use greater than(gt:) or less than(lt:) prefix

GET /pipelines/{id}/events?page={pageNumber}&count={countNumber}&sort={sort}&type={type}&prNum={prNumber}&sha={sha}

GET /pipelines/{id}/events?id=gt:{eventId}&count={countNumber} (greater than eventId)

GET /pipelines/{id}/events?id=lt:{eventId}&count={countNumber}&sort=ascending (less than eventId)

Get all pipeline builds

page, count, sort, latest, sortBy, fetchSteps, readOnly, and groupEventId are optional When latest=true and groupEventId is set, only latest builds in a pipeline based on groupEventId will be returned. The latest parameter must be used in conjunction with the groupEventId.

GET /pipelines/{id}/builds?page={pageNumber}&count={countNumber}&sort={sort}&latest=true&groupEventId={groupEventId}&sortBy={sortBy}&fetchSteps=false&readOnly=false

Get all jobs (including pull requests jobs)

archived is optional and has a default value of false, which makes the endpoint not return archived jobs (e.g. closed pull requests)

Arguments:

  • archived - Optional and has a default value of false, which makes the endpoint not return archived jobs (e.g. closed pull requests)
  • type - Optional and can be set to pr or pipeline to only return PR jobs or non-PR jobs
  • jobName - Optional and can be set to only return only a single job

GET /pipelines/{id}/jobs?archived={boolean}&type={type}&jobName={jobName}

Get Pipeline Admin

GET /pipelines/{id}/admin

Get all triggers

GET /pipelines/{id}/triggers

Get all stages for a single pipeline

page, count, sort, sortBy, and name optional

GET /pipelines/{id}/stages?page={pageNumber}&count={countNumber}&sort={sort}&name={stageName}

Get all pipeline secrets

GET /pipelines/{id}/secrets

Get event metrics for a single pipeline

GET /pipelines/{id}/metrics

GET /pipelines/{id}/metrics?startTime=2019-02-01T12:00:00.000Z

GET /pipelines/{id}/metrics?aggregateInterval=week

Need to have array format for downtimeJobs and downtimeStatuses GET /pipelines/{id}/metrics?downtimeJobs[]=123&downtimeJobs[]=456&downtimeStatuses[]=ABORTED

Start all child pipelines belong to this pipeline

  • Start all child pipelines belong to this config pipeline all at once

POST /pipelines/{id}/startall

Create a pipeline token

POST /pipelines/{id}/token

Get all pipeline tokens

GET /pipelines/{id}/tokens

Update a pipeline token

PUT /pipelines/{pipelineId}/tokens/{tokenId}

Refresh a pipeline token

PUT /pipelines/{pipelineId}/tokens/{tokenId}/refresh

Delete a pipeline token

DELETE /pipelines/{pipelineId}/tokens/{tokenId}

Delete all pipeline tokens belong to this pipeline

DELETE /pipelines/{pipelineId}/tokens

Get latest build for a single job

GET /pipelines/{id}/jobs/{jobName}/latestBuild

Can search by build status GET /pipelines/{id}/jobs/{jobName}/latestBuild?status=SUCCESS

Deletes cache for the given scope and cacheId for pipeline

DELETE /pipelines/${id}/caches?scope={scope}&cacheId={id}

Path Params:

  • id - The id of the pipeline

Query Params:

  • scope - Scope of the cache supporting values pipelines|jobs|events
  • cacheId - The id of the cache - pipelineId/jobId/eventId

Configuration - Reads the ecosystem

    ecosystem:
        store: 'https://store.screwdriver.cd'
        queue: 'https://queue.screwdriver.cd'
        cache:
            strategy: 's3'

Route requests to queue service api if strategy is disk and to store api if strategy is s3

Open pull request

POST /pipelines/{id}/openPr

Access to Factory methods

The server supplies factories to plugins in the form of server settings:

// handler pipelinePlugin.js
handler: async (request, h) => {
    const factory = request.server.app.pipelineFactory;

    // ...
}

Pipeline Templates

Get all pipeline templates

GET /pipeline/templates

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

Get all versions for a pipeline template

GET /pipeline/templates/{namespace}/{name}/versions

Can use additional options for sorting, pagination and count: GET /pipeline/templates/{namespace}/{name}/versions?sort=ascending&page=1&count=50

Create a pipeline template

Creating a template will store the template meta (name, namespace, maintainer, latestVersion, trustedSinceVersion, pipelineId) and template version (description, version, config, createTime, templateId) into the datastore.

version will be auto-bumped. For example, if [email protected] already exists and the version passed in is 1.0.0, the newly created template will be version 1.0.1.

POST /pipeline/template

Arguments

'name', 'namespace', 'version', 'description', 'maintainer', 'config'

  • name - Name of the template
  • namespace - Namespace of the template
  • version - Version of the template
  • description - Description of the template
  • maintainer - Maintainer of the template
  • config - Config of the template. This field is an object that includes steps, image, and optional secrets, environments. Similar to what's inside the pipeline

Example payload:

{
    "name": "example-template",
    "namespace": "my-namespace",
    "version": "1.3.1",
    "description": "An example template",
    "maintainer": "[email protected]",
    "config": {
        "steps": [{
            "echo": "echo hello"
        }]
    }
}
Validate a pipeline template

Validate a pipeline template and return a JSON containing the boolean property ‘valid’ indicating if the template is valid or not

POST /pipeline/template/validate

Arguments

'name', 'namespace', 'version', 'description', 'maintainer', 'config'

  • name - Name of the template
  • namespace - Namespace of the template
  • version - Version of the template
  • description - Description of the template
  • maintainer - Maintainer of the template
  • config - Config of the template. This field is an object that includes steps, image, and optional secrets, environments. Similar to what's inside the pipeline

Example payload:

{
    "name": "example-template",
    "namespace": "my-namespace",
    "version": "1.3.1",
    "description": "An example template",
    "maintainer": "[email protected]",
    "config": {
        "steps": [{
            "echo": "echo hello"
        }]
    }
}

Get a pipeline template by namespace and name

GET /pipeline/template/{namespace}/{name}

Get a specific pipeline template by id

GET /pipeline/template/{id}

Get version of a pipeline template by name, namespace, version or tag

GET /pipeline/template/{namespace}/{name}/{versionOrTag}

Template Tag

Template tag allows fetching on template version by tag. For example, tag [email protected] as stable.

Get all tags for a pipeline template by name, namespace

GET /pipeline/templates/{namespace}/{name}/tags

Can use additional options for sorting, pagination and count: GET /pipeline/templates/{namespace}/{name}/tags?sort=ascending&sortBy=name&page=1&count=50

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 pipeline template

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

DELETE /pipeline/templates/{namespace}/{name}

Arguments
  • name - Name of the template
Delete a pipeline template version

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

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

Arguments

'namespace', 'name', 'version'

  • namespace - Namespace of the template
  • name - Name of the template
  • version - Version of the template
Delete a pipeline template 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 /pipeline/templates/{namespace}/{name}/tags/{tag}

Arguments

'namespace', 'name', 'tag'

  • namespace - Namespace of the template
  • name - Name of the template
  • tag - Tag name of the template
Update a pipeline template's trusted property

Update a pipeline template's trusted property

PUT /pipeline/templates/{namespace}/{name}/trusted

Arguments

'namespace', 'name'

  • namespace - Namespace of the template
  • name - Name of the template

Example payload:

{
    "trusted": true
}