Skip to main content

build Submodule

Constructs ​

BuildWorkflow ​

Initializers ​

import { build } from 'projen'

new build.BuildWorkflow(project: Project, options: BuildWorkflowOptions)
NameTypeDescription
project
projen.ProjectNo description.
options
BuildWorkflowOptions
No description.
projectRequired ​
  • Type: projen.Project
optionsRequired ​

Methods ​

NameDescription
toString
Returns a string representation of this construct.
postSynthesize
Called after synthesis.
preSynthesize
Called before synthesis.
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.

postSynthesize ​
public postSynthesize(): void

Called after synthesis.

Order is not guaranteed.

preSynthesize ​
public preSynthesize(): void

Called before synthesis.

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.

idRequired ​
  • Type: string

The id of the new job.

jobRequired ​
  • 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.

idRequired ​
  • Type: string
commandsRequired ​
  • Type: string[]
optionsOptional ​

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.

taskRequired ​
  • Type: projen.Task
optionsOptional ​

Specify tools and other options.

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

Adds steps that are executed after the build.

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

The job steps.

Static Functions ​

NameDescription
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.

xRequired ​
  • Type: any

Any object.

isComponent ​
import { build } from 'projen'

build.BuildWorkflow.isComponent(x: any)

Test whether the given construct is a component.

xRequired ​
  • Type: any

Properties ​

NameTypeDescription
node
constructs.NodeThe tree node.
project
projen.ProjectNo description.
buildJobIds
string[]Returns a list of job IDs that are part of the build.
name
stringName of generated github workflow.
nodeRequired ​
public readonly node: Node;
  • Type: constructs.Node

The tree node.

projectRequired ​
public readonly project: Project;
  • Type: projen.Project
buildJobIdsRequired ​
public readonly buildJobIds: string[];
  • Type: string[]

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

nameRequired ​
public readonly name: string;
  • Type: string

Name of generated github workflow.

Structs ​

AddPostBuildJobCommandsOptions ​

Options for BuildWorkflow.addPostBuildJobCommands.

Initializer ​

import { build } from 'projen'

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

Properties ​

NameTypeDescription
checkoutRepo
booleanCheck out the repository at the pull request branch before commands are run.
installDeps
booleanInstall project dependencies before running commands. checkoutRepo must also be set to true.
runsOn
string[]Github Runner selection labels.
runsOnGroup
projen.GroupRunnerOptionsGithub Runner Group selection options.
tools
projen.github.workflows.ToolsTools that should be installed before the commands are run.
checkoutRepoOptional ​
public readonly checkoutRepo: boolean;
  • Type: boolean
  • Default: false

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

installDepsOptional ​
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.

runsOnOptional ​
public readonly runsOn: string[];
  • Type: string[]
  • Default: ["ubuntu-latest"]

Github Runner selection labels.

runsOnGroupOptional ​
public readonly runsOnGroup: GroupRunnerOptions;
  • Type: projen.GroupRunnerOptions

Github Runner Group selection options.

toolsOptional ​
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 ​

NameTypeDescription
runsOn
string[]Github Runner selection labels.
runsOnGroup
projen.GroupRunnerOptionsGithub Runner Group selection options.
tools
projen.github.workflows.ToolsTools that should be installed before the task is run.
runsOnOptional ​
public readonly runsOn: string[];
  • Type: string[]
  • Default: ["ubuntu-latest"]

Github Runner selection labels.

runsOnGroupOptional ​
public readonly runsOnGroup: GroupRunnerOptions;
  • Type: projen.GroupRunnerOptions

Github Runner Group selection options.

toolsOptional ​
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 ​

NameTypeDescription
name
stringName of the buildfile (e.g. "build" becomes "build.yml").
permissions
projen.github.workflows.JobPermissionsPermissions 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.TriggersBuild workflow triggers.
nameOptional ​
public readonly name: string;
  • Type: string
  • Default: "build"

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

permissionsOptional ​
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 }.

preBuildStepsOptional ​
public readonly preBuildSteps: JobStep[];
  • Type: projen.github.workflows.JobStep[]
  • Default: []

Steps to execute before the build.

workflowTriggersOptional ​
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 ​

NameTypeDescription
name
stringName of the buildfile (e.g. "build" becomes "build.yml").
permissions
projen.github.workflows.JobPermissionsPermissions 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.TriggersBuild workflow triggers.
buildTask
projen.TaskThe task to execute in order to build the project.
artifactsDirectory
stringA name of a directory that includes build artifacts.
containerImage
stringThe container image to use for builds.
env
{[ key: string ]: string}Build environment variables.
gitIdentity
projen.github.GitIdentityGit identity to use for the workflow.
mutableBuild
booleanAutomatically update files modified during builds to pull-request branches.
postBuildSteps
projen.github.workflows.JobStep[]Steps to execute after build.
runsOn
string[]Github Runner selection labels.
runsOnGroup
projen.GroupRunnerOptionsGithub Runner Group selection options.
nameOptional ​
public readonly name: string;
  • Type: string
  • Default: "build"

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

permissionsOptional ​
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 }.

preBuildStepsOptional ​
public readonly preBuildSteps: JobStep[];
  • Type: projen.github.workflows.JobStep[]
  • Default: []

Steps to execute before the build.

workflowTriggersOptional ​
public readonly workflowTriggers: Triggers;
  • Type: projen.github.workflows.Triggers
  • Default: "{ pullRequest: {}, workflowDispatch: {} }"

Build workflow triggers.

buildTaskRequired ​
public readonly buildTask: Task;
  • Type: projen.Task

The task to execute in order to build the project.

artifactsDirectoryOptional ​
public readonly artifactsDirectory: string;
  • Type: string
  • Default: "dist"

A name of a directory that includes build artifacts.

containerImageOptional ​
public readonly containerImage: string;
  • Type: string
  • Default: the default workflow container

The container image to use for builds.

envOptional ​
public readonly env: {[ key: string ]: string};
  • Type: {[ key: string ]: string}
  • Default: {}

Build environment variables.

gitIdentityOptional ​
public readonly gitIdentity: GitIdentity;
  • Type: projen.github.GitIdentity
  • Default: default identity

Git identity to use for the workflow.

mutableBuildOptional ​
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.

postBuildStepsOptional ​
public readonly postBuildSteps: JobStep[];
  • Type: projen.github.workflows.JobStep[]
  • Default: []

Steps to execute after build.

runsOnOptional ​
public readonly runsOn: string[];
  • Type: string[]
  • Default: ["ubuntu-latest"]

Github Runner selection labels.

runsOnGroupOptional ​
public readonly runsOnGroup: GroupRunnerOptions;
  • Type: projen.GroupRunnerOptions

Github Runner Group selection options.