Skip to content

Contracts and adapter NPM packages for various cloud build services

License

Notifications You must be signed in to change notification settings

AArnott/cloudbuild-task

Repository files navigation

cloudbuild-task

These NPM packages are typed with TypeScript MIT license

GitHub Actions status

This repo contains the source code for several NPM packages that allow for development of CI cloud build system tasks using a shared API abstraction. This abstraction allows the bulk of a task's code to be written once and run in GitHub Actions, Azure Pipelines, or locally on a dev box.

Installation

This repo creates NPM packages.

This package defines the abstraction, and is what the core of your task should depend on:

cloudbuild-task-contracts

These other packages are what your CI-specific task front-ends should depend on:

CI Package
Azure Pipelines cloudbuild-task-azp
GitHub Actions cloudbuild-task-github-actions
Local runner cloudbuild-task-local

Adapters for other CI systems may exist that are built elsewhere. If you create or know of one, please let us know so we can help direct people to it.

Consuming

Consumption of these packages is targeted at folks who write tasks for multiple cloud build systems (e.g. Azure Pipelines and GitHub Actions) and want to share code as much as possible between these task implementations.

These packages include TypeScript typings for your convenience.

Your task's core package

Design your task as a 'core' NPM package that contains most of your build logic. This should depend on the cloudbuild-task-contracts NPM package. It should not depend on any cloud build specific package.

This core package should export a class or method that accepts a CloudTask. All cloud build interactions should go through this abstraction. This CloudTask interface provides functionality such as:

  1. logging
  2. spawning tools
  3. getting task inputs
  4. looking up pull request, build or repo metadata.

...and more.

So for example, this core task package would look up a variable and log an error including its value and fail the task run:

import { CloudTask } from 'cloudbuild-task-contracts';

export function run(cloudTask: CloudTask) {
  const name = cloudTask.inputs.getInput('name');
  cloudTask.log.error(`That is not an acceptable name: ${name}.`);
  cloudTask.result.setFailed('Invalid input parameter.');
}

Multiple front-end tasks consume your core package

For each cloud build system you write a task for, follow their documentation to do so. Instead of writing the core logic of your task multiple times, consume the core task NPM package you wrote earlier. Activate the core task by passing in an instance of CloudTask that is specific to this cloud build system.

For an Azure Pipelines task, you might code it up like this:

import { factory } from 'cloudbuild-task-azp';
import { run } from './MyTask';

run(factory);

While for a GitHub Actions task it is nearly identical. The only change is the package you get the factory from:

import { factory } from 'cloudbuild-task-github-actions';
import { run } from './MyTask';

run(factory);

Contributing

Want to contribute a feature or fix to an existing adapter? Or perhaps add a new adapter for another cloud build system? We'd love to have your help.

See our contributing guide.

About

Contracts and adapter NPM packages for various cloud build services

Resources

License

Stars

Watchers

Forks

Packages

 
 
 

Contributors 4

  •  
  •  
  •  
  •