circleci Submodule

Constructs

Circleci

Circleci Class to manage .circleci/config.yml. Check projen's docs for more information.

https://circleci.com/docs/2.0/configuration-reference/

Initializers

import { circleci } from 'projen'

new circleci.Circleci(project: Project, options?: CircleCiProps)

Name	Type	Description
project	projen.Project	No description.
options	CircleCiProps	No description.

---

project^Required

• Type: projen.Project

---

options^Optional

• Type: CircleCiProps

---

Methods

Name	Description
toString	Returns a string representation of this construct.
with	Applies one or more mixins to this construct.
postProjectCreation	Called once, right after postSynthesize(), only when the project is created for the first time.
postSynthesize	Called after synthesis.
preSynthesize	Called before synthesis.
projectCreation	Called once, right after synthesize(), only when the project is created for the first time.
synthesize	Synthesizes files to the project output directory.
addOrb	Add a Circleci Orb to pipeline.
addWorkflow	add new workflow to existing pipeline.

---

toString

public toString(): string

Returns a string representation of this construct.

with

public with(mixins: ...IMixin[]): IConstruct

Applies one or more mixins to this construct.

Mixins are applied in order. The list of constructs is captured at the start of the call, so constructs added by a mixin will not be visited. Use multiple with() calls if subsequent mixins should apply to added constructs.

mixins^Required

• Type: ...constructs.IMixin[]

The mixins to apply.

---

postProjectCreation

public postProjectCreation(initProject: InitProject): void

Called once, right after postSynthesize(), only when the project is created for the first time.

It does not run on later projen invocations. It only fires for projen new (or Projects.createProject). It is also skipped when post-synthesis steps are disabled, e.g. --no-post or PROJEN_DISABLE_POST. Use it for one-off setup that can be turned off by the user, like running a task to give the user immediate feedback on their new project. Order across components is not guaranteed.

initProject^Required

• Type: projen.InitProject

Details about how the project was created, e.g. its type and the original CLI args.

---

postSynthesize

public postSynthesize(): void

Called after synthesis.

Order is not guaranteed.

preSynthesize

public preSynthesize(): void

Called before synthesis.

projectCreation

public projectCreation(initProject: InitProject): void

Called once, right after synthesize(), only when the project is created for the first time.

It does not run on later projen invocations. It only fires for projen new (or Projects.createProject). Use it for deterministic, one-off file generation. Order across components is not guaranteed.

initProject^Required

• Type: projen.InitProject

Details about how the project was created, e.g. its type and the original CLI args.

---

synthesize

public synthesize(): void

Synthesizes files to the project output directory.

addOrb

public addOrb(name: string, orb: string): void

Add a Circleci Orb to pipeline.

Will throw error if the orb already exists

name^Required

• Type: string

---

orb^Required

• Type: string

---

addWorkflow

public addWorkflow(workflow: Workflow): void

add new workflow to existing pipeline.

workflow^Required

• Type: Workflow

---

Static Functions

Name	Description
isConstruct	Checks if x is a construct.
isComponent	Test whether the given construct is a component.

---

isConstruct

import { circleci } from 'projen'

circleci.Circleci.isConstruct(x: any)

Checks if x is a construct.

Use this method instead of instanceof to properly detect Construct instances, even when the construct library is symlinked.

Explanation: in JavaScript, multiple copies of the constructs library on disk are seen as independent, completely different libraries. As a consequence, the class Construct in each copy of the constructs library is seen as a different class, and an instance of one class will not test as instanceof the other class. npm install will not create installations like this, but users may manually symlink construct libraries together or use a monorepo tool: in those cases, multiple copies of the constructs library can be accidentally installed, and instanceof will behave unpredictably. It is safest to avoid using instanceof, and using this type-testing method instead.

x^Required

• Type: any

Any object.

---

isComponent

import { circleci } from 'projen'

circleci.Circleci.isComponent(x: any)

Test whether the given construct is a component.

x^Required

• Type: any

---

Properties

Name	Type	Description
node	constructs.Node	The tree node.
project	projen.Project	No description.
file	projen.YamlFile	The yaml file for the Circleci pipeline.

---

node^Required

public readonly node: Node;

• Type: constructs.Node

The tree node.

---

project^Required

public readonly project: Project;

• Type: projen.Project

---

file^Required

public readonly file: YamlFile;

• Type: projen.YamlFile

The yaml file for the Circleci pipeline.

---

Structs

CircleCiProps

Options for class {@link Circleci}.

https://circleci.com/docs/2.0/configuration-reference/

Initializer

import { circleci } from 'projen'

const circleCiProps: circleci.CircleCiProps = { ... }

Properties

Name	Type	Description
jobs	Job[]	List of Jobs to create unique steps per pipeline, e.g. json jobs: [{ identifier: "compile", docker: { image: "golang:alpine" } steps: ["checkout", run: {command: "go build ."}] }] .
orbs	{[ key: string ]: string}	Contains a map of CirclCi Orbs json orbs: { node: "circleci/node@5.0.1" slack: "circleci/slack@4.8.3" } .
setup	boolean	The setup field enables you to conditionally trigger configurations from outside the primary .circleci parent directory, update pipeline parameters, or generate customized configurations.
version	number	pipeline version.
workflows	Workflow[]	List of Workflows of pipeline, e.g. json workflows: { { identifier: "build", jobs: [{ identifier: "node/install", context: ["npm"], }] } } .

---

jobs^Optional

public readonly jobs: Job[];

• Type: Job[]

List of Jobs to create unique steps per pipeline, e.g. json jobs: [{ identifier: "compile", docker: { image: "golang:alpine" } steps: ["checkout", run: {command: "go build ."}] }] .

https://circleci.com/docs/2.0/configuration-reference/#jobs

---

orbs^Optional

public readonly orbs: {[ key: string ]: string};

• Type: {[ key: string ]: string}

Contains a map of CirclCi Orbs json orbs: { node: "circleci/node@5.0.1" slack: "circleci/slack@4.8.3" } .

---

setup^Optional

public readonly setup: boolean;

• Type: boolean

The setup field enables you to conditionally trigger configurations from outside the primary .circleci parent directory, update pipeline parameters, or generate customized configurations.

https://circleci.com/docs/2.0/configuration-reference/#setup

---

version^Optional

public readonly version: number;

• Type: number
• Default: 2.1

pipeline version.

https://circleci.com/docs/2.0/configuration-reference/#version

---

workflows^Optional

public readonly workflows: Workflow[];

• Type: Workflow[]

List of Workflows of pipeline, e.g. json workflows: { { identifier: "build", jobs: [{ identifier: "node/install", context: ["npm"], }] } } .

https://circleci.com/docs/2.0/configuration-reference/#workflows

---

Docker

Options for docker executor.

https://circleci.com/docs/2.0/configuration-reference/#docker

Initializer

import { circleci } from 'projen'

const docker: circleci.Docker = { ... }

Properties

Name	Type	Description
image	string	The name of a custom docker image to use.
auth	{[ key: string ]: string}	Authentication for registries using standard docker login credentials.
awsAuth	{[ key: string ]: string}	Authentication for AWS Elastic Container Registry (ECR).
command	string[]	The command used as pid 1 (or args for entrypoint) when launching the container.
entrypoint	string[]	The command used as executable when launching the container.
environment	{[ key: string ]: string | number | boolean}	A map of environment variable names and values.
name	string	The name the container is reachable by.
user	string	Which user to run commands as within the Docker container.

---

image^Required

public readonly image: string;

• Type: string

The name of a custom docker image to use.

---

auth^Optional

public readonly auth: {[ key: string ]: string};

• Type: {[ key: string ]: string}

Authentication for registries using standard docker login credentials.

---

awsAuth^Optional

public readonly awsAuth: {[ key: string ]: string};

• Type: {[ key: string ]: string}

Authentication for AWS Elastic Container Registry (ECR).

---

command^Optional

public readonly command: string[];

• Type: string[]

The command used as pid 1 (or args for entrypoint) when launching the container.

---

entrypoint^Optional

public readonly entrypoint: string[];

• Type: string[]

The command used as executable when launching the container.

---

environment^Optional

public readonly environment: {[ key: string ]: string | number | boolean};

• Type: {[ key: string ]: string | number | boolean}

A map of environment variable names and values.

---

name^Optional

public readonly name: string;

• Type: string

The name the container is reachable by.

By default, container services are accessible through localhost

---

user^Optional

public readonly user: string;

• Type: string

Which user to run commands as within the Docker container.

---

Filter

The branches key controls whether the current branch should have a schedule trigger created for it, where current branch is the branch containing the config.yml file with the trigger stanza. That is, a push on the main branch will only schedule a workflow for the main branch.

Branches can have the keys only and ignore which either map to a single string naming a branch. You may also use regular expressions to match against branches by enclosing them with /’s, or map to a list of such strings. Regular expressions must match the entire string.

Any branches that match only will run the job. Any branches that match ignore will not run the job. If neither only nor ignore are specified then all branches will run the job. If both only and ignore are specified the only is considered before ignore.

https://circleci.com/docs/2.0/configuration-reference/#filters

Initializer

import { circleci } from 'projen'

const filter: circleci.Filter = { ... }

Properties

Name	Type	Description
branches	FilterConfig	No description.
tags	FilterConfig	No description.

---

branches^Optional

public readonly branches: FilterConfig;

• Type: FilterConfig

---

tags^Optional

public readonly tags: FilterConfig;

• Type: FilterConfig

---

FilterConfig

set an inclusive or exclusive filter.

https://circleci.com/docs/2.0/configuration-reference/#filters

Initializer

import { circleci } from 'projen'

const filterConfig: circleci.FilterConfig = { ... }

Properties

Name	Type	Description
ignore	string[]	Either a single branch specifier, or a list of branch specifiers.
only	string[]	Either a single branch specifier, or a list of branch specifiers.

---

ignore^Optional

public readonly ignore: string[];

• Type: string[]

Either a single branch specifier, or a list of branch specifiers.

---

only^Optional

public readonly only: string[];

• Type: string[]

Either a single branch specifier, or a list of branch specifiers.

---

Job

A Workflow is comprised of one or more uniquely named jobs.

Jobs are specified in the jobs map, see Sample 2.0 config.yml for two examples of a job map. The name of the job is the key in the map, and the value is a map describing the job. Each job consists of the job’s name as a key and a map as a value. A name should be case insensitive unique within a current jobs list.

https://circleci.com/docs/2.0/configuration-reference/#job_name

Initializer

import { circleci } from 'projen'

const job: circleci.Job = { ... }

Properties

Name	Type	Description
identifier	string	name of dynamic key *.
circleciIpRanges	boolean	Enables jobs to go through a set of well-defined IP address ranges.
docker	Docker[]	No description.
environment	{[ key: string ]: string | number | boolean}	A map of environment variable names and values.
machine	Machine	No description.
macos	Macos	No description.
parallelism	number	Number of parallel instances of this job to run (default: 1).
parameters	{[ key: string ]: PipelineParameter}	Parameters for making a job explicitly configurable in a workflow.
resourceClass	string	{@link ResourceClass}.
shell	string	Shell to use for execution command in all steps.
steps	any[]	no type support here, for syntax {@see https://circleci.com/docs/2.0/configuration-reference/#steps}.
workingDirectory	string	In which directory to run the steps.

---

identifier^Required

public readonly identifier: string;

• Type: string

name of dynamic key *.

---

circleciIpRanges^Optional

public readonly circleciIpRanges: boolean;

• Type: boolean

Enables jobs to go through a set of well-defined IP address ranges.

---

docker^Optional

public readonly docker: Docker[];

• Type: Docker[]

---

environment^Optional

public readonly environment: {[ key: string ]: string | number | boolean};

• Type: {[ key: string ]: string | number | boolean}

A map of environment variable names and values.

---

machine^Optional

public readonly machine: Machine;

• Type: Machine

---

macos^Optional

public readonly macos: Macos;

• Type: Macos

---

parallelism^Optional

public readonly parallelism: number;

• Type: number

Number of parallel instances of this job to run (default: 1).

---

parameters^Optional

public readonly parameters: {[ key: string ]: PipelineParameter};

• Type: {[ key: string ]: PipelineParameter}

Parameters for making a job explicitly configurable in a workflow.

---

resourceClass^Optional

public readonly resourceClass: string;

• Type: string

{@link ResourceClass}.

---

shell^Optional

public readonly shell: string;

• Type: string

Shell to use for execution command in all steps.

Can be overridden by shell in each step

---

steps^Optional

public readonly steps: any[];

• Type: any[]

no type support here, for syntax {@see https://circleci.com/docs/2.0/configuration-reference/#steps}.

---

workingDirectory^Optional

public readonly workingDirectory: string;

• Type: string

In which directory to run the steps.

Will be interpreted as an absolute path. Default: ~/project

---

Machine

Initializer

import { circleci } from 'projen'

const machine: circleci.Machine = { ... }

Properties

Name	Type	Description
image	string	The VM image to use.
dockerLayerCaching	string	enable docker layer caching.

---

image^Required

public readonly image: string;

• Type: string

The VM image to use.

https://circleci.com/docs/2.0/configuration-reference/#available-machine-images

---

dockerLayerCaching^Optional

public readonly dockerLayerCaching: string;

• Type: string

enable docker layer caching.

https://circleci.com/docs/2.0/configuration-reference/#available-machine-images

---

Macos

CircleCI supports running jobs on macOS, to allow you to build, test, and deploy apps for macOS, iOS, tvOS and watchOS.

To run a job in a macOS virtual machine, you must add the macos key to the top-level configuration for the job and specify the version of Xcode you would like to use.

https://circleci.com/docs/2.0/configuration-reference/#macos

Initializer

import { circleci } from 'projen'

const macos: circleci.Macos = { ... }

Properties

Name	Type	Description
xcode	string	The version of Xcode that is installed on the virtual machine.

---

xcode^Required

public readonly xcode: string;

• Type: string

The version of Xcode that is installed on the virtual machine.

---

Matrix

The matrix stanza allows you to run a parameterized job multiple times with different arguments.

https://circleci.com/docs/2.0/configuration-reference/#matrix-requires-version-21

Initializer

import { circleci } from 'projen'

const matrix: circleci.Matrix = { ... }

Properties

Name	Type	Description
alias	string	An alias for the matrix, usable from another job’s requires stanza.
parameters	{[ key: string ]: string[] | number[]}	A map of parameter names to every value the job should be called with.

---

alias^Optional

public readonly alias: string;

• Type: string

An alias for the matrix, usable from another job’s requires stanza.

Defaults to the name of the job being executed

---

parameters^Optional

public readonly parameters: {[ key: string ]: string[] | number[]};

• Type: {[ key: string ]: string[] | number[]}

A map of parameter names to every value the job should be called with.

---

PipelineParameter

Parameters are declared by name under a job, command, or executor.

https://circleci.com/docs/2.0/reusing-config#using-the-parameters-declaration

Initializer

import { circleci } from 'projen'

const pipelineParameter: circleci.PipelineParameter = { ... }

Properties

Name	Type	Description
type	PipelineParameterType	The parameter type, required.
default	string | number | boolean	The default value for the parameter.
description	string	Used to generate documentation for your orb.

---

type^Required

public readonly type: PipelineParameterType;

• Type: PipelineParameterType

The parameter type, required.

---

default^Optional

public readonly default: string | number | boolean;

• Type: string | number | boolean

The default value for the parameter.

If not present, the parameter is implied to be required.

---

description^Optional

public readonly description: string;

• Type: string

Used to generate documentation for your orb.

---

Run

Used for invoking all command-line programs, taking either a map of configuration values, or, when called in its short-form, a string that will be used as both the command and name.

Run commands are executed using non-login shells by default, so you must explicitly source any dotfiles as part of the command.

Not used because type incompatible types in steps array

https://circleci.com/docs/2.0/configuration-reference/#run

Initializer

import { circleci } from 'projen'

const run: circleci.Run = { ... }

Properties

Name	Type	Description
command	string	Command to run via the shell.
background	string	Whether this step should run in the background (default: false).
environment	string	Additional environmental variables, locally scoped to command.
name	string	Title of the step to be shown in the CircleCI UI (default: full command).
noOutputTimeout	string	Elapsed time the command can run without output such as “20m”, “1.25h”, “5s”. The default is 10 minutes.
shell	string	Shell to use for execution command.
when	string	Specify when to enable or disable the step.
workingDirectory	string	In which directory to run this step.

---

command^Required

public readonly command: string;

• Type: string

Command to run via the shell.

---

background^Optional

public readonly background: string;

• Type: string

Whether this step should run in the background (default: false).

---

environment^Optional

public readonly environment: string;

• Type: string

Additional environmental variables, locally scoped to command.

---

name^Optional

public readonly name: string;

• Type: string

Title of the step to be shown in the CircleCI UI (default: full command).

---

noOutputTimeout^Optional

public readonly noOutputTimeout: string;

• Type: string

Elapsed time the command can run without output such as “20m”, “1.25h”, “5s”. The default is 10 minutes.

---

shell^Optional

public readonly shell: string;

• Type: string

Shell to use for execution command.

---

when^Optional

public readonly when: string;

• Type: string

Specify when to enable or disable the step.

---

workingDirectory^Optional

public readonly workingDirectory: string;

• Type: string

In which directory to run this step.

Will be interpreted relative to the working_directory of the job). (default: .)

---

Schedule

A workflow may have a schedule indicating it runs at a certain time.

https://circleci.com/docs/2.0/configuration-reference/#schedule

Initializer

import { circleci } from 'projen'

const schedule: circleci.Schedule = { ... }

Properties

Name	Type	Description
filters	Filter	No description.
cron	string	The cron key is defined using POSIX crontab syntax.

---

filters^Required

public readonly filters: Filter;

• Type: Filter

---

cron^Optional

public readonly cron: string;

• Type: string

The cron key is defined using POSIX crontab syntax.

---

StepRun

Execution steps for Job.

https://circleci.com/docs/2.0/configuration-reference/#steps

Initializer

import { circleci } from 'projen'

const stepRun: circleci.StepRun = { ... }

Properties

Name	Type	Description
run	Run	No description.

---

run^Optional

public readonly run: Run;

• Type: Run

---

Triggers

Specifies which triggers will cause this workflow to be executed.

Default behavior is to trigger the workflow when pushing to a branch.

https://circleci.com/docs/2.0/configuration-reference/#triggers

Initializer

import { circleci } from 'projen'

const triggers: circleci.Triggers = { ... }

Properties

Name	Type	Description
schedule	Schedule	No description.

---

schedule^Optional

public readonly schedule: Schedule;

• Type: Schedule

---

Workflow

Used for orchestrating all jobs.

Each workflow consists of the workflow name as a key and a map as a value. A name should be unique within the current config.yml. The top-level keys for the Workflows configuration are version and jobs.

https://circleci.com/docs/2.0/configuration-reference/#workflows

Initializer

import { circleci } from 'projen'

const workflow: circleci.Workflow = { ... }

Properties

Name	Type	Description
identifier	string	name of dynamic key *.
jobs	WorkflowJob[]	No description.
triggers	Triggers[]	No description.
when	any	when is too dynamic to be casted to interfaces.

---

identifier^Required

public readonly identifier: string;

• Type: string

name of dynamic key *.

---

jobs^Optional

public readonly jobs: WorkflowJob[];

• Type: WorkflowJob[]

---

triggers^Optional

public readonly triggers: Triggers[];

• Type: Triggers[]

---

when^Optional

public readonly when: any;

• Type: any

when is too dynamic to be casted to interfaces.

Check Docu as reference

https://circleci.com/docs/2.0/configuration-reference/#logic-statement-examples

---

WorkflowJob

A Job is part of Workflow.

A Job can be created with {@link Job} or it can be provided by the orb

https://circleci.com/docs/2.0/configuration-reference/#jobs-in-workflow

Initializer

import { circleci } from 'projen'

const workflowJob: circleci.WorkflowJob = { ... }

Properties

Name	Type	Description
identifier	string	name of dynamic key *.
context	string[]	The name of the context(s).
filters	Filter	Job Filters can have the key branches or tags.
matrix	Matrix	No description.
name	string	A replacement for the job name.
orbParameters	{[ key: string ]: string | number | boolean}	Parameters passed to job when referencing a job from orb.
requires	string[]	A list of jobs that must succeed for the job to start.
type	JobType	A job may have a type of approval indicating it must be manually approved before downstream jobs may proceed.

---

identifier^Required

public readonly identifier: string;

• Type: string

name of dynamic key *.

---

context^Optional

public readonly context: string[];

• Type: string[]

The name of the context(s).

The initial default name is org-global. Each context name must be unique.

---

filters^Optional

public readonly filters: Filter;

• Type: Filter

Job Filters can have the key branches or tags.

---

matrix^Optional

public readonly matrix: Matrix;

• Type: Matrix

---

name^Optional

public readonly name: string;

• Type: string

A replacement for the job name.

Useful when calling a job multiple times

---

orbParameters^Optional

public readonly orbParameters: {[ key: string ]: string | number | boolean};

• Type: {[ key: string ]: string | number | boolean}

Parameters passed to job when referencing a job from orb.

---

requires^Optional

public readonly requires: string[];

• Type: string[]

A list of jobs that must succeed for the job to start.

---

type^Optional

public readonly type: JobType;

• Type: JobType

A job may have a type of approval indicating it must be manually approved before downstream jobs may proceed.

---

Enums

JobType

A job may have a type of approval indicating it must be manually approved before downstream jobs may proceed.

https://circleci.com/docs/2.0/configuration-reference/#type

Members

Name	Description
APPROVAL	No description.

---

APPROVAL

---

JobWhen

Specify when to enable or disable the step.

https://circleci.com/docs/2.0/configuration-reference/#steps

Members

Name	Description
ALWAYS	No description.
ON_SUCCESS	No description.
ON_FAIL	No description.

---

ALWAYS

---

ON_SUCCESS

---

ON_FAIL

---

PipelineParameterType

Pipeline parameter types.

https://circleci.com/docs/2.0/reusing-config#parameter-syntax

Members

Name	Description
STRING	No description.
BOOLEAN	No description.
INTEGER	No description.
ENUM	No description.

---

STRING

---

BOOLEAN

---

INTEGER

---

ENUM

---

ResourceClass

The resource_class feature allows configuring CPU and RAM resources for each job.

Different resource classes are available for different executors, as described in the tables below.

https://circleci.com/docs/2.0/configuration-reference/#resourceclass

Members

Name	Description
SMALL	No description.
MEDIUM	No description.
MEDIUM_PLUS	No description.
LARGE_X	No description.
LARGE_2X	No description.
LARGE_2X_PLUS	No description.

---

SMALL

---

MEDIUM

---

MEDIUM_PLUS

---

LARGE_X

---

LARGE_2X

---

LARGE_2X_PLUS

---