@dotcom-tool-kit/circleci

This plugin manages Tool Kit commands that are run from CircleCI workflows, via a Tool Kit Hook that automatically manages .circleci/config.yml. It also exposes state from the CircleCI environment for other plugins to consume generically.

This plugin will be installed as a dependency of the containerised-app-with-assets, containerised-app, component, circleci-deploy, and circleci-npm plugins so you do not need to install it separately if you are using any of those plugins.

Installation

Install @dotcom-tool-kit/circleci as a devDependency in your app:

``sh
npm install --save-dev @dotcom-tool-kit/circleci
`

Add the plugin to your Tool Kit configuration:

`yaml
plugins:
- '@dotcom-tool-kit/circleci'
`

And install this plugin's hooks:

`sh
npx dotcom-tool-kit --install
`




Hooks

$3

This hook automatically manages .circleci/config.yml in your repo to provide configuration for CircleCI workflows to run Tool Kit commands and tasks.

Options provided in your repository's .toolkitrc.yml for this hook are merged with any Tool Kit plugin that also provides options for the hook.

Unless they conflict, your options are appended to options from plugins, allowing you to define custom CircleCI jobs and workflows in your repository that work alongside those from plugins.
#### Hook options

| Property | Description | Type |
| :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| executors | an array of additional CircleCI executors to output in the generated config. | _Array of objects:_


• name: string
• image: string

|
| jobs | an array of additional CircleCI jobs to output in the generated config. these are used for running Tool Kit commands. for running arbitrary shell commands, use custom. | _Array of objects:_


• name: string
• command: string
• workspace: _Object with properties:_
  • persist: boolean
  • attach: boolean
• steps: _Object with properties:_
  • pre: Array
  • post: Array
• splitIntoMatrix: boolean
• environment: Record
• custom: _Object with dynamic keys of type_ string _and values of type_ unknown (_optional & nullable_)

|
| workflows | an array of additional CircleCI workflows to output in the generated config. these reference jobs defined in the jobs option. | _Array of objects:_


• name: string
• jobs: _Array of objects:_

  • name: string
  • requires: Array
  • splitIntoMatrix: boolean
  • runOnRelease: boolean
  • custom: _Object with dynamic keys of type_ string _and values of type_ unknown (_optional & nullable_)
• runOnRelease: boolean
• custom: _Object with dynamic keys of type_ string _and values of type_ unknown (_optional & nullable_)

|
| custom | arbitrary additional CircleCI configuration that will be merged into the Tool Kit-generated config. | _Object with dynamic keys of type_ string _and values of type_ unknown (_optional & nullable_) |
| disableBaseConfig | set to true to omit the Tool Kit CircleCI boilerplate. should be used along with custom to provide your own boilerplate. | boolean |

_All properties are optional._

Plugin-wide options

$3

| Property | Description | Type | Default |
| :----------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------------------------- | :-------------------------- |
| cimgNodeVersions | list of CircleCI Node.js image versions to use. if more than one is provided, a matrix build will be generated in your CircleCI config. | Array | ["20.19-browsers"] |
| tagFilter | the regular expression used to match tags for jobs that should run on tag workflows. by default, matches tags that look like v1.2.3; if your releases use a different tag format, change this option to match your tags. set to false to prevent running workflows on tags, for example if your repo doesn't do versioned releases. | string \| false | '/^v\d+\.\d+\.\d+(-.+)?/' |
| checkoutMethod | whether to checkout the full git repository or blobless (without files unrelated to the main commit.) blobless checkouts are the default and are faster, though some projects may encounter issues if they rely on inspecting files in the git history. if you see logs like The authenticity of host 'github.com (140.82.113.4)' can't be established. you should try enabling full checkouts. | 'full' \| 'blobless' | |
| orbDevVersion | set this option to use a development version of the Tool Kit CircleCI orb in the generated config | string (_regex: /^dev:/`_) | |

_All properties are optional._