build Submodule

Constructs

BuildWorkflow

Initializers

import { build } from 'projen'

new build.BuildWorkflow(project: Project, options: BuildWorkflowOptions)

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

---

project^Required

• Type: projen.Project

---

options^Required

• Type: BuildWorkflowOptions

---

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.
addPostBuildJob	Adds another job to the build workflow which is executed after the build job succeeded.
addPostBuildJobCommands	Run a sequence of commands as a job within the build workflow which is executed after the build job succeeded.
addPostBuildJobTask	Run a task as a job within the build workflow which is executed after the build job succeeded.
addPostBuildSteps	Adds steps that are executed after the build.

---

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.

addPostBuildJob

public addPostBuildJob(id: string, job: Job): void

Adds another job to the build workflow which is executed after the build job succeeded.

Jobs are executed only if the build did NOT self mutate. If the build self-mutate, the branch will either be updated or the build will fail (in forks), so there is no point in executing the post-build job.

id^Required

• Type: string

The id of the new job.

---

job^Required

• Type: projen.github.workflows.Job

The job specification.

---

addPostBuildJobCommands

public addPostBuildJobCommands(id: string, commands: string[], options?: AddPostBuildJobCommandsOptions): void

Run a sequence of commands as a job within the build workflow which is executed after the build job succeeded.

Jobs are executed only if the build did NOT self mutate. If the build self-mutate, the branch will either be updated or the build will fail (in forks), so there is no point in executing the post-build job.

id^Required

• Type: string

---

commands^Required

• Type: string[]

---

options^Optional

• Type: AddPostBuildJobCommandsOptions

Specify tools and other options.

---

addPostBuildJobTask

public addPostBuildJobTask(task: Task, options?: AddPostBuildJobTaskOptions): void

Run a task as a job within the build workflow which is executed after the build job succeeded.

The job will have access to build artifacts and will install project dependencies in order to be able to run any commands used in the tasks.

Jobs are executed only if the build did NOT self mutate. If the build self-mutate, the branch will either be updated or the build will fail (in forks), so there is no point in executing the post-build job.

task^Required

• Type: projen.Task

---

options^Optional

• Type: AddPostBuildJobTaskOptions

Specify tools and other options.

---

addPostBuildSteps

public addPostBuildSteps(steps: ...JobStep[]): void

Adds steps that are executed after the build.

steps^Required

• Type: ...projen.github.workflows.JobStep[]

The job steps.

---

Static Functions

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

---

isConstruct

import { build } from 'projen'

build.BuildWorkflow.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 { build } from 'projen'

build.BuildWorkflow.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.
buildJobIds	string[]	Returns a list of job IDs that are part of the build.
name	string	Name of generated github workflow.
workflow	projen.github.GithubWorkflow	The underlying GitHub Actions workflow.

---

node^Required

public readonly node: Node;

• Type: constructs.Node

The tree node.

---

project^Required

public readonly project: Project;

• Type: projen.Project

---

buildJobIds^Required

public readonly buildJobIds: string[];

• Type: string[]

Returns a list of job IDs that are part of the build.

---

name^Required

public readonly name: string;

• Type: string

Name of generated github workflow.

---

workflow^Required

public readonly workflow: GithubWorkflow;

• Type: projen.github.GithubWorkflow

The underlying GitHub Actions workflow.

---

Structs

AddPostBuildJobCommandsOptions

Options for BuildWorkflow.addPostBuildJobCommands.

Initializer

import { build } from 'projen'

const addPostBuildJobCommandsOptions: build.AddPostBuildJobCommandsOptions = { ... }

Properties

Name	Type	Description
checkoutRepo	boolean	Check out the repository at the pull request branch before commands are run.
installDeps	boolean	Install project dependencies before running commands. checkoutRepo must also be set to true.
runsOn	string[]	Github Runner selection labels.
runsOnGroup	projen.GroupRunnerOptions	Github Runner Group selection options.
tools	projen.github.workflows.Tools	Tools that should be installed before the commands are run.

---

checkoutRepo^Optional

public readonly checkoutRepo: boolean;

• Type: boolean
• Default: false

Check out the repository at the pull request branch before commands are run.

---

installDeps^Optional

public readonly installDeps: boolean;

• Type: boolean
• Default: false

Install project dependencies before running commands. checkoutRepo must also be set to true.

Currently only supported for NodeProject.

---

runsOn^Optional

public readonly runsOn: string[];

• Type: string[]
• Default: ["ubuntu-latest"]

Github Runner selection labels.

---

runsOnGroup^Optional

public readonly runsOnGroup: GroupRunnerOptions;

• Type: projen.GroupRunnerOptions

Github Runner Group selection options.

---

tools^Optional

public readonly tools: Tools;

• Type: projen.github.workflows.Tools

Tools that should be installed before the commands are run.

---

AddPostBuildJobTaskOptions

Options for BuildWorkflow.addPostBuildJobTask.

Initializer

import { build } from 'projen'

const addPostBuildJobTaskOptions: build.AddPostBuildJobTaskOptions = { ... }

Properties

Name	Type	Description
runsOn	string[]	Github Runner selection labels.
runsOnGroup	projen.GroupRunnerOptions	Github Runner Group selection options.
tools	projen.github.workflows.Tools	Tools that should be installed before the task is run.

---

runsOn^Optional

public readonly runsOn: string[];

• Type: string[]
• Default: ["ubuntu-latest"]

Github Runner selection labels.

---

runsOnGroup^Optional

public readonly runsOnGroup: GroupRunnerOptions;

• Type: projen.GroupRunnerOptions

Github Runner Group selection options.

---

tools^Optional

public readonly tools: Tools;

• Type: projen.github.workflows.Tools

Tools that should be installed before the task is run.

---

BuildWorkflowCommonOptions

Initializer

import { build } from 'projen'

const buildWorkflowCommonOptions: build.BuildWorkflowCommonOptions = { ... }

Properties

Name	Type	Description
env	{[ key: string ]: string}	Build environment variables.
name	string	Name of the buildfile (e.g. "build" becomes "build.yml").
permissions	projen.github.workflows.JobPermissions	Permissions granted to the build job To limit job permissions for contents, the desired permissions have to be explicitly set, e.g.: { contents: JobPermission.NONE }.
preBuildSteps	projen.github.workflows.JobStep[]	Steps to execute before the build.
workflowTriggers	projen.github.workflows.Triggers	Build workflow triggers.

---

env^Optional

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

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

Build environment variables.

---

name^Optional

public readonly name: string;

• Type: string
• Default: "build"

Name of the buildfile (e.g. "build" becomes "build.yml").

---

permissions^Optional

public readonly permissions: JobPermissions;

• Type: projen.github.workflows.JobPermissions
• Default: { contents: JobPermission.WRITE }

Permissions granted to the build job To limit job permissions for contents, the desired permissions have to be explicitly set, e.g.: { contents: JobPermission.NONE }.

---

preBuildSteps^Optional

public readonly preBuildSteps: JobStep[];

• Type: projen.github.workflows.JobStep[]
• Default: []

Steps to execute before the build.

---

workflowTriggers^Optional

public readonly workflowTriggers: Triggers;

• Type: projen.github.workflows.Triggers
• Default: "{ pullRequest: {}, workflowDispatch: {} }"

Build workflow triggers.

---

BuildWorkflowOptions

Initializer

import { build } from 'projen'

const buildWorkflowOptions: build.BuildWorkflowOptions = { ... }

Properties

Name	Type	Description
env	{[ key: string ]: string}	Build environment variables.
name	string	Name of the buildfile (e.g. "build" becomes "build.yml").
permissions	projen.github.workflows.JobPermissions	Permissions granted to the build job To limit job permissions for contents, the desired permissions have to be explicitly set, e.g.: { contents: JobPermission.NONE }.
preBuildSteps	projen.github.workflows.JobStep[]	Steps to execute before the build.
workflowTriggers	projen.github.workflows.Triggers	Build workflow triggers.
buildTask	projen.Task	The task to execute in order to build the project.
artifactsDirectory	string	A name of a directory that includes build artifacts.
buildRunsOn	string[]	Github Runner selection labels.
containerImage	string	The container image to use for builds.
gitIdentity	projen.github.GitIdentity	Git identity to use for the workflow.
mutableBuild	boolean	Automatically update files modified during builds to pull-request branches.
mutableInstall	boolean	Perform a mutable (non-frozen) install during builds.
postBuildSteps	projen.github.workflows.JobStep[]	Steps to execute after build.
runsOn	string[]	Github Runner selection labels.
runsOnGroup	projen.GroupRunnerOptions	Github Runner Group selection options.

---

env^Optional

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

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

Build environment variables.

---

name^Optional

public readonly name: string;

• Type: string
• Default: "build"

Name of the buildfile (e.g. "build" becomes "build.yml").

---

permissions^Optional

public readonly permissions: JobPermissions;

• Type: projen.github.workflows.JobPermissions
• Default: { contents: JobPermission.WRITE }

Permissions granted to the build job To limit job permissions for contents, the desired permissions have to be explicitly set, e.g.: { contents: JobPermission.NONE }.

---

preBuildSteps^Optional

public readonly preBuildSteps: JobStep[];

• Type: projen.github.workflows.JobStep[]
• Default: []

Steps to execute before the build.

---

workflowTriggers^Optional

public readonly workflowTriggers: Triggers;

• Type: projen.github.workflows.Triggers
• Default: "{ pullRequest: {}, workflowDispatch: {} }"

Build workflow triggers.

---

buildTask^Required

public readonly buildTask: Task;

• Type: projen.Task

The task to execute in order to build the project.

---

artifactsDirectory^Optional

public readonly artifactsDirectory: string;

• Type: string
• Default: "dist"

A name of a directory that includes build artifacts.

---

buildRunsOn^Optional

public readonly buildRunsOn: string[];

• Type: string[]
• Default: runsOn

Github Runner selection labels.

---

containerImage^Optional

public readonly containerImage: string;

• Type: string
• Default: the default workflow container

The container image to use for builds.

---

gitIdentity^Optional

public readonly gitIdentity: GitIdentity;

• Type: projen.github.GitIdentity
• Default: default GitHub Actions user

Git identity to use for the workflow.

---

mutableBuild^Optional

public readonly mutableBuild: boolean;

• Type: boolean
• Default: true

Automatically update files modified during builds to pull-request branches.

This means that any files synthesized by projen or e.g. test snapshots will always be up-to-date before a PR is merged.

Implies that PR builds do not have anti-tamper checks.

This is enabled by default only if githubTokenSecret is set. Otherwise it is disabled, which implies that file changes that happen during build will not be pushed back to the branch.

---

mutableInstall^Optional

public readonly mutableInstall: boolean;

• Type: boolean
• Default: value of mutableBuild

Perform a mutable (non-frozen) install during builds.

This will update the package lockfile during installs, which is useful when build steps modify dependencies. Set to false to use frozen lockfile installs even when mutableBuild is enabled.

---

postBuildSteps^Optional

public readonly postBuildSteps: JobStep[];

• Type: projen.github.workflows.JobStep[]
• Default: []

Steps to execute after build.

---

runsOn^Optional

public readonly runsOn: string[];

• Type: string[]
• Default: ["ubuntu-latest"]

Github Runner selection labels.

---

runsOnGroup^Optional

public readonly runsOnGroup: GroupRunnerOptions;

• Type: projen.GroupRunnerOptions

Github Runner Group selection options.

---