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.

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.


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.


BuildWorkflowOptions

Initializer

import { build } from 'projen'

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

Properties

NameTypeDescription
artifactsDirectory
stringA name of a directory that includes build artifacts.
buildTask
projen.TaskThe task to execute in order to build the project.
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.
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 }.
postBuildSteps
projen.github.workflows.JobStep[]Steps to execute after build.
preBuildSteps
projen.github.workflows.JobStep[]Steps to execute before the build.
runsOn
string[]Github Runner selection labels.
runsOnGroup
projen.GroupRunnerOptionsGithub Runner Group selection options.
workflowTriggers
projen.github.workflows.TriggersBuild workflow triggers.

artifactsDirectoryRequired
public readonly artifactsDirectory: string;
  • Type: string

A name of a directory that includes build artifacts.


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

The task to execute in order to build the project.


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.


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


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

Steps to execute after build.


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

Steps to execute before the 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.


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

Build workflow triggers.