build Submodule
Constructs
BuildWorkflow
Initializers
import { build } from 'projen'
new build.BuildWorkflow(project: Project, options: BuildWorkflowOptions)
| Name | Type | Description |
|---|---|---|
| projen.Project | No description. |
| | No description. |
projectRequired
- Type: projen.Project
optionsRequired
- Type: BuildWorkflowOptions
Methods
| Name | Description |
|---|---|
| Returns a string representation of this construct. |
| Applies one or more mixins to this construct. |
| Called once, right after postSynthesize(), only when the project is created for the first time. |
| Called after synthesis. |
| Called before synthesis. |
| Called once, right after synthesize(), only when the project is created for the first time. |
| Synthesizes files to the project output directory. |
| Adds another job to the build workflow which is executed after the build job succeeded. |
| Run a sequence of commands as a job within the build workflow which is executed after the build job succeeded. |
| Run a task as a job within the build workflow which is executed after the build job succeeded. |
| 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.
mixinsRequired
- 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.
initProjectRequired
- 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.
initProjectRequired
- 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.
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
| Name | Description |
|---|---|
| Checks if x is a construct. |
| 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
| Name | Type | Description |
|---|---|---|
| constructs.Node | The tree node. |
| projen.Project | No description. |
| string[] | Returns a list of job IDs that are part of the build. |
| string | Name of generated github workflow. |
| projen.github.GithubWorkflow | The underlying GitHub Actions 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.
workflowRequired
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 |
|---|---|---|
| boolean | Check out the repository at the pull request branch before commands are run. |
| boolean | Install project dependencies before running commands. checkoutRepo must also be set to true. |
| string[] | Github Runner selection labels. |
| projen.GroupRunnerOptions | Github Runner Group selection options. |
| projen.github.workflows.Tools | Tools 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
| Name | Type | Description |
|---|---|---|
| string[] | Github Runner selection labels. |
| projen.GroupRunnerOptions | Github Runner Group selection options. |
| projen.github.workflows.Tools | Tools 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
| Name | Type | Description |
|---|---|---|
| {[ key: string ]: string} | Build environment variables. |
| string | Name of the buildfile (e.g. "build" becomes "build.yml"). |
| 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 }. |
| projen.github.workflows.JobStep[] | Steps to execute before the build. |
| projen.github.workflows.Triggers | Build workflow triggers. |
envOptional
public readonly env: {[ key: string ]: string};
- Type: {[ key: string ]: string}
- Default: {}
Build environment variables.
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
| Name | Type | Description |
|---|---|---|
| {[ key: string ]: string} | Build environment variables. |
| string | Name of the buildfile (e.g. "build" becomes "build.yml"). |
| 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 }. |
| projen.github.workflows.JobStep[] | Steps to execute before the build. |
| projen.github.workflows.Triggers | Build workflow triggers. |
| projen.Task | The task to execute in order to build the project. |
| string | A name of a directory that includes build artifacts. |
| string[] | Github Runner selection labels. |
| string | The container image to use for builds. |
| projen.github.GitIdentity | Git identity to use for the workflow. |
| boolean | Automatically push files modified during builds to pull request branches. |
| | Options for pushing files modified during builds back to pull request branches. |
| boolean | Perform a mutable (non-frozen) install during builds. |
| projen.github.workflows.JobStep[] | Steps to execute after build. |
| string[] | Github Runner selection labels. |
| projen.GroupRunnerOptions | Github Runner Group selection options. |
envOptional
public readonly env: {[ key: string ]: string};
- Type: {[ key: string ]: string}
- Default: {}
Build environment variables.
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.
buildRunsOnOptional
public readonly buildRunsOn: string[];
- Type: string[]
- Default: runsOn
Github Runner selection labels.
containerImageOptional
public readonly containerImage: string;
- Type: string
- Default: the default workflow container
The container image to use for builds.
gitIdentityOptional
public readonly gitIdentity: GitIdentity;
- Type: projen.github.GitIdentity
- Default: default GitHub Actions user
Git identity to use for the workflow.
mutableBuildOptional
public readonly mutableBuild: boolean;
- Type: boolean
- Default: true
Automatically push 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.
A build that modifies files still fails. A separate self-mutation
workflow then pushes the changes to the pull request branch using the
projen credentials, which starts a new build.
mutableBuildOptionsOptional
public readonly mutableBuildOptions: MutableBuildOptions;
- Type: MutableBuildOptions
- Default: default options
Options for pushing files modified during builds back to pull request branches.
Only used if mutableBuild is enabled.
mutableInstallOptional
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.
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.
MutableBuildOptions
Options for pushing files modified during builds back to pull request branches.
Initializer
import { build } from 'projen'
const mutableBuildOptions: build.MutableBuildOptions = { ... }
Properties
| Name | Type | Description |
|---|---|---|
| boolean | Also push changes back to pull requests from forks. |
allowFromForksOptional
public readonly allowFromForks: boolean;
- Type: boolean
- Default: false
Also push changes back to pull requests from forks.
The changes are produced by the fork's build and pushed to the fork's branch using the projen credentials. This requires the pull request to allow edits from maintainers and credentials that can push to the fork.
The fork author controls the content of these commits, which can change any file. Review them like the rest of the pull request, even though they are authored by the automation user. Their builds also run without the approval GitHub requires for workflow runs from first-time contributors.