`github` Submodule

Constructs

AutoApprove

Auto approve pull requests that meet a criteria.

Initializers

import { github } from 'projen'

new github.AutoApprove(github: GitHub, options?: AutoApproveOptions)

Name	Type	Description
`github`	`GitHub`	No description.
`options`	`AutoApproveOptions`	No description.

`github`^Required

Type: GitHub

`options`^Optional

Type: AutoApproveOptions

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.
`addSource`	Auto-approve pull requests from this source, in addition to the configured sources.

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

`addSource`

public addSource(source: PullRequestSource): void

Auto-approve pull requests from this source, in addition to the configured sources.

Adding a source replaces the default source.

`source`^Required

Type: PullRequestSource

Static Functions

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

`isConstruct`

import { github } from 'projen'

github.AutoApprove.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 { github } from 'projen'

github.AutoApprove.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.
`label`	`string`	No description.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`project`^Required

public readonly project: Project;

Type: projen.Project

`label`^Required

public readonly label: string;

Type: string

AutoMerge

Automatically merge Pull Requests using Mergify.

[!NOTE] GitHub now natively provides the same features, so you don't need Mergify anymore. See GitHubOptions.mergeQueue and MergeQueueOptions.autoQueue.

If buildJob is specified, the specified GitHub workflow job ID is required to succeed in order for the PR to be merged.

approvedReviews specified the number of code review approvals required for the PR to be merged.

https://mergify.com/

Initializers

import { github } from 'projen'

new github.AutoMerge(github: GitHub, options?: AutoMergeOptions)

Name	Type	Description
`github`	`GitHub`	No description.
`options`	`AutoMergeOptions`	No description.

`github`^Required

Type: GitHub

`options`^Optional

Type: AutoMergeOptions

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.
`addConditions`	Adds conditions to the auto merge rule.
`addConditionsLater`	Adds conditions that will be rendered only during synthesis.

`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`^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.

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

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

`addConditions`

public addConditions(conditions: ...string[]): void

Adds conditions to the auto merge rule.

`conditions`^Required

Type: ...string[]

The conditions to add (mergify syntax).

`addConditionsLater`

public addConditionsLater(later: IAddConditionsLater): void

Adds conditions that will be rendered only during synthesis.

`later`^Required

Type: IAddConditionsLater

The later.

Static Functions

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

`isConstruct`

import { github } from 'projen'

github.AutoMerge.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.

`x`^Required

Type: any

Any object.

`isComponent`

import { github } from 'projen'

github.AutoMerge.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.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`project`^Required

public readonly project: Project;

Type: projen.Project

AutoQueue

Automatically add pull requests to the merge queue PRs will be merged once they pass required checks.

Initializers

import { github } from 'projen'

new github.AutoQueue(scope: IConstruct, options?: AutoQueueOptions)

Name	Type	Description
`scope`	`constructs.IConstruct`	No description.
`options`	`AutoQueueOptions`	No description.

`scope`^Required

Type: constructs.IConstruct

`options`^Optional

Type: AutoQueueOptions

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.

`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`^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.

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

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

Static Functions

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

`isConstruct`

import { github } from 'projen'

github.AutoQueue.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.

`x`^Required

Type: any

Any object.

`isComponent`

import { github } from 'projen'

github.AutoQueue.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.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`project`^Required

public readonly project: Project;

Type: projen.Project

Dependabot

Defines dependabot configuration for node projects.

Since module versions are managed in projen, the versioning strategy will be configured to "lockfile-only" which means that only updates that can be done on the lockfile itself will be proposed.

Initializers

import { github } from 'projen'

new github.Dependabot(github: GitHub, options?: DependabotOptions)

Name	Type	Description
`github`	`GitHub`	No description.
`options`	`DependabotOptions`	No description.

`github`^Required

Type: GitHub

`options`^Optional

Type: DependabotOptions

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.
`addAllow`	Allows a dependency from automatic updates.
`addIgnore`	Ignores a dependency from automatic updates.

`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`^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.

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

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

`addAllow`

public addAllow(dependencyName: string): void

Allows a dependency from automatic updates.

`dependencyName`^Required

Type: string

Use to allow updates for dependencies with matching names, optionally using * to match zero or more characters.

`addIgnore`

public addIgnore(dependencyName: string, versions: ...string[]): void

Ignores a dependency from automatic updates.

`dependencyName`^Required

Type: string

Use to ignore updates for dependencies with matching names, optionally using * to match zero or more characters.

`versions`^Required

Type: ...string[]

Use to ignore specific versions or ranges of versions.

If you want to define a range, use the standard pattern for the package manager (for example: ^1.0.0 for npm, or ~> 2.0 for Bundler).

Static Functions

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

`isConstruct`

import { github } from 'projen'

github.Dependabot.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.

`x`^Required

Type: any

Any object.

`isComponent`

import { github } from 'projen'

github.Dependabot.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.
`config`	`any`	The raw dependabot configuration.
`ignoresProjen`	`boolean`	Whether or not projen is also upgraded in this config,.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`project`^Required

public readonly project: Project;

Type: projen.Project

`config`^Required

public readonly config: any;

Type: any

The raw dependabot configuration.

https://docs.github.com/en/github/administering-a-repository/configuration-options-for-dependency-updates

`ignoresProjen`^Required

public readonly ignoresProjen: boolean;

Type: boolean

Whether or not projen is also upgraded in this config,.

DependencyReview

Adds a GitHub workflow that runs the dependency-review-action on pull requests.

This action scans pull requests for dependency changes and raises an error if any vulnerabilities or invalid licenses are introduced.

https://github.com/actions/dependency-review-action

Initializers

import { github } from 'projen'

new github.DependencyReview(github: GitHub, options?: DependencyReviewOptions)

Name	Type	Description
`github`	`GitHub`	No description.
`options`	`DependencyReviewOptions`	No description.

`github`^Required

Type: GitHub

`options`^Optional

Type: DependencyReviewOptions

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.

`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`^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.

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

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

Static Functions

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

`isConstruct`

import { github } from 'projen'

github.DependencyReview.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.

`x`^Required

Type: any

Any object.

`isComponent`

import { github } from 'projen'

github.DependencyReview.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.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`project`^Required

public readonly project: Project;

Type: projen.Project

GitHub

Initializers

import { github } from 'projen'

new github.GitHub(project: Project, options?: GitHubOptions)

Name	Type	Description
`project`	`projen.Project`	No description.
`options`	`GitHubOptions`	No description.

`project`^Required

Type: projen.Project

`options`^Optional

Type: GitHubOptions

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.
`addDependabot`	No description.
`addPullRequestTemplate`	No description.
`addWorkflow`	Adds a workflow to the project.
`runsOnConfig`	Resolves the `runsOn`/`runsOnGroup` config for a job, falling back to the project's global runner selection (`workflowRunsOn`/`workflowRunsOnGroup`) when `options` does not specify one.
`tryFindWorkflow`	Finds a GitHub workflow by name.

`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`^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.

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

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

`addDependabot`

public addDependabot(options?: DependabotOptions): Dependabot

`options`^Optional

Type: DependabotOptions

`addPullRequestTemplate`

public addPullRequestTemplate(content: ...string[]): PullRequestTemplate

`content`^Required

Type: ...string[]

`addWorkflow`

public addWorkflow(name: string): GithubWorkflow

Adds a workflow to the project.

`name`^Required

Type: string

Name of the workflow.

`runsOnConfig`

public runsOnConfig(options?: RunsOnOptions): RunsOnConfig

Resolves the runsOn/runsOnGroup config for a job, falling back to the project's global runner selection (workflowRunsOn/workflowRunsOnGroup) when options does not specify one.

`options`^Optional

Type: projen.RunsOnOptions

per-job runner selection that takes precedence over the project's global default.

`tryFindWorkflow`

public tryFindWorkflow(name: string): GithubWorkflow

Finds a GitHub workflow by name.

Returns undefined if the workflow cannot be found.

`name`^Required

Type: string

The name of the GitHub workflow.

Static Functions

Name	Description
`isConstruct`	Checks if `x` is a construct.
`isComponent`	Test whether the given construct is a component.
`of`	Returns the `GitHub` component of a project or `undefined` if the project does not have a GitHub component.

`isConstruct`

import { github } from 'projen'

github.GitHub.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.

`x`^Required

Type: any

Any object.

`isComponent`

import { github } from 'projen'

github.GitHub.isComponent(x: any)

Test whether the given construct is a component.

`x`^Required

Type: any

`of`

import { github } from 'projen'

github.GitHub.of(project: Project)

Returns the GitHub component of a project or undefined if the project does not have a GitHub component.

`project`^Required

Type: projen.Project

Properties

Name	Type	Description
`node`	`constructs.Node`	The tree node.
`project`	`projen.Project`	No description.
`actions`	`GitHubActionsProvider`	The GitHub Actions provider used to manage the versions of actions used in steps.
`checkoutSubmodules`	`CheckoutSubmodules`	Whether checking out Git submodules is enabled for this GitHub project.
`downloadLfs`	`boolean`	Whether downloading from LFS is enabled for this GitHub project.
`projenCredentials`	`GithubCredentials`	GitHub API authentication method used by projen workflows.
`workflows`	`GithubWorkflow[]`	All workflows.
`workflowsEnabled`	`boolean`	Are workflows enabled?
`mergeQueue`	`MergeQueue`	The `MergeQueue` component configured on this repository This is `undefined` if merge queues are not enabled for this repository.
`mergify`	`Mergify`	The `Mergify` component configured on this repository This is `undefined` if Mergify is not enabled for this repository.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`project`^Required

public readonly project: Project;

Type: projen.Project

`actions`^Required

public readonly actions: GitHubActionsProvider;

Type: GitHubActionsProvider

The GitHub Actions provider used to manage the versions of actions used in steps.

`checkoutSubmodules`^Required

public readonly checkoutSubmodules: CheckoutSubmodules;

Type: CheckoutSubmodules

Whether checking out Git submodules is enabled for this GitHub project.

`downloadLfs`^Required

public readonly downloadLfs: boolean;

Type: boolean

Whether downloading from LFS is enabled for this GitHub project.

`projenCredentials`^Required

public readonly projenCredentials: GithubCredentials;

Type: GithubCredentials

GitHub API authentication method used by projen workflows.

`workflows`^Required

public readonly workflows: GithubWorkflow[];

Type: GithubWorkflow[]

All workflows.

`workflowsEnabled`^Required

public readonly workflowsEnabled: boolean;

Type: boolean

Are workflows enabled?

`mergeQueue`^Optional

public readonly mergeQueue: MergeQueue;

Type: MergeQueue

The MergeQueue component configured on this repository This is undefined if merge queues are not enabled for this repository.

`mergify`^Optional

public readonly mergify: Mergify;

Type: Mergify

The Mergify component configured on this repository This is undefined if Mergify is not enabled for this repository.

GitHubProject

GitHub-based project.

Initializers

import { github } from 'projen'

new github.GitHubProject(options: GitHubProjectOptions)

Name	Type	Description
`options`	`GitHubProjectOptions`	No description.

`options`^Required

Type: GitHubProjectOptions

Methods

Name	Description
`toString`	Returns a string representation of this construct.
`with`	Applies one or more mixins to this construct.
`addExcludeFromCleanup`	Exclude the matching files from pre-synth cleanup.
`addGitIgnore`	Adds a .gitignore pattern.
`addPackageIgnore`	Exclude these files from the bundled package.
`addTask`	Adds a new task to this project.
`annotateGenerated`	Marks the provided file(s) as being generated.
`postSynthesize`	Called after all components are synthesized.
`preSynthesize`	Called before all components are synthesized.
`removeTask`	Removes a task from a project.
`runTaskCommand`	Returns the shell command to execute in order to run a task.
`synth`	Synthesize all project files into `outdir`.
`tryFindFile`	Finds a file at the specified relative path within this project and all its subprojects.
`tryFindObjectFile`	Finds an object file (like JsonFile, YamlFile, etc.) by name.
`tryRemoveFile`	Finds a file at the specified relative path within this project and removes it.

`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`^Required

Type: ...constructs.IMixin[]

The mixins to apply.

`addExcludeFromCleanup`

public addExcludeFromCleanup(globs: ...string[]): void

Exclude the matching files from pre-synth cleanup.

Can be used when, for example, some source files include the projen marker and we don't want them to be erased during synth.

`globs`^Required

Type: ...string[]

The glob patterns to match.

`addGitIgnore`

public addGitIgnore(pattern: string): void

Adds a .gitignore pattern.

`pattern`^Required

Type: string

The glob pattern to ignore.

`addPackageIgnore`

public addPackageIgnore(_pattern: string): void

Exclude these files from the bundled package.

Implemented by project types based on the packaging mechanism. For example, NodeProject delegates this to .npmignore.

`_pattern`^Required

Type: string

The glob pattern to exclude.

`addTask`

public addTask(name: string, props?: TaskOptions): Task

Adds a new task to this project.

This will fail if the project already has a task with this name.

`name`^Required

Type: string

The task name to add.

`props`^Optional

Type: projen.TaskOptions

Task properties.

`annotateGenerated`

public annotateGenerated(glob: string): void

Marks the provided file(s) as being generated.

This is achieved using the github-linguist attributes. Generated files do not count against the repository statistics and language breakdown.

https://github.com/github/linguist/blob/master/docs/overrides.md

`glob`^Required

Type: string

the glob pattern to match (could be a file path).

`postSynthesize`

public postSynthesize(): void

Called after all components are synthesized.

Order is not guaranteed.

`preSynthesize`

public preSynthesize(): void

Called before all components are synthesized.

`removeTask`

public removeTask(name: string): Task

Removes a task from a project.

`name`^Required

Type: string

The name of the task to remove.

`runTaskCommand`

public runTaskCommand(task: Task): string

Returns the shell command to execute in order to run a task.

By default, this is npx projen@<version> <task>

`task`^Required

Type: projen.Task

The task for which the command is required.

`synth`

public synth(): void

Synthesize all project files into outdir.

Call "this.preSynthesize()"
Delete all generated files
Synthesize all subprojects
Synthesize all components of this project
Call "projectCreation()" for all components, only if the project is being created for the first time
Call "postSynthesize()" for all components of this project
Call "this.postSynthesize()"
Call "postProjectCreation()" for all components, only if the project is being created for the first time

`tryFindFile`

public tryFindFile(filePath: string): FileBase

Finds a file at the specified relative path within this project and all its subprojects.

`filePath`^Required

Type: string

The file path.

If this path is relative, it will be resolved from the root of this project.

`tryFindObjectFile`

public tryFindObjectFile(filePath: string): ObjectFile

Finds an object file (like JsonFile, YamlFile, etc.) by name.

`filePath`^Required

Type: string

The file path.

`tryRemoveFile`

public tryRemoveFile(filePath: string): FileBase

Finds a file at the specified relative path within this project and removes it.

`filePath`^Required

Type: string

The file path.

If this path is relative, it will be resolved from the root of this project.

Static Functions

Name	Description
`isConstruct`	Checks if `x` is a construct.
`isProject`	Test whether the given construct is a project.
`of`	Find the closest ancestor project for given construct.

`isConstruct`

import { github } from 'projen'

github.GitHubProject.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.

`x`^Required

Type: any

Any object.

`isProject`

import { github } from 'projen'

github.GitHubProject.isProject(x: any)

Test whether the given construct is a project.

`x`^Required

Type: any

`of`

import { github } from 'projen'

github.GitHubProject.of(construct: IConstruct)

Find the closest ancestor project for given construct.

When given a project, this it the project itself.

`construct`^Required

Type: constructs.IConstruct

Properties

Name	Type	Description
`node`	`constructs.Node`	The tree node.
`buildTask`	`projen.Task`	No description.
`commitGenerated`	`boolean`	Whether to commit the managed files by default.
`compileTask`	`projen.Task`	No description.
`components`	`projen.Component[]`	Returns all the components within this project.
`deps`	`projen.Dependencies`	Project dependencies.
`ejected`	`boolean`	Whether or not the project is being ejected.
`files`	`projen.FileBase[]`	All files in this project.
`gitattributes`	`projen.GitAttributesFile`	The .gitattributes file for this repository.
`gitignore`	`projen.IgnoreFile`	.gitignore.
`logger`	`projen.Logger`	Logging utilities.
`name`	`string`	Project name.
`outdir`	`string`	Absolute output directory of this project.
`packageTask`	`projen.Task`	No description.
`postCompileTask`	`projen.Task`	No description.
`preCompileTask`	`projen.Task`	No description.
`projectBuild`	`projen.ProjectBuild`	Manages the build process of the project.
`projenCommand`	`string`	The command to use in order to run the projen CLI.
`root`	`projen.Project`	The root project.
`subprojects`	`projen.Project[]`	Returns all the subprojects within this project.
`tasks`	`projen.Tasks`	Project tasks.
`testTask`	`projen.Task`	No description.
`defaultTask`	`projen.Task`	This is the "default" task, the one that executes "projen".
`initProject`	`projen.InitProject`	The options used when this project is bootstrapped via `projen new`.
`parent`	`projen.Project`	A parent project.
`autoApprove`	`AutoApprove`	Auto approve set up for this project.
`devContainer`	`projen.vscode.DevContainer`	Access for .devcontainer.json (used for GitHub Codespaces).
`github`	`GitHub`	Access all github components.
`gitpod`	`projen.Gitpod`	Access for Gitpod.
`vscode`	`projen.vscode.VsCode`	Access all VSCode components.

`node`^Required

Deprecated: This is a temporary class. At the moment, our base project types such as NodeProject and JavaProject are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.

public readonly node: Node;

Type: constructs.Node

The tree node.

`buildTask`^Required

Deprecated: This is a temporary class. At the moment, our base project types such as NodeProject and JavaProject are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.

public readonly buildTask: Task;

Type: projen.Task

`commitGenerated`^Required

Deprecated: This is a temporary class. At the moment, our base project types such as NodeProject and JavaProject are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.

public readonly commitGenerated: boolean;

Type: boolean

Whether to commit the managed files by default.

`compileTask`^Required

Deprecated: This is a temporary class. At the moment, our base project types such as NodeProject and JavaProject are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.

public readonly compileTask: Task;

Type: projen.Task

`components`^Required

Deprecated: This is a temporary class. At the moment, our base project types such as NodeProject and JavaProject are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.

public readonly components: Component[];

Type: projen.Component[]

Returns all the components within this project.

`deps`^Required

Deprecated: This is a temporary class. At the moment, our base project types such as NodeProject and JavaProject are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.

public readonly deps: Dependencies;

Type: projen.Dependencies

Project dependencies.

`ejected`^Required

Deprecated: This is a temporary class. At the moment, our base project types such as NodeProject and JavaProject are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.

public readonly ejected: boolean;

Type: boolean

Whether or not the project is being ejected.

`files`^Required

Deprecated: This is a temporary class. At the moment, our base project types such as NodeProject and JavaProject are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.

public readonly files: FileBase[];

Type: projen.FileBase[]

All files in this project.

`gitattributes`^Required

Deprecated: This is a temporary class. At the moment, our base project types such as NodeProject and JavaProject are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.

public readonly gitattributes: GitAttributesFile;

Type: projen.GitAttributesFile

The .gitattributes file for this repository.

`gitignore`^Required

Deprecated: This is a temporary class. At the moment, our base project types such as NodeProject and JavaProject are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.

public readonly gitignore: IgnoreFile;

Type: projen.IgnoreFile

.gitignore.

`logger`^Required

Deprecated: This is a temporary class. At the moment, our base project types such as NodeProject and JavaProject are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.

public readonly logger: Logger;

Type: projen.Logger

Logging utilities.

`name`^Required

Deprecated: This is a temporary class. At the moment, our base project types such as NodeProject and JavaProject are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.

public readonly name: string;

Type: string

Project name.

`outdir`^Required

Deprecated: This is a temporary class. At the moment, our base project types such as NodeProject and JavaProject are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.

public readonly outdir: string;

Type: string

Absolute output directory of this project.

`packageTask`^Required

Deprecated: This is a temporary class. At the moment, our base project types such as NodeProject and JavaProject are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.

public readonly packageTask: Task;

Type: projen.Task

`postCompileTask`^Required

Deprecated: This is a temporary class. At the moment, our base project types such as NodeProject and JavaProject are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.

public readonly postCompileTask: Task;

Type: projen.Task

`preCompileTask`^Required

Deprecated: This is a temporary class. At the moment, our base project types such as NodeProject and JavaProject are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.

public readonly preCompileTask: Task;

Type: projen.Task

`projectBuild`^Required

Deprecated: This is a temporary class. At the moment, our base project types such as NodeProject and JavaProject are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.

public readonly projectBuild: ProjectBuild;

Type: projen.ProjectBuild

Manages the build process of the project.

`projenCommand`^Required

Deprecated: This is a temporary class. At the moment, our base project types such as NodeProject and JavaProject are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.

public readonly projenCommand: string;

Type: string

The command to use in order to run the projen CLI.

`root`^Required

Deprecated: This is a temporary class. At the moment, our base project types such as NodeProject and JavaProject are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.

public readonly root: Project;

Type: projen.Project

The root project.

`subprojects`^Required

Deprecated: This is a temporary class. At the moment, our base project types such as NodeProject and JavaProject are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.

public readonly subprojects: Project[];

Type: projen.Project[]

Returns all the subprojects within this project.

`tasks`^Required

Deprecated: This is a temporary class. At the moment, our base project types such as NodeProject and JavaProject are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.

public readonly tasks: Tasks;

Type: projen.Tasks

Project tasks.

`testTask`^Required

Deprecated: This is a temporary class. At the moment, our base project types such as NodeProject and JavaProject are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.

public readonly testTask: Task;

Type: projen.Task

`defaultTask`^Optional

Deprecated: This is a temporary class. At the moment, our base project types such as NodeProject and JavaProject are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.

public readonly defaultTask: Task;

Type: projen.Task

This is the "default" task, the one that executes "projen".

Undefined if the project is being ejected.

`initProject`^Optional

Deprecated: use the initProject argument passed to Component.projectCreation() instead.

public readonly initProject: InitProject;

Type: projen.InitProject

The options used when this project is bootstrapped via projen new.

It includes the original set of options passed to the CLI and also the JSII FQN of the project type.

`parent`^Optional

Deprecated: This is a temporary class. At the moment, our base project types such as NodeProject and JavaProject are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.

public readonly parent: Project;

Type: projen.Project

A parent project.

If undefined, this is the root project.

`autoApprove`^Optional

Deprecated: This is a temporary class. At the moment, our base project types such as NodeProject and JavaProject are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.

public readonly autoApprove: AutoApprove;

Type: AutoApprove

Auto approve set up for this project.

`devContainer`^Optional

Deprecated: This is a temporary class. At the moment, our base project types such as NodeProject and JavaProject are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.

public readonly devContainer: DevContainer;

Type: projen.vscode.DevContainer

Access for .devcontainer.json (used for GitHub Codespaces).

This will be undefined if devContainer boolean is false

`github`^Optional

Deprecated: This is a temporary class. At the moment, our base project types such as NodeProject and JavaProject are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.

public readonly github: GitHub;

Type: GitHub

Access all github components.

This will be undefined for subprojects.

`gitpod`^Optional

Deprecated: This is a temporary class. At the moment, our base project types such as NodeProject and JavaProject are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.

public readonly gitpod: Gitpod;

Type: projen.Gitpod

Access for Gitpod.

This will be undefined if gitpod boolean is false

`vscode`^Optional

Deprecated: This is a temporary class. At the moment, our base project types such as NodeProject and JavaProject are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.

public readonly vscode: VsCode;

Type: projen.vscode.VsCode

Access all VSCode components.

This will be undefined for subprojects.

Constants

Name	Type	Description
`DEFAULT_TASK`	`string`	The name of the default task (the task executed when `projen` is run without arguments).

`DEFAULT_TASK`^Required

Deprecated: This is a temporary class. At the moment, our base project types such as NodeProject and JavaProject are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.

public readonly DEFAULT_TASK: string;

Type: string

The name of the default task (the task executed when projen is run without arguments).

Normally this task should synthesize the project files.

GithubWorkflow

Workflow for GitHub.

A workflow is a configurable automated process made up of one or more jobs.

https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions

Initializers

import { github } from 'projen'

new github.GithubWorkflow(github: GitHub, name: string, options?: GithubWorkflowOptions)

Name	Type	Description
`github`	`GitHub`	The GitHub component of the project this workflow belongs to.
`name`	`string`	The name of the workflow, displayed under the repository's "Actions" tab.
`options`	`GithubWorkflowOptions`	Additional options to configure the workflow.

`github`^Required

Type: GitHub

The GitHub component of the project this workflow belongs to.

`name`^Required

Type: string

The name of the workflow, displayed under the repository's "Actions" tab.

`options`^Optional

Type: GithubWorkflowOptions

Additional options to configure the workflow.

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.
`addJob`	Adds a single job to the workflow.
`addJobs`	Add jobs to the workflow.
`appendStep`	Appends a step to the end of a job's step list.
`getJob`	Get a single job from the workflow.
`getStep`	Gets a single step from a job by step ID.
`insertStepAfter`	Inserts a step after an existing step, identified by ID.
`insertStepBefore`	Inserts a step before an existing step, identified by ID.
`on`	Add events to triggers the workflow.
`patchStep`	Applies a surgical modification to an existing step.
`removeJob`	Removes a single job to the workflow.
`removeStep`	Removes a step from a job by step ID.
`replaceStep`	Replaces an existing step in a job, preserving its position.
`updateJob`	Updates a single job to the workflow.
`updateJobs`	Updates jobs for this workflow Does a complete replace, it does not try to merge the jobs.

`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`^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.

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

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

`addJob`

public addJob(id: string, job: JobCallingReusableWorkflow | Job): void

Adds a single job to the workflow.

`id`^Required

Type: string

The job name (unique within the workflow).

`job`^Required

Type: JobCallingReusableWorkflow | Job

The job specification.

`addJobs`

public addJobs(jobs: {[ key: string ]: JobCallingReusableWorkflow | Job}): void

Add jobs to the workflow.

`jobs`^Required

Type: {[ key: string ]: JobCallingReusableWorkflow | Job}

Jobs to add.

`appendStep`

public appendStep(jobId: string, step: JobStep): void

Appends a step to the end of a job's step list.

`jobId`^Required

Type: string

The job name (unique within the workflow).

`step`^Required

Type: JobStep

The step to add.

Must have an id set.

`getJob`

public getJob(id: string): JobCallingReusableWorkflow | Job

Get a single job from the workflow.

`id`^Required

Type: string

The job name (unique within the workflow).

`getStep`

public getStep(jobId: string, stepId: string): JobStep

Gets a single step from a job by step ID.

The returned object is frozen and read-only. Use replaceStep or patchStep to modify a step.

`jobId`^Required

Type: string

The job name (unique within the workflow).

`stepId`^Required

Type: string

The step ID to look up.

`insertStepAfter`

public insertStepAfter(jobId: string, referenceStepId: string, step: JobStep): void

Inserts a step after an existing step, identified by ID.

`jobId`^Required

Type: string

The job name (unique within the workflow).

`referenceStepId`^Required

Type: string

The ID of the step to insert after.

`step`^Required

Type: JobStep

The step to insert.

Must have an id set.

`insertStepBefore`

public insertStepBefore(jobId: string, referenceStepId: string, step: JobStep): void

Inserts a step before an existing step, identified by ID.

`jobId`^Required

Type: string

The job name (unique within the workflow).

`referenceStepId`^Required

Type: string

The ID of the step to insert before.

`step`^Required

Type: JobStep

The step to insert.

Must have an id set.

`on`

public on(events: Triggers): void

Add events to triggers the workflow.

`events`^Required

Type: Triggers

The event(s) to trigger the workflow.

`patchStep`

public patchStep(jobId: string, stepId: string, patch: JobStep): void

Applies a surgical modification to an existing step.

The provided patch is shallow-merged onto the existing step. Fields not present in the patch are preserved unchanged. Use getStep to read the current step values before constructing the patch.

Example

// Add an env var without replacing existing ones:
const step = workflow.getStep("build", "install");
workflow.patchStep("build", "install", {
  env: { ...step.env, NODE_AUTH_TOKEN: "${{ steps.jfrog.outputs.oidc-token }}" },
});

`jobId`^Required

Type: string

The job name (unique within the workflow).

`stepId`^Required

Type: string

The ID of the step to patch.

`patch`^Required

Type: JobStep

A partial step object whose fields are shallow-merged onto the existing step.

`removeJob`

public removeJob(id: string): void

Removes a single job to the workflow.

`id`^Required

Type: string

The job name (unique within the workflow).

`removeStep`

public removeStep(jobId: string, stepId: string): void

Removes a step from a job by step ID.

`jobId`^Required

Type: string

The job name (unique within the workflow).

`stepId`^Required

Type: string

The ID of the step to remove.

`replaceStep`

public replaceStep(jobId: string, stepId: string, replacementStep: JobStep): void

Replaces an existing step in a job, preserving its position.

`jobId`^Required

Type: string

The job name (unique within the workflow).

`stepId`^Required

Type: string

The ID of the step to replace.

`replacementStep`^Required

Type: JobStep

The replacement step.

Inherits the original step's ID.

`updateJob`

public updateJob(id: string, job: JobCallingReusableWorkflow | Job): void

Updates a single job to the workflow.

`id`^Required

Type: string

The job name (unique within the workflow).

`job`^Required

Type: JobCallingReusableWorkflow | Job

`updateJobs`

public updateJobs(jobs: {[ key: string ]: JobCallingReusableWorkflow | Job}): void

Updates jobs for this workflow Does a complete replace, it does not try to merge the jobs.

`jobs`^Required

Type: {[ key: string ]: JobCallingReusableWorkflow | Job}

Jobs to update.

Static Functions

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

`isConstruct`

import { github } from 'projen'

github.GithubWorkflow.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.

`x`^Required

Type: any

Any object.

`isComponent`

import { github } from 'projen'

github.GithubWorkflow.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.
`jobs`	`{[ key: string ]: JobCallingReusableWorkflow \| Job}`	All current jobs of the workflow.
`name`	`string`	The name of the workflow.
`projenCredentials`	`GithubCredentials`	GitHub API authentication method used by projen workflows.
`concurrency`	`ConcurrencyOptions`	The concurrency configuration of the workflow.
`env`	`{[ key: string ]: string}`	Additional environment variables to set for the workflow.
`file`	`projen.YamlFile`	The workflow YAML file.
`runName`	`string`	The name for workflow runs generated from the workflow.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`project`^Required

public readonly project: Project;

Type: projen.Project

`jobs`^Required

public readonly jobs: {[ key: string ]: JobCallingReusableWorkflow | Job};

Type: {[ key: string ]: JobCallingReusableWorkflow | Job}

All current jobs of the workflow.

This is a read-only copy, use the respective helper methods to add, update or remove jobs.

`name`^Required

public readonly name: string;

Type: string

The name of the workflow.

GitHub displays the names of your workflows under your repository's "Actions" tab.

https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#name

`projenCredentials`^Required

public readonly projenCredentials: GithubCredentials;

Type: GithubCredentials

GitHub API authentication method used by projen workflows.

`concurrency`^Optional

public readonly concurrency: ConcurrencyOptions;

Type: ConcurrencyOptions

The concurrency configuration of the workflow.

undefined means no concurrency limitations.

`env`^Optional

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

Type: {[ key: string ]: string}

Additional environment variables to set for the workflow.

`file`^Optional

public readonly file: YamlFile;

Type: projen.YamlFile

The workflow YAML file.

May not exist if workflowsEnabled is false on GitHub.

`runName`^Optional

public readonly runName: string;

Type: string

The name for workflow runs generated from the workflow.

GitHub displays the workflow run name in the list of workflow runs on your repository's "Actions" tab. If run-name is omitted or is only whitespace, then the run name is set to event-specific information for the workflow run. For example, for a workflow triggered by a push or pull_request event, it is set as the commit message.

This value can include expressions and can reference github and inputs contexts.

MergeQueue

Merge pull requests using a merge queue.

Initializers

import { github } from 'projen'

new github.MergeQueue(scope: IConstruct, options?: MergeQueueOptions)

Name	Type	Description
`scope`	`constructs.IConstruct`	No description.
`options`	`MergeQueueOptions`	No description.

`scope`^Required

Type: constructs.IConstruct

`options`^Optional

Type: MergeQueueOptions

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.

`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`^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.

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

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

Static Functions

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

`isConstruct`

import { github } from 'projen'

github.MergeQueue.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.

`x`^Required

Type: any

Any object.

`isComponent`

import { github } from 'projen'

github.MergeQueue.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.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`project`^Required

public readonly project: Project;

Type: projen.Project

Mergify

Initializers

import { github } from 'projen'

new github.Mergify(github: GitHub, options?: MergifyOptions)

Name	Type	Description
`github`	`GitHub`	No description.
`options`	`MergifyOptions`	No description.

`github`^Required

Type: GitHub

`options`^Optional

Type: MergifyOptions

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.
`addQueue`	No description.
`addRule`	No description.

`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`^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.

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

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

`addQueue`

public addQueue(queue: MergifyQueue): void

`queue`^Required

Type: MergifyQueue

`addRule`

public addRule(rule: MergifyRule): void

`rule`^Required

Type: MergifyRule

Static Functions

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

`isConstruct`

import { github } from 'projen'

github.Mergify.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.

`x`^Required

Type: any

Any object.

`isComponent`

import { github } from 'projen'

github.Mergify.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.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`project`^Required

public readonly project: Project;

Type: projen.Project

PullRequestBackport

Initializers

import { github } from 'projen'

new github.PullRequestBackport(scope: IConstruct, options?: PullRequestBackportOptions)

Name	Type	Description
`scope`	`constructs.IConstruct`	No description.
`options`	`PullRequestBackportOptions`	No description.

`scope`^Required

Type: constructs.IConstruct

`options`^Optional

Type: PullRequestBackportOptions

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.

`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`^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.

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

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

Static Functions

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

`isConstruct`

import { github } from 'projen'

github.PullRequestBackport.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.

`x`^Required

Type: any

Any object.

`isComponent`

import { github } from 'projen'

github.PullRequestBackport.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.JsonFile`	No description.
`workflow`	`GithubWorkflow`	No description.

`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: JsonFile;

Type: projen.JsonFile

`workflow`^Required

public readonly workflow: GithubWorkflow;

Type: GithubWorkflow

PullRequestLint

Configure validations to run on GitHub pull requests.

Only generates a file if at least one linter is configured.

Initializers

import { github } from 'projen'

new github.PullRequestLint(github: GitHub, options?: PullRequestLintOptions)

Name	Type	Description
`github`	`GitHub`	No description.
`options`	`PullRequestLintOptions`	No description.

`github`^Required

Type: GitHub

`options`^Optional

Type: PullRequestLintOptions

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.

`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`^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.

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

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

Static Functions

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

`isConstruct`

import { github } from 'projen'

github.PullRequestLint.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.

`x`^Required

Type: any

Any object.

`isComponent`

import { github } from 'projen'

github.PullRequestLint.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.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`project`^Required

public readonly project: Project;

Type: projen.Project

PullRequestTemplate

Template for GitHub pull requests.

Initializers

import { github } from 'projen'

new github.PullRequestTemplate(github: GitHub, options?: PullRequestTemplateOptions)

Name	Type	Description
`github`	`GitHub`	No description.
`options`	`PullRequestTemplateOptions`	No description.

`github`^Required

Type: GitHub

`options`^Optional

Type: PullRequestTemplateOptions

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`	Writes the file to the project's output directory.
`diff`	Returns a unified diff of the old and new file contents with context lines and hunk headers.
`addLine`	Adds a line to the text file.

`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`^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.

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

`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

Writes the file to the project's output directory.

`diff`

public diff(colorize?: boolean, contextLines?: number): string[]

Returns a unified diff of the old and new file contents with context lines and hunk headers.

Only available after synthesis.

This is an expensive operation and should only be used on non time-critical code paths, like debug output.

`colorize`^Optional

Type: boolean

Whether to colorize the diff output.

`contextLines`^Optional

Type: number

Number of context lines around changes.

`addLine`

public addLine(line: string): void

Adds a line to the text file.

`line`^Required

Type: string

the line to add (can use tokens).

Static Functions

Name	Description
`isConstruct`	Checks if `x` is a construct.
`isComponent`	Test whether the given construct is a component.
`of`	Returns the `PullRequestTemplate` instance associated with a project or `undefined` if there is no PullRequestTemplate.

`isConstruct`

import { github } from 'projen'

github.PullRequestTemplate.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.

`x`^Required

Type: any

Any object.

`isComponent`

import { github } from 'projen'

github.PullRequestTemplate.isComponent(x: any)

Test whether the given construct is a component.

`x`^Required

Type: any

`of`

import { github } from 'projen'

github.PullRequestTemplate.of(project: Project)

Returns the PullRequestTemplate instance associated with a project or undefined if there is no PullRequestTemplate.

`project`^Required

Type: projen.Project

The project.

Properties

Name	Type	Description
`node`	`constructs.Node`	The tree node.
`project`	`projen.Project`	No description.
`absolutePath`	`string`	The absolute path of this file.
`committed`	`boolean`	Indicates if the file will be committed.
`path`	`string`	The file path, relative to the project's outdir.
`changed`	`boolean`	Indicates if the file has been changed during synthesis.
`marker`	`string`	The projen marker, used to identify files as projen-generated.
`executable`	`boolean`	Indicates if the file should be marked as executable.
`readonly`	`boolean`	Indicates if the file should be read-only or read-write.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`project`^Required

public readonly project: Project;

Type: projen.Project

`absolutePath`^Required

public readonly absolutePath: string;

Type: string

The absolute path of this file.

`committed`^Required

public readonly committed: boolean;

Type: boolean

Indicates if the file will be committed.

`path`^Required

public readonly path: string;

Type: string

The file path, relative to the project's outdir.

`changed`^Optional

public readonly changed: boolean;

Type: boolean

Indicates if the file has been changed during synthesis.

This property is only available in postSynthesize() hooks. If this is undefined, the file has not been synthesized yet.

`marker`^Optional

public readonly marker: string;

Type: string

The projen marker, used to identify files as projen-generated.

Value is undefined if the project is being ejected.

`executable`^Required

public readonly executable: boolean;

Type: boolean

Indicates if the file should be marked as executable.

`readonly`^Required

public readonly readonly: boolean;

Type: boolean

Indicates if the file should be read-only or read-write.

Stale

Warns and then closes issues and PRs that have had no activity for a specified amount of time.

The default configuration will:

Add a "Stale" label to pull requests after 14 days and closed after 2 days
Add a "Stale" label to issues after 60 days and closed after 7 days
If a comment is added, the label will be removed and timer is restarted.

https://github.com/actions/stale

Initializers

import { github } from 'projen'

new github.Stale(github: GitHub, options?: StaleOptions)

Name	Type	Description
`github`	`GitHub`	No description.
`options`	`StaleOptions`	No description.

`github`^Required

Type: GitHub

`options`^Optional

Type: StaleOptions

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.

`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`^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.

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

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

Static Functions

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

`isConstruct`

import { github } from 'projen'

github.Stale.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.

`x`^Required

Type: any

Any object.

`isComponent`

import { github } from 'projen'

github.Stale.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.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`project`^Required

public readonly project: Project;

Type: projen.Project

TaskWorkflow

A GitHub workflow for common build tasks within a project.

Initializers

import { github } from 'projen'

new github.TaskWorkflow(github: GitHub, options: TaskWorkflowOptions)

Name	Type	Description
`github`	`GitHub`	No description.
`options`	`TaskWorkflowOptions`	No description.

`github`^Required

Type: GitHub

`options`^Required

Type: TaskWorkflowOptions

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.
`addJob`	Adds a single job to the workflow.
`addJobs`	Add jobs to the workflow.
`appendStep`	Appends a step to the end of a job's step list.
`getJob`	Get a single job from the workflow.
`getStep`	Gets a single step from a job by step ID.
`insertStepAfter`	Inserts a step after an existing step, identified by ID.
`insertStepBefore`	Inserts a step before an existing step, identified by ID.
`on`	Add events to triggers the workflow.
`patchStep`	Applies a surgical modification to an existing step.
`removeJob`	Removes a single job to the workflow.
`removeStep`	Removes a step from a job by step ID.
`replaceStep`	Replaces an existing step in a job, preserving its position.
`updateJob`	Updates a single job to the workflow.
`updateJobs`	Updates jobs for this workflow Does a complete replace, it does not try to merge the jobs.

`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`^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.

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

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

`addJob`

public addJob(id: string, job: JobCallingReusableWorkflow | Job): void

Adds a single job to the workflow.

`id`^Required

Type: string

The job name (unique within the workflow).

`job`^Required

Type: JobCallingReusableWorkflow | Job

The job specification.

`addJobs`

public addJobs(jobs: {[ key: string ]: JobCallingReusableWorkflow | Job}): void

Add jobs to the workflow.

`jobs`^Required

Type: {[ key: string ]: JobCallingReusableWorkflow | Job}

Jobs to add.

`appendStep`

public appendStep(jobId: string, step: JobStep): void

Appends a step to the end of a job's step list.

`jobId`^Required

Type: string

The job name (unique within the workflow).

`step`^Required

Type: JobStep

The step to add.

Must have an id set.

`getJob`

public getJob(id: string): JobCallingReusableWorkflow | Job

Get a single job from the workflow.

`id`^Required

Type: string

The job name (unique within the workflow).

`getStep`

public getStep(jobId: string, stepId: string): JobStep

Gets a single step from a job by step ID.

The returned object is frozen and read-only. Use replaceStep or patchStep to modify a step.

`jobId`^Required

Type: string

The job name (unique within the workflow).

`stepId`^Required

Type: string

The step ID to look up.

`insertStepAfter`

public insertStepAfter(jobId: string, referenceStepId: string, step: JobStep): void

Inserts a step after an existing step, identified by ID.

`jobId`^Required

Type: string

The job name (unique within the workflow).

`referenceStepId`^Required

Type: string

The ID of the step to insert after.

`step`^Required

Type: JobStep

The step to insert.

Must have an id set.

`insertStepBefore`

public insertStepBefore(jobId: string, referenceStepId: string, step: JobStep): void

Inserts a step before an existing step, identified by ID.

`jobId`^Required

Type: string

The job name (unique within the workflow).

`referenceStepId`^Required

Type: string

The ID of the step to insert before.

`step`^Required

Type: JobStep

The step to insert.

Must have an id set.

`on`

public on(events: Triggers): void

Add events to triggers the workflow.

`events`^Required

Type: Triggers

The event(s) to trigger the workflow.

`patchStep`

public patchStep(jobId: string, stepId: string, patch: JobStep): void

Applies a surgical modification to an existing step.

The provided patch is shallow-merged onto the existing step. Fields not present in the patch are preserved unchanged. Use getStep to read the current step values before constructing the patch.

Example

// Add an env var without replacing existing ones:
const step = workflow.getStep("build", "install");
workflow.patchStep("build", "install", {
  env: { ...step.env, NODE_AUTH_TOKEN: "${{ steps.jfrog.outputs.oidc-token }}" },
});

`jobId`^Required

Type: string

The job name (unique within the workflow).

`stepId`^Required

Type: string

The ID of the step to patch.

`patch`^Required

Type: JobStep

A partial step object whose fields are shallow-merged onto the existing step.

`removeJob`

public removeJob(id: string): void

Removes a single job to the workflow.

`id`^Required

Type: string

The job name (unique within the workflow).

`removeStep`

public removeStep(jobId: string, stepId: string): void

Removes a step from a job by step ID.

`jobId`^Required

Type: string

The job name (unique within the workflow).

`stepId`^Required

Type: string

The ID of the step to remove.

`replaceStep`

public replaceStep(jobId: string, stepId: string, replacementStep: JobStep): void

Replaces an existing step in a job, preserving its position.

`jobId`^Required

Type: string

The job name (unique within the workflow).

`stepId`^Required

Type: string

The ID of the step to replace.

`replacementStep`^Required

Type: JobStep

The replacement step.

Inherits the original step's ID.

`updateJob`

public updateJob(id: string, job: JobCallingReusableWorkflow | Job): void

Updates a single job to the workflow.

`id`^Required

Type: string

The job name (unique within the workflow).

`job`^Required

Type: JobCallingReusableWorkflow | Job

`updateJobs`

public updateJobs(jobs: {[ key: string ]: JobCallingReusableWorkflow | Job}): void

Updates jobs for this workflow Does a complete replace, it does not try to merge the jobs.

`jobs`^Required

Type: {[ key: string ]: JobCallingReusableWorkflow | Job}

Jobs to update.

Static Functions

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

`isConstruct`

import { github } from 'projen'

github.TaskWorkflow.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.

`x`^Required

Type: any

Any object.

`isComponent`

import { github } from 'projen'

github.TaskWorkflow.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.
`jobs`	`{[ key: string ]: JobCallingReusableWorkflow \| Job}`	All current jobs of the workflow.
`name`	`string`	The name of the workflow.
`projenCredentials`	`GithubCredentials`	GitHub API authentication method used by projen workflows.
`concurrency`	`ConcurrencyOptions`	The concurrency configuration of the workflow.
`env`	`{[ key: string ]: string}`	Additional environment variables to set for the workflow.
`file`	`projen.YamlFile`	The workflow YAML file.
`runName`	`string`	The name for workflow runs generated from the workflow.
`jobId`	`string`	No description.
`artifactsDirectory`	`string`	No description.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`project`^Required

public readonly project: Project;

Type: projen.Project

`jobs`^Required

public readonly jobs: {[ key: string ]: JobCallingReusableWorkflow | Job};

Type: {[ key: string ]: JobCallingReusableWorkflow | Job}

All current jobs of the workflow.

This is a read-only copy, use the respective helper methods to add, update or remove jobs.

`name`^Required

public readonly name: string;

Type: string

The name of the workflow.

GitHub displays the names of your workflows under your repository's "Actions" tab.

https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#name

`projenCredentials`^Required

public readonly projenCredentials: GithubCredentials;

Type: GithubCredentials

GitHub API authentication method used by projen workflows.

`concurrency`^Optional

public readonly concurrency: ConcurrencyOptions;

Type: ConcurrencyOptions

The concurrency configuration of the workflow.

undefined means no concurrency limitations.

`env`^Optional

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

Type: {[ key: string ]: string}

Additional environment variables to set for the workflow.

`file`^Optional

public readonly file: YamlFile;

Type: projen.YamlFile

The workflow YAML file.

May not exist if workflowsEnabled is false on GitHub.

`runName`^Optional

public readonly runName: string;

Type: string

The name for workflow runs generated from the workflow.

This value can include expressions and can reference github and inputs contexts.

`jobId`^Required

public readonly jobId: string;

Type: string

`artifactsDirectory`^Optional

public readonly artifactsDirectory: string;

Type: string

TaskWorkflowJob

The primary or initial job of a TaskWorkflow.

Initializers

import { github } from 'projen'

new github.TaskWorkflowJob(scope: IConstruct, task: Task, options: TaskWorkflowJobOptions)

Name	Type	Description
`scope`	`constructs.IConstruct`	should be part of the project the Task belongs to.
`task`	`projen.Task`	the main task that is run as part of this job.
`options`	`TaskWorkflowJobOptions`	options to configure the TaskWorkflowJob.

`scope`^Required

Type: constructs.IConstruct

should be part of the project the Task belongs to.

`task`^Required

Type: projen.Task

the main task that is run as part of this job.

`options`^Required

Type: TaskWorkflowJobOptions

options to configure the TaskWorkflowJob.

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.

`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`^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.

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

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

Static Functions

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

`isConstruct`

import { github } from 'projen'

github.TaskWorkflowJob.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.

`x`^Required

Type: any

Any object.

`isComponent`

import { github } from 'projen'

github.TaskWorkflowJob.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.
`permissions`	`JobPermissions`	No description.
`steps`	`JobStep[]`	No description.
`concurrency`	`any`	No description.
`container`	`ContainerOptions`	No description.
`continueOnError`	`boolean`	No description.
`defaults`	`JobDefaults`	No description.
`env`	`{[ key: string ]: string}`	No description.
`environment`	`string`	No description.
`if`	`string`	No description.
`name`	`string`	No description.
`needs`	`string[]`	No description.
`outputs`	`{[ key: string ]: JobStepOutput}`	No description.
`runsOn`	`string[]`	No description.
`runsOnGroup`	`projen.GroupRunnerOptions`	No description.
`services`	`{[ key: string ]: ContainerOptions}`	No description.
`strategy`	`JobStrategy`	No description.
`timeoutMinutes`	`number`	No description.
`tools`	`Tools`	No description.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`project`^Required

public readonly project: Project;

Type: projen.Project

`permissions`^Required

public readonly permissions: JobPermissions;

Type: JobPermissions

`steps`^Required

public readonly steps: JobStep[];

Type: JobStep[]

`concurrency`^Optional

public readonly concurrency: any;

Type: any

`container`^Optional

public readonly container: ContainerOptions;

Type: ContainerOptions

`continueOnError`^Optional

public readonly continueOnError: boolean;

Type: boolean

`defaults`^Optional

public readonly defaults: JobDefaults;

Type: JobDefaults

`env`^Optional

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

Type: {[ key: string ]: string}

`environment`^Optional

public readonly environment: string;

Type: string

`if`^Optional

public readonly if: string;

Type: string

`name`^Optional

public readonly name: string;

Type: string

`needs`^Optional

public readonly needs: string[];

Type: string[]

`outputs`^Optional

public readonly outputs: {[ key: string ]: JobStepOutput};

Type: {[ key: string ]: JobStepOutput}

`runsOn`^Optional

public readonly runsOn: string[];

Type: string[]

`runsOnGroup`^Optional

public readonly runsOnGroup: GroupRunnerOptions;

Type: projen.GroupRunnerOptions

`services`^Optional

public readonly services: {[ key: string ]: ContainerOptions};

Type: {[ key: string ]: ContainerOptions}

`strategy`^Optional

public readonly strategy: JobStrategy;

Type: JobStrategy

`timeoutMinutes`^Optional

public readonly timeoutMinutes: number;

Type: number

`tools`^Optional

public readonly tools: Tools;

Type: Tools

Structs

AutoApproveOptions

Options for 'AutoApprove'.

Initializer

import { github } from 'projen'

const autoApproveOptions: github.AutoApproveOptions = { ... }

Properties

Name	Type	Description
`runsOn`	`string[]`	Github Runner selection labels.
`runsOnGroup`	`projen.GroupRunnerOptions`	Github Runner Group selection options.
`allowedUsernames`	`string[]`	Only pull requests authored by these Github usernames will be auto-approved.
`credentials`	`GithubCredentials`	The credentials used to approve pull requests.
`label`	`string`	Only pull requests with this label will be auto-approved.
`secret`	`string`	A GitHub secret name which contains a GitHub Access Token with write permissions for the `pull_request` scope.
`sources`	`PullRequestSource[]`	Only pull requests from one of these sources will be auto-approved.

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

`allowedUsernames`^Optional

Deprecated: Use sources with PullRequestSource.fromUsers({ logins }) instead.

public readonly allowedUsernames: string[];

Type: string[]
Default: ['github-actions[bot]']

Only pull requests authored by these Github usernames will be auto-approved.

An empty list approves pull requests from any user.

`credentials`^Optional

public readonly credentials: GithubCredentials;

Type: GithubCredentials
Default: the workflow's GITHUB_TOKEN

The credentials used to approve pull requests.

Github forbids an identity to approve its own pull request. These credentials must belong to a different identity than the one creating the pull requests. Use environment on the credentials to restrict which branches can access them.

`label`^Optional

public readonly label: string;

Type: string
Default: 'auto-approve'

Only pull requests with this label will be auto-approved.

This is required in addition to matching one of the sources.

`secret`^Optional

Deprecated: Use credentials with GithubCredentials.fromPersonalAccessToken({ secret }) instead.

public readonly secret: string;

Type: string
Default: "GITHUB_TOKEN"

A GitHub secret name which contains a GitHub Access Token with write permissions for the pull_request scope.

This token is used to approve pull requests.

Github forbids an identity to approve its own pull request. If your project produces automated pull requests using the Github default token - {@link https://docs.github.com/en/actions/reference/authentication-in-a-workflow GITHUB_TOKEN }

that you would like auto approved, such as when using the depsUpgrade property in NodeProjectOptions, then you must use a different token here.

`sources`^Optional

public readonly sources: PullRequestSource[];

Type: PullRequestSource[]
Default: [PullRequestSource.fromUsers({ logins: ["github-actions[bot]"] })]

Only pull requests from one of these sources will be auto-approved.

Components that create pull requests can add more sources with AutoApprove.addSource(). Providing sources, either here or with addSource(), replaces the default source.

AutoMergeOptions

Initializer

import { github } from 'projen'

const autoMergeOptions: github.AutoMergeOptions = { ... }

Properties

Name	Type	Description
`approvedReviews`	`number`	Number of approved code reviews.
`blockingLabels`	`string[]`	List of labels that will prevent auto-merging.
`queueName`	`string`	Name of the mergify queue.
`ruleName`	`string`	Name of the mergify rule.

`approvedReviews`^Optional

public readonly approvedReviews: number;

Type: number
Default: 1

Number of approved code reviews.

`blockingLabels`^Optional

public readonly blockingLabels: string[];

Type: string[]
Default: ['do-not-merge']

List of labels that will prevent auto-merging.

`queueName`^Optional

public readonly queueName: string;

Type: string
Default: 'default'

Name of the mergify queue.

`ruleName`^Optional

public readonly ruleName: string;

Type: string
Default: 'Automatic merge on approval and successful build'

Name of the mergify rule.

AutoQueueOptions

Options for 'AutoQueue'.

Initializer

import { github } from 'projen'

const autoQueueOptions: github.AutoQueueOptions = { ... }

Properties

Name	Type	Description
`runsOn`	`string[]`	Github Runner selection labels.
`runsOnGroup`	`projen.GroupRunnerOptions`	Github Runner Group selection options.
`allowedUsernames`	`string[]`	Only pull requests authored by these Github usernames will have auto-queue enabled.
`labels`	`string[]`	Only pull requests with one of this labels will have auto-queue enabled.
`mergeMethod`	`MergeMethod`	The method used to add the PR to the merge queue Any branch protection rules must allow this merge method.
`projenCredentials`	`GithubCredentials`	Choose a method for authenticating with GitHub to enable auto-queue on pull requests.
`targetBranches`	`string[]`	The branch names that we should auto-queue for.

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

`allowedUsernames`^Optional

public readonly allowedUsernames: string[];

Type: string[]
Default: pull requests from all users are eligible for auto-queuing

Only pull requests authored by these Github usernames will have auto-queue enabled.

`labels`^Optional

public readonly labels: string[];

Type: string[]
Default: all pull requests are eligible for auto-queueing

Only pull requests with one of this labels will have auto-queue enabled.

`mergeMethod`^Optional

public readonly mergeMethod: MergeMethod;

Type: MergeMethod
Default: MergeMethod.SQUASH

The method used to add the PR to the merge queue Any branch protection rules must allow this merge method.

`projenCredentials`^Optional

public readonly projenCredentials: GithubCredentials;

Type: GithubCredentials
Default: uses credentials from the GitHub component

Choose a method for authenticating with GitHub to enable auto-queue on pull requests.

The workflow cannot use a default github token. Queuing a PR with the default token will not trigger any merge queue workflows, which results in the PR just not getting merged at all.

https://projen.io/docs/integrations/github/

`targetBranches`^Optional

public readonly targetBranches: string[];

Type: string[]

The branch names that we should auto-queue for.

This set of branches should be a subset of MergeQueueOptions.targetBranches.

Be sure not to enable autoQueue for branches that don't have branch rules with merge requirements set up, otherwise new PRs will be merged immediately after creating without a chance for review.

Automatically merging a set of Stacked PRs

If you set this to ['main'] you can automatically merge a set of Stacked PRs in the right order. It works like this:

Create PR #1 from branch a, targeting main.
Create PR #2 from branch b, targeting branch a.
Create PR #3 from branch c, targeting branch b.

Initially, PR #1 will be set to auto-merge, PRs #2 and #3 will not.

Once PR #1 passes all of its requirements it will merge. That will delete branch a and change the target branch of PR #2 change to main. At that point, auto-queueing will switch on for PR #2 and it gets merged, etc.

[!IMPORTANT] This component will never disable AutoMerge, only enable it. So if a PR is initially targeted at one of the branches in this list, and then subsequently retargeted to another branch, AutoMerge is not automatically turned off.

CheckoutOptions

Initializer

import { github } from 'projen'

const checkoutOptions: github.CheckoutOptions = { ... }

Properties

Name	Type	Description
`env`	`{[ key: string ]: string}`	Sets environment variables for steps to use in the runner environment.
`id`	`string`	A unique identifier for the step.
`if`	`string`	You can use the if conditional to prevent a job from running unless a condition is met.
`name`	`string`	A name for your step to display on GitHub.
`shell`	`string`	Overrides the default shell settings in the runner's operating system and the job's default.
`workingDirectory`	`string`	Specifies a working directory for a step.
`background`	`boolean`	Runs a step asynchronously so the job continues to the next step without waiting for it to finish.
`cancel`	`string`	Gracefully terminates a running background step, referenced by its `id`.
`continueOnError`	`boolean`	Prevents a job from failing when a step fails.
`parallel`	`JobStep[]`	Runs a group of steps concurrently, then waits for all of them to finish before continuing.
`timeoutMinutes`	`number`	The maximum number of minutes to run the step before killing the process.
`wait`	`string[]`	Pauses the job until one or more background steps complete. Provide the `id`s of the background steps to wait for.
`waitAll`	`boolean`	Pauses the job until all active background steps complete.
`with`	`CheckoutWith`	Options for `checkout`.

`env`^Optional

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

Type: {[ key: string ]: string}

Sets environment variables for steps to use in the runner environment.

You can also set environment variables for the entire workflow or a job.

`id`^Optional

public readonly id: string;

Type: string

A unique identifier for the step.

You can use the id to reference the step in contexts.

`if`^Optional

public readonly if: string;

Type: string

You can use the if conditional to prevent a job from running unless a condition is met.

You can use any supported context and expression to create a conditional.

`name`^Optional

public readonly name: string;

Type: string

A name for your step to display on GitHub.

`shell`^Optional

public readonly shell: string;

Type: string

Overrides the default shell settings in the runner's operating system and the job's default.

Refer to GitHub documentation for allowed values.

https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsshell

`workingDirectory`^Optional

public readonly workingDirectory: string;

Type: string

Specifies a working directory for a step.

Overrides a job's working directory.

`background`^Optional

public readonly background: boolean;

Type: boolean

Runs a step asynchronously so the job continues to the next step without waiting for it to finish.

Use for long-running processes, such as databases, servers, or monitoring tasks, that need to run alongside other steps.

Synchronize with background steps later using wait or waitAll, or stop them with cancel. Give the step an id so it can be referenced.

A maximum of 10 background steps can run concurrently in a single job; additional background steps are queued until a slot is free.

https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsbackground

`cancel`^Optional

public readonly cancel: string;

Type: string

Gracefully terminates a running background step, referenced by its id.

The runner sends the step's process a termination signal (SIGTERM) so it can clean up, and forcibly stops it (SIGKILL) if it does not exit within a short grace period.

https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepscancel

`continueOnError`^Optional

public readonly continueOnError: boolean;

Type: boolean

Prevents a job from failing when a step fails.

Set to true to allow a job to pass when this step fails.

`parallel`^Optional

public readonly parallel: JobStep[];

Type: JobStep[]

Runs a group of steps concurrently, then waits for all of them to finish before continuing.

This is shorthand for declaring each step with background: true followed by a wait step.

Use this when you have a self-contained group of independent steps that can all run at the same time and don't need to be referenced individually. Use background instead when you need finer control, such as starting a long-running process that stays up while later steps run.

Each step in the group is subject to the same 10-step concurrency limit as other background steps. Cannot be used inside a composite action.

https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsparallel

`timeoutMinutes`^Optional

public readonly timeoutMinutes: number;

Type: number

The maximum number of minutes to run the step before killing the process.

`wait`^Optional

public readonly wait: string[];

Type: string[]

Pauses the job until one or more background steps complete. Provide the ids of the background steps to wait for.

This step performs no work itself; it only blocks until the referenced background steps finish. If a referenced background step failed, the wait step fails too.

https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepswait

`waitAll`^Optional

public readonly waitAll: boolean;

Type: boolean

Pauses the job until all active background steps complete.

Fails if any of the background steps it waits on failed, unless continueOnError is set on this step.

https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepswait-all

`with`^Optional

public readonly with: CheckoutWith;

Type: CheckoutWith

Options for checkout.

CheckoutWith

Options for checkout.

Initializer

import { github } from 'projen'

const checkoutWith: github.CheckoutWith = { ... }

Properties

Name	Type	Description
`fetchDepth`	`number`	Number of commits to fetch.
`lfs`	`boolean`	Whether LFS is enabled for the GitHub repository.
`path`	`string`	Relative path under $GITHUB_WORKSPACE to place the repository.
`ref`	`string`	Branch or tag name.
`repository`	`string`	The repository (owner/repo) to use.
`submodules`	`CheckoutSubmodules`	Whether to checkout Git submodules.
`token`	`string`	A GitHub token to use when checking out the repository.

`fetchDepth`^Optional

public readonly fetchDepth: number;

Type: number
Default: 1

Number of commits to fetch.

0 indicates all history for all branches and tags.

`lfs`^Optional

public readonly lfs: boolean;

Type: boolean
Default: false

Whether LFS is enabled for the GitHub repository.

`path`^Optional

public readonly path: string;

Type: string
Default: $GITHUB_WORKSPACE

Relative path under $GITHUB_WORKSPACE to place the repository.

`ref`^Optional

public readonly ref: string;

Type: string
Default: the default branch is implicitly used

Branch or tag name.

`repository`^Optional

public readonly repository: string;

Type: string
Default: the default repository is implicitly used

The repository (owner/repo) to use.

`submodules`^Optional

public readonly submodules: CheckoutSubmodules;

Type: CheckoutSubmodules
Default: CheckoutSubmodules.DISABLED

Whether to checkout Git submodules.

`token`^Optional

public readonly token: string;

Type: string
Default: the default GITHUB_TOKEN is implicitly used

A GitHub token to use when checking out the repository.

If the intent is to push changes back to the branch, then you must use a PAT with repo (and possibly workflows) permissions.

CheckoutWithPatchOptions

Options for checkoutWithPatch.

Initializer

import { github } from 'projen'

const checkoutWithPatchOptions: github.CheckoutWithPatchOptions = { ... }

Properties

Name	Type	Description
`fetchDepth`	`number`	Number of commits to fetch.
`lfs`	`boolean`	Whether LFS is enabled for the GitHub repository.
`path`	`string`	Relative path under $GITHUB_WORKSPACE to place the repository.
`ref`	`string`	Branch or tag name.
`repository`	`string`	The repository (owner/repo) to use.
`submodules`	`CheckoutSubmodules`	Whether to checkout Git submodules.
`token`	`string`	A GitHub token to use when checking out the repository.
`patchFile`	`string`	The name of the artifact the patch is stored as.

`fetchDepth`^Optional

public readonly fetchDepth: number;

Type: number
Default: 1

Number of commits to fetch.

0 indicates all history for all branches and tags.

`lfs`^Optional

public readonly lfs: boolean;

Type: boolean
Default: false

Whether LFS is enabled for the GitHub repository.

`path`^Optional

public readonly path: string;

Type: string
Default: $GITHUB_WORKSPACE

Relative path under $GITHUB_WORKSPACE to place the repository.

`ref`^Optional

public readonly ref: string;

Type: string
Default: the default branch is implicitly used

Branch or tag name.

`repository`^Optional

public readonly repository: string;

Type: string
Default: the default repository is implicitly used

The repository (owner/repo) to use.

`submodules`^Optional

public readonly submodules: CheckoutSubmodules;

Type: CheckoutSubmodules
Default: CheckoutSubmodules.DISABLED

Whether to checkout Git submodules.

`token`^Optional

public readonly token: string;

Type: string
Default: the default GITHUB_TOKEN is implicitly used

A GitHub token to use when checking out the repository.

If the intent is to push changes back to the branch, then you must use a PAT with repo (and possibly workflows) permissions.

`patchFile`^Optional

public readonly patchFile: string;

Type: string
Default: ".repo.patch"

The name of the artifact the patch is stored as.

ConcurrencyOptions

Options for concurrency.

Initializer

import { github } from 'projen'

const concurrencyOptions: github.ConcurrencyOptions = { ... }

Properties

Name	Type	Description
`cancelInProgress`	`boolean`	When a workflow is triggered while another one (in the same group) is running, should GitHub cancel the running workflow?
`group`	`string`	Concurrency group controls which workflow runs will share the same concurrency limit.

`cancelInProgress`^Optional

public readonly cancelInProgress: boolean;

Type: boolean
Default: false

When a workflow is triggered while another one (in the same group) is running, should GitHub cancel the running workflow?

`group`^Optional

public readonly group: string;

Type: string
Default: ${{ github.workflow }}

Concurrency group controls which workflow runs will share the same concurrency limit.

For example, if you specify ${{ github.workflow }}-${{ github.ref }}, workflow runs triggered on the same branch cannot run concurrently, but workflows runs triggered on different branches can.

https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-concurrency#example-concurrency-groups

ContributorStatementOptions

Options for requiring a contributor statement on Pull Requests.

Initializer

import { github } from 'projen'

const contributorStatementOptions: github.ContributorStatementOptions = { ... }

Properties

Name	Type	Description
`exemptLabels`	`string[]`	Pull requests with one of these labels are exempted from a contributor statement.
`exemptUsers`	`string[]`	Pull requests from these GitHub users are exempted from a contributor statement.

`exemptLabels`^Optional

public readonly exemptLabels: string[];

Type: string[]
Default: no labels are excluded

Pull requests with one of these labels are exempted from a contributor statement.

`exemptUsers`^Optional

public readonly exemptUsers: string[];

Type: string[]
Default: no users are exempted

Pull requests from these GitHub users are exempted from a contributor statement.

CreatePullRequestOptions

Initializer

import { github } from 'projen'

const createPullRequestOptions: github.CreatePullRequestOptions = { ... }

Properties

Name	Type	Description
`pullRequestDescription`	`string`	Description added to the pull request.
`pullRequestTitle`	`string`	The full title used to create the pull request.
`workflowName`	`string`	The name of the workflow that will create the PR.
`addPaths`	`string[]`	Paths to add to the commit, mapping to the action's `add-paths` input.
`assignees`	`string[]`	Assignees to add on the PR.
`baseBranch`	`string`	Sets the pull request base branch.
`branchName`	`string`	The pull request branch name.
`credentials`	`GithubCredentials`	The job credentials used to create the pull request.
`deleteBranch`	`boolean`	Whether to delete the pull request branch when the pull request is closed, mapping to the action's `delete-branch` input.
`gitIdentity`	`GitIdentity`	The git identity used to create the commit.
`labels`	`string[]`	Labels to apply on the PR.
`signoff`	`boolean`	Add Signed-off-by line by the committer at the end of the commit log message.
`stepId`	`string`	The step ID which produces the output which indicates if a patch was created.
`stepName`	`string`	The name of the step displayed on GitHub.

`pullRequestDescription`^Required

public readonly pullRequestDescription: string;

Type: string

Description added to the pull request.

Providence information are automatically added.

`pullRequestTitle`^Required

public readonly pullRequestTitle: string;

Type: string

The full title used to create the pull request.

If PR titles are validated in this repo, the title should comply with the respective rules.

`workflowName`^Required

public readonly workflowName: string;

Type: string

The name of the workflow that will create the PR.

`addPaths`^Optional

public readonly addPaths: string[];

Type: string[]
Default: all paths

Paths to add to the commit, mapping to the action's add-paths input.

`assignees`^Optional

public readonly assignees: string[];

Type: string[]
Default: no assignees

Assignees to add on the PR.

`baseBranch`^Optional

public readonly baseBranch: string;

Type: string
Default: The branch checked out in the workflow.

Sets the pull request base branch.

`branchName`^Optional

public readonly branchName: string;

Type: string
Default: github-actions/${options.workflowName}

The pull request branch name.

`credentials`^Optional

public readonly credentials: GithubCredentials;

Type: GithubCredentials

The job credentials used to create the pull request.

Provided credentials must have permissions to create a pull request on the repository.

`deleteBranch`^Optional

public readonly deleteBranch: boolean;

Type: boolean
Default: false

Whether to delete the pull request branch when the pull request is closed, mapping to the action's delete-branch input.

`gitIdentity`^Optional

public readonly gitIdentity: GitIdentity;

Type: GitIdentity
Default: default GitHub Actions user

The git identity used to create the commit.

`labels`^Optional

public readonly labels: string[];

Type: string[]
Default: no labels.

Labels to apply on the PR.

`signoff`^Optional

public readonly signoff: boolean;

Type: boolean
Default: true

Add Signed-off-by line by the committer at the end of the commit log message.

`stepId`^Optional

public readonly stepId: string;

Type: string
Default: "create_pr"

The step ID which produces the output which indicates if a patch was created.

`stepName`^Optional

public readonly stepName: string;

Type: string
Default: "Create Pull Request"

The name of the step displayed on GitHub.

DependabotAllow

You can use the allow option to customize which dependencies are updated.

The allow option supports the following options.

Initializer

import { github } from 'projen'

const dependabotAllow: github.DependabotAllow = { ... }

Properties

Name	Type	Description
`dependencyName`	`string`	Use to allow updates for dependencies with matching names, optionally using `*` to match zero or more characters.

`dependencyName`^Required

public readonly dependencyName: string;

Type: string

Use to allow updates for dependencies with matching names, optionally using * to match zero or more characters.

For Java dependencies, the format of the dependency-name attribute is: groupId:artifactId, for example: org.kohsuke:github-api.

DependabotCooldown

Defines a cooldown period for dependency version updates.

https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#cooldown-

Initializer

import { github } from 'projen'

const dependabotCooldown: github.DependabotCooldown = { ... }

Properties

Name	Type	Description
`defaultDays`	`number`	Default cooldown period (in days) for all dependencies without specific semver rules.
`exclude`	`string[]`	List of dependencies excluded from cooldown.
`include`	`string[]`	List of dependencies to apply cooldown to.
`semverMajorDays`	`number`	Cooldown period (in days) for major version updates.
`semverMinorDays`	`number`	Cooldown period (in days) for minor version updates.
`semverPatchDays`	`number`	Cooldown period (in days) for patch version updates.

`defaultDays`^Optional

public readonly defaultDays: number;

Type: number
Default: no default cooldown

Default cooldown period (in days) for all dependencies without specific semver rules.

`exclude`^Optional

public readonly exclude: string[];

Type: string[]
Default: no exclusions

List of dependencies excluded from cooldown.

Supports wildcards. Takes precedence over include.

`include`^Optional

public readonly include: string[];

Type: string[]
Default: all dependencies

List of dependencies to apply cooldown to.

Supports wildcards.

`semverMajorDays`^Optional

public readonly semverMajorDays: number;

Type: number
Default: uses defaultDays

Cooldown period (in days) for major version updates.

`semverMinorDays`^Optional

public readonly semverMinorDays: number;

Type: number
Default: uses defaultDays

Cooldown period (in days) for minor version updates.

`semverPatchDays`^Optional

public readonly semverPatchDays: number;

Type: number
Default: uses defaultDays

Cooldown period (in days) for patch version updates.

DependabotGroup

Defines a single group for dependency updates.

https://docs.github.com/en/code-security/dependabot/working-with-dependabot/dependabot-options-reference#groups--

Initializer

import { github } from 'projen'

const dependabotGroup: github.DependabotGroup = { ... }

Properties

Name	Type	Description
`patterns`	`string[]`	Define a list of strings (with or without wildcards) that will match package names to form this dependency group.
`appliesTo`	`DependabotGroupAppliesTo`	Specify which type of update the group applies to.
`dependencyType`	`DependabotGroupDependencyType`	Limit the group to a type of dependency.
`excludePatterns`	`string[]`	Optionally you can use this to exclude certain dependencies from the group.
`updateTypes`	`DependabotGroupUpdateType[]`	Limit the group to one or more semantic versioning levels.

`patterns`^Required

public readonly patterns: string[];

Type: string[]

Define a list of strings (with or without wildcards) that will match package names to form this dependency group.

`appliesTo`^Optional

public readonly appliesTo: DependabotGroupAppliesTo;

Type: DependabotGroupAppliesTo
Default: version updates

Specify which type of update the group applies to.

`dependencyType`^Optional

public readonly dependencyType: DependabotGroupDependencyType;

Type: DependabotGroupDependencyType
Default: all types of dependencies

Limit the group to a type of dependency.

https://docs.github.com/en/code-security/dependabot/working-with-dependabot/dependabot-options-reference#dependency-type-groups

`excludePatterns`^Optional

public readonly excludePatterns: string[];

Type: string[]

Optionally you can use this to exclude certain dependencies from the group.

`updateTypes`^Optional

public readonly updateTypes: DependabotGroupUpdateType[];

Type: DependabotGroupUpdateType[]
Default: all semantic versioning levels

Limit the group to one or more semantic versioning levels.

If specified, must contain at least one element and elements must be unique.

https://docs.github.com/en/code-security/dependabot/working-with-dependabot/dependabot-options-reference#update-types-groups

DependabotIgnore

You can use the ignore option to customize which dependencies are updated.

The ignore option supports the following options.

Initializer

import { github } from 'projen'

const dependabotIgnore: github.DependabotIgnore = { ... }

Properties

Name	Type	Description
`dependencyName`	`string`	Use to ignore updates for dependencies with matching names, optionally using `*` to match zero or more characters.
`versions`	`string[]`	Use to ignore specific versions or ranges of versions.

`dependencyName`^Required

public readonly dependencyName: string;

Type: string

Use to ignore updates for dependencies with matching names, optionally using * to match zero or more characters.

For Java dependencies, the format of the dependency-name attribute is: groupId:artifactId, for example: org.kohsuke:github-api.

`versions`^Optional

public readonly versions: string[];

Type: string[]

Use to ignore specific versions or ranges of versions.

If you want to define a range, use the standard pattern for the package manager (for example: ^1.0.0 for npm, or ~> 2.0 for Bundler).

DependabotOptions

Initializer

import { github } from 'projen'

const dependabotOptions: github.DependabotOptions = { ... }

Properties

Name	Type	Description
`allow`	`DependabotAllow[]`	https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#allow.
`assignees`	`string[]`	Specify individual assignees or teams of assignees for all pull requests raised for a package manager.
`cooldown`	`DependabotCooldown`	Defines a cooldown period for dependency version updates.
`groups`	`{[ key: string ]: DependabotGroup}`	https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#groups.
`ignore`	`DependabotIgnore[]`	You can use the `ignore` option to customize which dependencies are updated.
`ignoreProjen`	`boolean`	Ignores updates to `projen`.
`labels`	`string[]`	List of labels to apply to the created PR's.
`openPullRequestsLimit`	`number`	Sets the maximum of pull requests Dependabot opens for version updates.
`registries`	`{[ key: string ]: DependabotRegistry}`	Map of package registries to use.
`reviewers`	`string[]`	Specify individual reviewers or teams of reviewers for all pull requests raised for a package manager.
`scheduleInterval`	`DependabotScheduleInterval`	How often to check for new versions and raise pull requests.
`targetBranch`	`string`	https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#target-branch You can configure the target branch for raising pull requests for version updates against.
`versioningStrategy`	`VersioningStrategy`	The strategy to use when edits manifest and lock files.

`allow`^Optional

public readonly allow: DependabotAllow[];

Type: DependabotAllow[]
Default: []

https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#allow.

Use the allow option to customize which dependencies are updated. This applies to both version and security updates.

`assignees`^Optional

public readonly assignees: string[];

Type: string[]
Default: []

Specify individual assignees or teams of assignees for all pull requests raised for a package manager.

`cooldown`^Optional

public readonly cooldown: DependabotCooldown;

Type: DependabotCooldown
Default: no cooldown

Defines a cooldown period for dependency version updates.

During the cooldown, Dependabot will not propose updates for a dependency. This only applies to version updates, not security updates.

https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#cooldown-

`groups`^Optional

public readonly groups: {[ key: string ]: DependabotGroup};

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

https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#groups.

You can create groups to package dependency updates together into a single PR.

`ignore`^Optional

public readonly ignore: DependabotIgnore[];

Type: DependabotIgnore[]
Default: []

You can use the ignore option to customize which dependencies are updated.

The ignore option supports the following options.

`ignoreProjen`^Optional

public readonly ignoreProjen: boolean;

Type: boolean
Default: true

Ignores updates to projen.

This is required since projen updates may cause changes in committed files and anti-tamper checks will fail.

Projen upgrades are covered through the ProjenUpgrade class.

`labels`^Optional

public readonly labels: string[];

Type: string[]

List of labels to apply to the created PR's.

`openPullRequestsLimit`^Optional

public readonly openPullRequestsLimit: number;

Type: number
Default: 5

Sets the maximum of pull requests Dependabot opens for version updates.

Dependabot will not open any new requests until some of those open requests are merged or closed.

`registries`^Optional

public readonly registries: {[ key: string ]: DependabotRegistry};

Type: {[ key: string ]: DependabotRegistry}
Default: use public registries

Map of package registries to use.

`reviewers`^Optional

public readonly reviewers: string[];

Type: string[]
Default: []

Specify individual reviewers or teams of reviewers for all pull requests raised for a package manager.

`scheduleInterval`^Optional

public readonly scheduleInterval: DependabotScheduleInterval;

Type: DependabotScheduleInterval
Default: ScheduleInterval.DAILY

How often to check for new versions and raise pull requests.

`targetBranch`^Optional

public readonly targetBranch: string;

Type: string

https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#target-branch You can configure the target branch for raising pull requests for version updates against.

`versioningStrategy`^Optional

public readonly versioningStrategy: VersioningStrategy;

Type: VersioningStrategy
Default: VersioningStrategy.LOCKFILE_ONLY The default is to only update the lock file because package.json is controlled by projen and any outside updates will fail the build.

The strategy to use when edits manifest and lock files.

DependabotRegistry

Use to add private registry support for dependabot.

https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/configuration-options-for-dependency-updates#configuration-options-for-private-registries

Initializer

import { github } from 'projen'

const dependabotRegistry: github.DependabotRegistry = { ... }

Properties

Name	Type	Description
`type`	`DependabotRegistryType`	Registry type e.g. 'npm-registry' or 'docker-registry'.
`url`	`string`	Url for the registry e.g. 'https://npm.pkg.github.com' or 'registry.hub.docker.com'.
`key`	`string`	A reference to a Dependabot secret containing an access key for this registry.
`organization`	`string`	Used with the hex-organization registry type.
`password`	`string`	A reference to a Dependabot secret containing the password for the specified user.
`replacesBase`	`boolean`	For registries with type: python-index, if the boolean value is true, pip esolves dependencies by using the specified URL rather than the base URL of the Python Package Index (by default https://pypi.org/simple).
`token`	`string`	Secret token for dependabot access e.g. '${{ secrets.DEPENDABOT_PACKAGE_TOKEN }}'.
`username`	`string`	The username that Dependabot uses to access the registry.

`type`^Required

public readonly type: DependabotRegistryType;

Type: DependabotRegistryType

Registry type e.g. 'npm-registry' or 'docker-registry'.

`url`^Required

public readonly url: string;

Type: string

Url for the registry e.g. 'https://npm.pkg.github.com' or 'registry.hub.docker.com'.

`key`^Optional

public readonly key: string;

Type: string
Default: undefined

A reference to a Dependabot secret containing an access key for this registry.

`organization`^Optional

public readonly organization: string;

Type: string
Default: undefined

Used with the hex-organization registry type.

https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/configuration-options-for-dependency-updates#hex-organization

`password`^Optional

public readonly password: string;

Type: string
Default: undefined

A reference to a Dependabot secret containing the password for the specified user.

`replacesBase`^Optional

public readonly replacesBase: boolean;

Type: boolean
Default: undefined

For registries with type: python-index, if the boolean value is true, pip esolves dependencies by using the specified URL rather than the base URL of the Python Package Index (by default https://pypi.org/simple).

`token`^Optional

public readonly token: string;

Type: string
Default: undefined

Secret token for dependabot access e.g. '${{ secrets.DEPENDABOT_PACKAGE_TOKEN }}'.

`username`^Optional

public readonly username: string;

Type: string
Default: do not authenticate

The username that Dependabot uses to access the registry.

DependencyReviewOptions

Options for the DependencyReview component.

Initializer

import { github } from 'projen'

const dependencyReviewOptions: github.DependencyReviewOptions = { ... }

Properties

Name	Type	Description
`runsOn`	`string[]`	Github Runner selection labels.
`runsOnGroup`	`projen.GroupRunnerOptions`	Github Runner Group selection options.
`allowGhsas`	`string[]`	GitHub Advisory Database IDs that can be skipped during detection.
`allowLicenses`	`string[]`	List of allowed SPDX license identifiers.
`commentSummaryInPr`	`string`	Whether to post a comment summary on the PR.
`configFile`	`string`	Path to an external configuration file.
`denyPackages`	`string[]`	Packages to block in a PR (in purl format).
`failOnScopes`	`string[]`	Scopes of dependencies to fail on.
`failOnSeverity`	`string`	The severity level at which the action will fail.
`licenseCheck`	`boolean`	Enable or disable the license check.
`showOpenSSFScorecard`	`boolean`	Show OpenSSF Scorecard scores for dependencies.
`vulnerabilityCheck`	`boolean`	Enable or disable the vulnerability check.
`warnOnly`	`boolean`	When true, the action will only warn and not fail.
`warnOnOpenSSFScorecardLevel`	`number`	Score threshold for OpenSSF Scorecard warnings.

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

`allowGhsas`^Optional

public readonly allowGhsas: string[];

Type: string[]
Default: no advisories are skipped

GitHub Advisory Database IDs that can be skipped during detection.

`allowLicenses`^Optional

public readonly allowLicenses: string[];

Type: string[]
Default: no license allow-list

List of allowed SPDX license identifiers.

`commentSummaryInPr`^Optional

public readonly commentSummaryInPr: string;

Type: string
Default: "always"

Whether to post a comment summary on the PR.

`configFile`^Optional

public readonly configFile: string;

Type: string
Default: no external config

Path to an external configuration file.

`denyPackages`^Optional

public readonly denyPackages: string[];

Type: string[]
Default: no packages are denied

Packages to block in a PR (in purl format).

`failOnScopes`^Optional

public readonly failOnScopes: string[];

Type: string[]
Default: no scopes filter (action default is "runtime")

Scopes of dependencies to fail on.

`failOnSeverity`^Optional

public readonly failOnSeverity: string;

Type: string
Default: no minimum severity (action default is "low")

The severity level at which the action will fail.

`licenseCheck`^Optional

public readonly licenseCheck: boolean;

Type: boolean
Default: true

Enable or disable the license check.

`showOpenSSFScorecard`^Optional

public readonly showOpenSSFScorecard: boolean;

Type: boolean
Default: true

Show OpenSSF Scorecard scores for dependencies.

`vulnerabilityCheck`^Optional

public readonly vulnerabilityCheck: boolean;

Type: boolean
Default: true

Enable or disable the vulnerability check.

`warnOnly`^Optional

public readonly warnOnly: boolean;

Type: boolean
Default: false

When true, the action will only warn and not fail.

`warnOnOpenSSFScorecardLevel`^Optional

public readonly warnOnOpenSSFScorecardLevel: number;

Type: number
Default: 3

Score threshold for OpenSSF Scorecard warnings.

DownloadArtifactOptions

Initializer

import { github } from 'projen'

const downloadArtifactOptions: github.DownloadArtifactOptions = { ... }

Properties

Name	Type	Description
`env`	`{[ key: string ]: string}`	Sets environment variables for steps to use in the runner environment.
`id`	`string`	A unique identifier for the step.
`if`	`string`	You can use the if conditional to prevent a job from running unless a condition is met.
`name`	`string`	A name for your step to display on GitHub.
`shell`	`string`	Overrides the default shell settings in the runner's operating system and the job's default.
`workingDirectory`	`string`	Specifies a working directory for a step.
`background`	`boolean`	Runs a step asynchronously so the job continues to the next step without waiting for it to finish.
`cancel`	`string`	Gracefully terminates a running background step, referenced by its `id`.
`continueOnError`	`boolean`	Prevents a job from failing when a step fails.
`parallel`	`JobStep[]`	Runs a group of steps concurrently, then waits for all of them to finish before continuing.
`timeoutMinutes`	`number`	The maximum number of minutes to run the step before killing the process.
`wait`	`string[]`	Pauses the job until one or more background steps complete. Provide the `id`s of the background steps to wait for.
`waitAll`	`boolean`	Pauses the job until all active background steps complete.
`with`	`DownloadArtifactWith`	Options for `download-artifact`.

`env`^Optional

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

Type: {[ key: string ]: string}

Sets environment variables for steps to use in the runner environment.

You can also set environment variables for the entire workflow or a job.

`id`^Optional

public readonly id: string;

Type: string

A unique identifier for the step.

You can use the id to reference the step in contexts.

`if`^Optional

public readonly if: string;

Type: string

You can use the if conditional to prevent a job from running unless a condition is met.

You can use any supported context and expression to create a conditional.

`name`^Optional

public readonly name: string;

Type: string

A name for your step to display on GitHub.

`shell`^Optional

public readonly shell: string;

Type: string

Overrides the default shell settings in the runner's operating system and the job's default.

Refer to GitHub documentation for allowed values.

https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsshell

`workingDirectory`^Optional

public readonly workingDirectory: string;

Type: string

Specifies a working directory for a step.

Overrides a job's working directory.

`background`^Optional

public readonly background: boolean;

Type: boolean

Runs a step asynchronously so the job continues to the next step without waiting for it to finish.

Use for long-running processes, such as databases, servers, or monitoring tasks, that need to run alongside other steps.

Synchronize with background steps later using wait or waitAll, or stop them with cancel. Give the step an id so it can be referenced.

A maximum of 10 background steps can run concurrently in a single job; additional background steps are queued until a slot is free.

https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsbackground

`cancel`^Optional

public readonly cancel: string;

Type: string

Gracefully terminates a running background step, referenced by its id.

The runner sends the step's process a termination signal (SIGTERM) so it can clean up, and forcibly stops it (SIGKILL) if it does not exit within a short grace period.

https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepscancel

`continueOnError`^Optional

public readonly continueOnError: boolean;

Type: boolean

Prevents a job from failing when a step fails.

Set to true to allow a job to pass when this step fails.

`parallel`^Optional

public readonly parallel: JobStep[];

Type: JobStep[]

Runs a group of steps concurrently, then waits for all of them to finish before continuing.

This is shorthand for declaring each step with background: true followed by a wait step.

Each step in the group is subject to the same 10-step concurrency limit as other background steps. Cannot be used inside a composite action.

https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsparallel

`timeoutMinutes`^Optional

public readonly timeoutMinutes: number;

Type: number

The maximum number of minutes to run the step before killing the process.

`wait`^Optional

public readonly wait: string[];

Type: string[]

Pauses the job until one or more background steps complete. Provide the ids of the background steps to wait for.

This step performs no work itself; it only blocks until the referenced background steps finish. If a referenced background step failed, the wait step fails too.

https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepswait

`waitAll`^Optional

public readonly waitAll: boolean;

Type: boolean

Pauses the job until all active background steps complete.

Fails if any of the background steps it waits on failed, unless continueOnError is set on this step.

https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepswait-all

`with`^Required

public readonly with: DownloadArtifactWith;

Type: DownloadArtifactWith

Options for download-artifact.

DownloadArtifactWith

Initializer

import { github } from 'projen'

const downloadArtifactWith: github.DownloadArtifactWith = { ... }

Properties

Name	Type	Description
`artifactIds`	`string[]`	IDs of the artifacts to download.
`mergeMultiple`	`boolean`	When multiple artifacts are matched, this changes the behavior of the destination directories If true, the downloaded artifacts will be in the same directory specified by path If false, the downloaded artifacts will be extracted into individual named directories within the specified path.
`name`	`string`	Name of the artifact to download.
`path`	`string`	A file, directory or wildcard pattern that describes what to download.
`pattern`	`string`	A glob pattern to the artifacts that should be downloaded This is ignored if name is specified.
`repository`	`string`	The repository owner and the repository name joined together by "/" If github-token is specified, this is the repository that artifacts will be downloaded from.
`runId`	`string`	The id of the workflow run where the desired download artifact was uploaded from If github-token is specified, this is the run that artifacts will be downloaded from.
`token`	`string`	The GitHub token used to authenticate with the GitHub API to download artifacts from a different repository or from a different workflow run.

`artifactIds`^Optional

public readonly artifactIds: string[];

Type: string[]

IDs of the artifacts to download.

Either inputs artifact-ids or name can be used, but not both.

`mergeMultiple`^Optional

public readonly mergeMultiple: boolean;

Type: boolean
Default: false

When multiple artifacts are matched, this changes the behavior of the destination directories If true, the downloaded artifacts will be in the same directory specified by path If false, the downloaded artifacts will be extracted into individual named directories within the specified path.

`name`^Optional

public readonly name: string;

Type: string
Default: If unspecified, all artifacts for the run are downloaded

Name of the artifact to download.

`path`^Optional

public readonly path: string;

Type: string
Default: $GITHUB_WORKSPACE

A file, directory or wildcard pattern that describes what to download.

Supports basic tilde expansion.

`pattern`^Optional

public readonly pattern: string;

Type: string

A glob pattern to the artifacts that should be downloaded This is ignored if name is specified.

`repository`^Optional

public readonly repository: string;

Type: string
Default: ${{ github.repository }}

The repository owner and the repository name joined together by "/" If github-token is specified, this is the repository that artifacts will be downloaded from.

`runId`^Optional

public readonly runId: string;

Type: string
Default: ${{ github.run_id }}

The id of the workflow run where the desired download artifact was uploaded from If github-token is specified, this is the run that artifacts will be downloaded from.

`token`^Optional

public readonly token: string;

Type: string
Default: If unspecified, the action will download artifacts from the current repo and the current workflow run

The GitHub token used to authenticate with the GitHub API to download artifacts from a different repository or from a different workflow run.

GithubCredentialsAppOptions

Options for GithubCredentials.fromApp.

Initializer

import { github } from 'projen'

const githubCredentialsAppOptions: github.GithubCredentialsAppOptions = { ... }

Properties

Name	Type	Description
`appIdSecret`	`string`	The secret containing the GitHub App ID.
`environment`	`string`	The GitHub Actions environment the secrets are added to.
`owner`	`string`	The owner of the GitHub App installation.
`permissions`	`AppPermissions`	The permissions granted to the token.
`privateKeySecret`	`string`	The secret containing the GitHub App private key.
`repositories`	`string[]`	List of repositories to grant access to.

`appIdSecret`^Optional

public readonly appIdSecret: string;

Type: string
Default: "PROJEN_APP_ID"

The secret containing the GitHub App ID.

`environment`^Optional

public readonly environment: string;

Type: string
Default: no environment used

The GitHub Actions environment the secrets are added to.

This can be used to add explicit approval steps to access the secrets.

`owner`^Optional

public readonly owner: string;

Type: string
Default: if empty, defaults to the current repository owner

The owner of the GitHub App installation.

`permissions`^Optional

public readonly permissions: AppPermissions;

Type: AppPermissions
Default: all permissions granted to the app

The permissions granted to the token.

`privateKeySecret`^Optional

public readonly privateKeySecret: string;

Type: string
Default: "PROJEN_APP_PRIVATE_KEY"

The secret containing the GitHub App private key.

Escaped newlines (\n) will be automatically replaced with actual newlines.

`repositories`^Optional

public readonly repositories: string[];

Type: string[]
Default: if owner is set and repositories is empty, access will be scoped to all repositories in the provided repository owner's installation. If owner and repositories are empty, access will be scoped to only the current repository.

List of repositories to grant access to.

GithubCredentialsPersonalAccessTokenOptions

Options for GithubCredentials.fromPersonalAccessToken.

Initializer

import { github } from 'projen'

const githubCredentialsPersonalAccessTokenOptions: github.GithubCredentialsPersonalAccessTokenOptions = { ... }

Properties

Name	Type	Description
`environment`	`string`	The GitHub Actions environment the secrets is added to.
`secret`	`string`	The name of the secret that holds the GitHub personal access token.

`environment`^Optional

public readonly environment: string;

Type: string
Default: no environment used

The GitHub Actions environment the secrets is added to.

This can be used to add explicit approval steps to access the secret.

`secret`^Optional

public readonly secret: string;

Type: string
Default: "PROJEN_GITHUB_TOKEN"

The name of the secret that holds the GitHub personal access token.

GitHubOptions

Initializer

import { github } from 'projen'

const gitHubOptions: github.GitHubOptions = { ... }

Properties

Name	Type	Description
`checkoutSubmodules`	`CheckoutSubmodules`	Whether to checkout Git submodules.
`dependencyReview`	`boolean`	Enable the dependency-review-action workflow on pull requests.
`dependencyReviewOptions`	`DependencyReviewOptions`	Options for the dependency review workflow.
`downloadLfs`	`boolean`	Download files in LFS in workflows.
`mergeQueue`	`boolean`	Whether a merge queue should be used on this repository to merge pull requests.
`mergeQueueOptions`	`MergeQueueOptions`	Options for MergeQueue.
`mergify`	`boolean`	Whether mergify should be enabled on this repository or not.
`mergifyOptions`	`MergifyOptions`	Options for Mergify.
`projenCredentials`	`GithubCredentials`	Choose a method of providing GitHub API access for projen workflows.
`pullRequestBackport`	`boolean`	Add a workflow that allows backport of PRs to other branches using labels.
`pullRequestBackportOptions`	`PullRequestBackportOptions`	Options for configuring pull request backport.
`pullRequestLint`	`boolean`	Add a workflow that performs basic checks for pull requests, like validating that PRs follow Conventional Commits.
`pullRequestLintOptions`	`PullRequestLintOptions`	Options for configuring a pull request linter.
`workflowRunsOn`	`string[]`	Github Runner selection labels.
`workflowRunsOnGroup`	`projen.GroupRunnerOptions`	Github Runner Group selection options.
`workflows`	`boolean`	Enables GitHub workflows.

`checkoutSubmodules`^Optional

public readonly checkoutSubmodules: CheckoutSubmodules;

Type: CheckoutSubmodules
Default: CheckoutSubmodules.DISABLED

Whether to checkout Git submodules.

`dependencyReview`^Optional

public readonly dependencyReview: boolean;

Type: boolean
Default: false

Enable the dependency-review-action workflow on pull requests.

Adds a separate workflow that runs actions/dependency-review-action to scan pull requests for newly introduced vulnerable or non-compliant dependencies.

`dependencyReviewOptions`^Optional

public readonly dependencyReviewOptions: DependencyReviewOptions;

Type: DependencyReviewOptions
Default: default options

Options for the dependency review workflow.

Only used when dependencyReview is true.

`downloadLfs`^Optional

public readonly downloadLfs: boolean;

Type: boolean
Default: true if the associated project has lfsPatterns, false otherwise

Download files in LFS in workflows.

`mergeQueue`^Optional

public readonly mergeQueue: boolean;

Type: boolean
Default: false

Whether a merge queue should be used on this repository to merge pull requests.

Requires additional configuration of the repositories branch protection rules.

`mergeQueueOptions`^Optional

public readonly mergeQueueOptions: MergeQueueOptions;

Type: MergeQueueOptions
Default: default options

Options for MergeQueue.

`mergify`^Optional

public readonly mergify: boolean;

Type: boolean
Default: true

Whether mergify should be enabled on this repository or not.

`mergifyOptions`^Optional

public readonly mergifyOptions: MergifyOptions;

Type: MergifyOptions
Default: default options

Options for Mergify.

`projenCredentials`^Optional

public readonly projenCredentials: GithubCredentials;

Type: GithubCredentials
Default: use a personal access token named PROJEN_GITHUB_TOKEN

Choose a method of providing GitHub API access for projen workflows.

`pullRequestBackport`^Optional

public readonly pullRequestBackport: boolean;

Type: boolean
Default: false

Add a workflow that allows backport of PRs to other branches using labels.

When opening a new PR add a backport label to it, and the PR will be backported to the target branches once the PR is merged.

Should not be used together with mergify.

`pullRequestBackportOptions`^Optional

public readonly pullRequestBackportOptions: PullRequestBackportOptions;

Type: PullRequestBackportOptions
Default: see defaults in PullRequestBackportOptions

Options for configuring pull request backport.

`pullRequestLint`^Optional

public readonly pullRequestLint: boolean;

Type: boolean
Default: true

Add a workflow that performs basic checks for pull requests, like validating that PRs follow Conventional Commits.

`pullRequestLintOptions`^Optional

public readonly pullRequestLintOptions: PullRequestLintOptions;

Type: PullRequestLintOptions
Default: see defaults in PullRequestLintOptions

Options for configuring a pull request linter.

`workflowRunsOn`^Optional

public readonly workflowRunsOn: string[];

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

Github Runner selection labels.

`workflowRunsOnGroup`^Optional

public readonly workflowRunsOnGroup: GroupRunnerOptions;

Type: projen.GroupRunnerOptions

Github Runner Group selection options.

`workflows`^Optional

public readonly workflows: boolean;

Type: boolean
Default: true

Enables GitHub workflows.

If this is set to false, workflows will not be created.

GitHubProjectOptions

Options for GitHubProject.

Initializer

import { github } from 'projen'

const gitHubProjectOptions: github.GitHubProjectOptions = { ... }

Properties

Name	Type	Description
`name`	`string`	This is the name of your project.
`commitGenerated`	`boolean`	Whether to commit the managed files by default.
`gitIgnoreOptions`	`projen.IgnoreFileOptions`	Configuration options for .gitignore file.
`gitOptions`	`projen.GitOptions`	Configuration options for git.
`logging`	`projen.LoggerOptions`	Configure logging options such as verbosity.
`outdir`	`string`	The root directory of the project.
`parent`	`projen.Project`	The parent project, if this project is part of a bigger project.
`projectTree`	`boolean`	Generate a project tree file (`.projen/tree.json`) that shows all components and their relationships. Useful for understanding your project structure and debugging.
`projenCommand`	`string`	The shell command to use in order to run the projen CLI.
`projenrcJson`	`boolean`	Generate (once) .projenrc.json (in JSON). Set to `false` in order to disable .projenrc.json generation.
`projenrcJsonOptions`	`projen.ProjenrcJsonOptions`	Options for .projenrc.json.
`renovatebot`	`boolean`	Use renovatebot to handle dependency upgrades.
`renovatebotOptions`	`projen.RenovatebotOptions`	Options for renovatebot.
`autoApproveOptions`	`AutoApproveOptions`	Enable and configure the 'auto approve' workflow.
`autoMerge`	`boolean`	Enable automatic merging on GitHub.
`autoMergeOptions`	`AutoMergeOptions`	Configure options for automatic merging on GitHub.
`clobber`	`boolean`	Add a `clobber` task which resets the repo to origin.
`devContainer`	`boolean`	Add a VSCode development environment (used for GitHub Codespaces).
`github`	`boolean`	Enable GitHub integration.
`githubOptions`	`GitHubOptions`	Options for GitHub integration.
`gitpod`	`boolean`	Add a Gitpod development environment.
`projenCredentials`	`GithubCredentials`	Choose a method of providing GitHub API access for projen workflows.
`readme`	`projen.SampleReadmeProps`	The README setup.
`stale`	`boolean`	Auto-close of stale issues and pull request.
`staleOptions`	`StaleOptions`	Auto-close stale issues and pull requests.
`vscode`	`boolean`	Enable VSCode integration.

`name`^Required

public readonly name: string;

Type: string
Default: $BASEDIR

This is the name of your project.

`commitGenerated`^Optional

public readonly commitGenerated: boolean;

Type: boolean
Default: true

Whether to commit the managed files by default.

`gitIgnoreOptions`^Optional

public readonly gitIgnoreOptions: IgnoreFileOptions;

Type: projen.IgnoreFileOptions

Configuration options for .gitignore file.

`gitOptions`^Optional

public readonly gitOptions: GitOptions;

Type: projen.GitOptions

Configuration options for git.

`logging`^Optional

public readonly logging: LoggerOptions;

Type: projen.LoggerOptions
Default: {}

Configure logging options such as verbosity.

`outdir`^Optional

public readonly outdir: string;

Type: string
Default: "."

The root directory of the project.

Relative to this directory, all files are synthesized.

If this project has a parent, this directory is relative to the parent directory and it cannot be the same as the parent or any of it's other subprojects.

`parent`^Optional

public readonly parent: Project;

Type: projen.Project

The parent project, if this project is part of a bigger project.

`projectTree`^Optional

public readonly projectTree: boolean;

Type: boolean
Default: false

Generate a project tree file (.projen/tree.json) that shows all components and their relationships. Useful for understanding your project structure and debugging.

`projenCommand`^Optional

public readonly projenCommand: string;

Type: string
Default: "npx projen"

The shell command to use in order to run the projen CLI.

Inserted verbatim into task steps, workflows and IDE configuration, and run by each of their shells - locally, in CI and in dev containers. Keep it a plain unquoted command, since shell syntax in it executes in all of them.

Can be used to customize in special environments.

`projenrcJson`^Optional

public readonly projenrcJson: boolean;

Type: boolean
Default: false

Generate (once) .projenrc.json (in JSON). Set to false in order to disable .projenrc.json generation.

`projenrcJsonOptions`^Optional

public readonly projenrcJsonOptions: ProjenrcJsonOptions;

Type: projen.ProjenrcJsonOptions
Default: default options

Options for .projenrc.json.

`renovatebot`^Optional

public readonly renovatebot: boolean;

Type: boolean
Default: false

Use renovatebot to handle dependency upgrades.

`renovatebotOptions`^Optional

public readonly renovatebotOptions: RenovatebotOptions;

Type: projen.RenovatebotOptions
Default: default options

Options for renovatebot.

`autoApproveOptions`^Optional

public readonly autoApproveOptions: AutoApproveOptions;

Type: AutoApproveOptions
Default: auto approve is disabled

Enable and configure the 'auto approve' workflow.

`autoMerge`^Optional

public readonly autoMerge: boolean;

Type: boolean
Default: true

Enable automatic merging on GitHub.

Has no effect if github.mergify is set to false.

`autoMergeOptions`^Optional

public readonly autoMergeOptions: AutoMergeOptions;

Type: AutoMergeOptions
Default: see defaults in AutoMergeOptions

Configure options for automatic merging on GitHub.

Has no effect if github.mergify or autoMerge is set to false.

`clobber`^Optional

public readonly clobber: boolean;

Type: boolean
Default: true, but false for subprojects

Add a clobber task which resets the repo to origin.

`devContainer`^Optional

public readonly devContainer: boolean;

Type: boolean
Default: false

Add a VSCode development environment (used for GitHub Codespaces).

`github`^Optional

public readonly github: boolean;

Type: boolean
Default: true

Enable GitHub integration.

Enabled by default for root projects. Disabled for non-root projects.

`githubOptions`^Optional

public readonly githubOptions: GitHubOptions;

Type: GitHubOptions
Default: see GitHubOptions

Options for GitHub integration.

`gitpod`^Optional

public readonly gitpod: boolean;

Type: boolean
Default: false

Add a Gitpod development environment.

`projenCredentials`^Optional

public readonly projenCredentials: GithubCredentials;

Type: GithubCredentials
Default: use a personal access token named PROJEN_GITHUB_TOKEN

Choose a method of providing GitHub API access for projen workflows.

`readme`^Optional

public readonly readme: SampleReadmeProps;

Type: projen.SampleReadmeProps
Default: { filename: 'README.md', contents: '# replace this' }

The README setup.

Example

"{ filename: 'readme.md', contents: '# title' }"

`stale`^Optional

public readonly stale: boolean;

Type: boolean
Default: false

Auto-close of stale issues and pull request.

See staleOptions for options.

`staleOptions`^Optional

public readonly staleOptions: StaleOptions;

Type: StaleOptions
Default: see defaults in StaleOptions

Auto-close stale issues and pull requests.

To disable set stale to false.

`vscode`^Optional

public readonly vscode: boolean;

Type: boolean
Default: true

Enable VSCode integration.

Enabled by default for root projects. Disabled for non-root projects.

GithubWorkflowOptions

Options for GithubWorkflow.

Initializer

import { github } from 'projen'

const githubWorkflowOptions: github.GithubWorkflowOptions = { ... }

Properties

Name	Type	Description
`concurrencyOptions`	`ConcurrencyOptions`	Concurrency ensures that only a single job or workflow using the same concurrency group will run at a time.
`env`	`{[ key: string ]: string}`	Additional environment variables to set for the workflow.
`fileName`	`string`	Set a custom file name for the workflow definition file. Must include either a .yml or .yaml file extension.
`force`	`boolean`	Force the creation of the workflow even if `workflows` is disabled in `GitHub`.
`limitConcurrency`	`boolean`	Enable concurrency limitations.

`concurrencyOptions`^Optional

public readonly concurrencyOptions: ConcurrencyOptions;

Type: ConcurrencyOptions
Default: { group: ${{ github.workflow }}, cancelInProgress: false }

Concurrency ensures that only a single job or workflow using the same concurrency group will run at a time.

Currently in beta.

https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#concurrency

`env`^Optional

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

Type: {[ key: string ]: string}
Default: no additional environment variables

Additional environment variables to set for the workflow.

`fileName`^Optional

public readonly fileName: string;

Type: string
Default: a path-safe version of the workflow name plus the .yml file ending, e.g. build.yml

Set a custom file name for the workflow definition file. Must include either a .yml or .yaml file extension.

Use this option to set a file name for the workflow file, that is different than the display name.

Example

"my-workflow.yaml"

`force`^Optional

public readonly force: boolean;

Type: boolean
Default: false

Force the creation of the workflow even if workflows is disabled in GitHub.

`limitConcurrency`^Optional

public readonly limitConcurrency: boolean;

Type: boolean
Default: false

Enable concurrency limitations.

Use concurrencyOptions to configure specific non default values.

GitIdentity

Represents the git identity.

Initializer

import { github } from 'projen'

const gitIdentity: github.GitIdentity = { ... }

Properties

Name	Type	Description
`email`	`string`	The email address of the git user.
`name`	`string`	The name of the user.

`email`^Required

public readonly email: string;

Type: string

The email address of the git user.

`name`^Required

public readonly name: string;

Type: string

The name of the user.

MergeQueueOptions

Options for 'MergeQueue'.

Initializer

import { github } from 'projen'

const mergeQueueOptions: github.MergeQueueOptions = { ... }

Properties

Name	Type	Description
`autoQueue`	`boolean`	Should pull requests be queued automatically to be merged once they pass required checks.
`autoQueueOptions`	`AutoQueueOptions`	Configure auto-queue pull requests.
`targetBranches`	`string[]`	The branches that can be merged into using MergeQueue.

`autoQueue`^Optional

public readonly autoQueue: boolean;

Type: boolean
Default: true

Should pull requests be queued automatically to be merged once they pass required checks.

`autoQueueOptions`^Optional

public readonly autoQueueOptions: AutoQueueOptions;

Type: AutoQueueOptions
Default: see AutoQueueOptions

Configure auto-queue pull requests.

`targetBranches`^Optional

public readonly targetBranches: string[];

Type: string[]
Default: all branches

The branches that can be merged into using MergeQueue.

MergifyCommitMessageFormat

Declarative configuration for Mergify commit_message_format.

https://docs.mergify.com/workflow/actions/merge/#customizing-the-commit-message

Initializer

import { github } from 'projen'

const mergifyCommitMessageFormat: github.MergifyCommitMessageFormat = { ... }

Properties

Name	Type	Description
`body`	`string`	Commit body format.
`title`	`string`	Commit title format.
`trailers`	`string[]`	Optional list of trailers to append to the commit message.

`body`^Optional

public readonly body: string;

Type: string

Commit body format.

inherit: use the GitHub repository default merge commit body format

pr-body: use the pull request body
empty: set the commit body to be empty

`title`^Optional

public readonly title: string;

Type: string

Commit title format.

inherit: use the GitHub repository default merge commit title format

pr-title: use the pull request title (with the PR number appended)

`trailers`^Optional

public readonly trailers: string[];

Type: string[]

Optional list of trailers to append to the commit message.

MergifyConditionalOperator

The Mergify conditional operators that can be used are: or and and.

Note: The number of nested conditions is limited to 3.

https://docs.mergify.io/conditions/#combining-conditions-with-operators

Initializer

import { github } from 'projen'

const mergifyConditionalOperator: github.MergifyConditionalOperator = { ... }

Properties

Name	Type	Description
`and`	`string \| MergifyConditionalOperator[]`	No description.
`or`	`string \| MergifyConditionalOperator[]`	No description.

`and`^Optional

public readonly and: (string | MergifyConditionalOperator)[];

Type: string | MergifyConditionalOperator[]

`or`^Optional

public readonly or: (string | MergifyConditionalOperator)[];

Type: string | MergifyConditionalOperator[]

MergifyOptions

Configure Mergify.

This currently only offers a subset of options available.

https://docs.mergify.com/configuration/file-format/

Initializer

import { github } from 'projen'

const mergifyOptions: github.MergifyOptions = { ... }

Properties

Name	Type	Description
`queues`	`MergifyQueue[]`	The available merge queues.
`rules`	`MergifyRule[]`	Pull request automation rules.

`queues`^Optional

public readonly queues: MergifyQueue[];

Type: MergifyQueue[]

The available merge queues.

`rules`^Optional

public readonly rules: MergifyRule[];

Type: MergifyRule[]

Pull request automation rules.

MergifyQueue

Initializer

import { github } from 'projen'

const mergifyQueue: github.MergifyQueue = { ... }

Properties

Name	Type	Description
`name`	`string`	The name of the queue.
`commitMessageFormat`	`MergifyCommitMessageFormat`	When merging with the merge or squash method, configure the title, body, and trailers of the resulting commit.
`commitMessageTemplate`	`string`	Template to use as the commit message when using the merge or squash merge method.
`mergeConditions`	`string \| MergifyConditionalOperator[]`	The list of conditions to match to get the queued pull request merged.
`mergeMethod`	`string`	Merge method to use.
`queueConditions`	`string \| MergifyConditionalOperator[]`	The list of conditions that needs to match to queue the pull request.
`updateMethod`	`string`	Method to use to update the pull request with its base branch when the speculative check is done in-place.

`name`^Required

public readonly name: string;

Type: string

The name of the queue.

`commitMessageFormat`^Optional

public readonly commitMessageFormat: MergifyCommitMessageFormat;

Type: MergifyCommitMessageFormat

When merging with the merge or squash method, configure the title, body, and trailers of the resulting commit.

https://docs.mergify.com/workflow/actions/merge/#customizing-the-commit-message

`commitMessageTemplate`^Optional

Deprecated: Use commitMessageFormat instead.

public readonly commitMessageTemplate: string;

Type: string

Template to use as the commit message when using the merge or squash merge method.

`mergeConditions`^Optional

public readonly mergeConditions: (string | MergifyConditionalOperator)[];

Type: string | MergifyConditionalOperator[]

The list of conditions to match to get the queued pull request merged.

This automatically includes the queueConditions. In case of speculative merge pull request, the merge conditions are evaluated against the temporary pull request instead of the original one.

https://docs.mergify.com/conditions/#conditions

`mergeMethod`^Optional

public readonly mergeMethod: string;

Type: string
Default: "merge"

Merge method to use.

Possible values are merge, squash, rebase or fast-forward. fast-forward is not supported on queues with speculative_checks > 1, batch_size > 1, or with allow_inplace_checks set to false.

`queueConditions`^Optional

public readonly queueConditions: (string | MergifyConditionalOperator)[];

Type: string | MergifyConditionalOperator[]

The list of conditions that needs to match to queue the pull request.

https://docs.mergify.com/conditions/#conditions

`updateMethod`^Optional

public readonly updateMethod: string;

Type: string
Default: merge for all merge methods except fast-forward where rebase is used

Method to use to update the pull request with its base branch when the speculative check is done in-place.

Possible values:

merge to merge the base branch into the pull request.
rebase to rebase the pull request against its base branch.

Note that the rebase method has some drawbacks, see Mergify docs for details.

https://docs.mergify.com/actions/queue/#queue-rules

MergifyRule

Initializer

import { github } from 'projen'

const mergifyRule: github.MergifyRule = { ... }

Properties

Name	Type	Description
`actions`	`{[ key: string ]: any}`	A dictionary made of Actions that will be executed on the matching pull requests.
`conditions`	`string \| MergifyConditionalOperator[]`	A list of Conditions string that must match against the pull request for the rule to be applied.
`name`	`string`	The name of the rule.

`actions`^Required

public readonly actions: {[ key: string ]: any};

Type: {[ key: string ]: any}

A dictionary made of Actions that will be executed on the matching pull requests.

https://docs.mergify.io/actions/#actions

`conditions`^Required

public readonly conditions: (string | MergifyConditionalOperator)[];

Type: string | MergifyConditionalOperator[]

A list of Conditions string that must match against the pull request for the rule to be applied.

https://docs.mergify.io/conditions/#conditions

`name`^Required

public readonly name: string;

Type: string

The name of the rule.

This is not used by the engine directly, but is used when reporting information about a rule.

PullRequestBackportOptions

Initializer

import { github } from 'projen'

const pullRequestBackportOptions: github.PullRequestBackportOptions = { ... }

Properties

Name	Type	Description
`runsOn`	`string[]`	Github Runner selection labels.
`runsOnGroup`	`projen.GroupRunnerOptions`	Github Runner Group selection options.
`autoApproveBackport`	`boolean`	Automatically approve backport PRs if the 'auto approve' workflow is available.
`backportBranchNamePrefix`	`string`	The prefix used to name backport branches.
`backportPRLabels`	`string[]`	The labels added to the created backport PR.
`branches`	`string[]`	List of branches that can be a target for backports.
`createWithConflicts`	`boolean`	Should this created Backport PRs with conflicts.
`labelPrefix`	`string`	The prefix used to detect PRs that should be backported.
`workflowName`	`string`	The name of the workflow.

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

`autoApproveBackport`^Optional

public readonly autoApproveBackport: boolean;

Type: boolean
Default: true

Automatically approve backport PRs if the 'auto approve' workflow is available.

`backportBranchNamePrefix`^Optional

public readonly backportBranchNamePrefix: string;

Type: string
Default: "backport/"

The prefix used to name backport branches.

Make sure to include a separator at the end like / or _.

`backportPRLabels`^Optional

public readonly backportPRLabels: string[];

Type: string[]
Default: ["backport"]

The labels added to the created backport PR.

`branches`^Optional

public readonly branches: string[];

Type: string[]
Default: allow backports to all release branches

List of branches that can be a target for backports.

`createWithConflicts`^Optional

public readonly createWithConflicts: boolean;

Type: boolean
Default: true

Should this created Backport PRs with conflicts.

Conflicts will have to be resolved manually, but a PR is always created. Set to false to prevent the backport PR from being created if there are conflicts.

`labelPrefix`^Optional

public readonly labelPrefix: string;

Type: string
Default: "backport-to-"

The prefix used to detect PRs that should be backported.

`workflowName`^Optional

public readonly workflowName: string;

Type: string
Default: "backport"

The name of the workflow.

PullRequestFromPatchOptions

Initializer

import { github } from 'projen'

const pullRequestFromPatchOptions: github.PullRequestFromPatchOptions = { ... }

Properties

Name	Type	Description
`pullRequestDescription`	`string`	Description added to the pull request.
`pullRequestTitle`	`string`	The full title used to create the pull request.
`workflowName`	`string`	The name of the workflow that will create the PR.
`addPaths`	`string[]`	Paths to add to the commit, mapping to the action's `add-paths` input.
`assignees`	`string[]`	Assignees to add on the PR.
`baseBranch`	`string`	Sets the pull request base branch.
`branchName`	`string`	The pull request branch name.
`credentials`	`GithubCredentials`	The job credentials used to create the pull request.
`deleteBranch`	`boolean`	Whether to delete the pull request branch when the pull request is closed, mapping to the action's `delete-branch` input.
`gitIdentity`	`GitIdentity`	The git identity used to create the commit.
`labels`	`string[]`	Labels to apply on the PR.
`signoff`	`boolean`	Add Signed-off-by line by the committer at the end of the commit log message.
`stepId`	`string`	The step ID which produces the output which indicates if a patch was created.
`stepName`	`string`	The name of the step displayed on GitHub.
`patch`	`PullRequestPatchSource`	Information about the patch that is used to create the pull request.
`jobName`	`string`	The name of the job displayed on GitHub.
`runsOn`	`string[]`	Github Runner selection labels.
`runsOnGroup`	`projen.GroupRunnerOptions`	Github Runner Group selection options.

`pullRequestDescription`^Required

public readonly pullRequestDescription: string;

Type: string

Description added to the pull request.

Providence information are automatically added.

`pullRequestTitle`^Required

public readonly pullRequestTitle: string;

Type: string

The full title used to create the pull request.

If PR titles are validated in this repo, the title should comply with the respective rules.

`workflowName`^Required

public readonly workflowName: string;

Type: string

The name of the workflow that will create the PR.

`addPaths`^Optional

public readonly addPaths: string[];

Type: string[]
Default: all paths

Paths to add to the commit, mapping to the action's add-paths input.

`assignees`^Optional

public readonly assignees: string[];

Type: string[]
Default: no assignees

Assignees to add on the PR.

`baseBranch`^Optional

public readonly baseBranch: string;

Type: string
Default: The branch checked out in the workflow.

Sets the pull request base branch.

`branchName`^Optional

public readonly branchName: string;

Type: string
Default: github-actions/${options.workflowName}

The pull request branch name.

`credentials`^Optional

public readonly credentials: GithubCredentials;

Type: GithubCredentials

The job credentials used to create the pull request.

Provided credentials must have permissions to create a pull request on the repository.

`deleteBranch`^Optional

public readonly deleteBranch: boolean;

Type: boolean
Default: false

Whether to delete the pull request branch when the pull request is closed, mapping to the action's delete-branch input.

`gitIdentity`^Optional

public readonly gitIdentity: GitIdentity;

Type: GitIdentity
Default: default GitHub Actions user

The git identity used to create the commit.

`labels`^Optional

public readonly labels: string[];

Type: string[]
Default: no labels.

Labels to apply on the PR.

`signoff`^Optional

public readonly signoff: boolean;

Type: boolean
Default: true

Add Signed-off-by line by the committer at the end of the commit log message.

`stepId`^Optional

public readonly stepId: string;

Type: string
Default: "create_pr"

The step ID which produces the output which indicates if a patch was created.

`stepName`^Optional

public readonly stepName: string;

Type: string
Default: "Create Pull Request"

The name of the step displayed on GitHub.

`patch`^Required

public readonly patch: PullRequestPatchSource;

Type: PullRequestPatchSource

Information about the patch that is used to create the pull request.

`jobName`^Optional

public readonly jobName: string;

Type: string
Default: "Create Pull Request"

The name of the job displayed on GitHub.

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

PullRequestLintOptions

Options for PullRequestLint.

Initializer

import { github } from 'projen'

const pullRequestLintOptions: github.PullRequestLintOptions = { ... }

Properties

Name	Type	Description
`runsOn`	`string[]`	Github Runner selection labels.
`runsOnGroup`	`projen.GroupRunnerOptions`	Github Runner Group selection options.
`contributorStatement`	`string`	Require a contributor statement to be included in the PR description.
`contributorStatementOptions`	`ContributorStatementOptions`	Options for requiring a contributor statement on Pull Requests.
`semanticTitle`	`boolean`	Validate that pull request titles follow Conventional Commits.
`semanticTitleOptions`	`SemanticTitleOptions`	Options for validating the conventional commit title linter.

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

`contributorStatement`^Optional

public readonly contributorStatement: string;

Type: string
Default: no contributor statement is required

Require a contributor statement to be included in the PR description.

For example confirming that the contribution has been made by the contributor and complies with the project's license.

Appends the statement to the end of the Pull Request template.

`contributorStatementOptions`^Optional

public readonly contributorStatementOptions: ContributorStatementOptions;

Type: ContributorStatementOptions
Default: none

Options for requiring a contributor statement on Pull Requests.

`semanticTitle`^Optional

public readonly semanticTitle: boolean;

Type: boolean
Default: true

Validate that pull request titles follow Conventional Commits.

https://www.conventionalcommits.org/

`semanticTitleOptions`^Optional

public readonly semanticTitleOptions: SemanticTitleOptions;

Type: SemanticTitleOptions
Default: title must start with "feat", "fix", or "chore"

Options for validating the conventional commit title linter.

PullRequestPatchSource

Initializer

import { github } from 'projen'

const pullRequestPatchSource: github.PullRequestPatchSource = { ... }

Properties

Name	Type	Description
`fetchDepth`	`number`	Number of commits to fetch.
`lfs`	`boolean`	Whether LFS is enabled for the GitHub repository.
`path`	`string`	Relative path under $GITHUB_WORKSPACE to place the repository.
`ref`	`string`	Branch or tag name.
`repository`	`string`	The repository (owner/repo) to use.
`submodules`	`CheckoutSubmodules`	Whether to checkout Git submodules.
`token`	`string`	A GitHub token to use when checking out the repository.
`patchFile`	`string`	The name of the artifact the patch is stored as.
`jobId`	`string`	The id of the job that created the patch file.
`outputName`	`string`	The name of the output that indicates if a patch has been created.

`fetchDepth`^Optional

public readonly fetchDepth: number;

Type: number
Default: 1

Number of commits to fetch.

0 indicates all history for all branches and tags.

`lfs`^Optional

public readonly lfs: boolean;

Type: boolean
Default: false

Whether LFS is enabled for the GitHub repository.

`path`^Optional

public readonly path: string;

Type: string
Default: $GITHUB_WORKSPACE

Relative path under $GITHUB_WORKSPACE to place the repository.

`ref`^Optional

public readonly ref: string;

Type: string
Default: the default branch is implicitly used

Branch or tag name.

`repository`^Optional

public readonly repository: string;

Type: string
Default: the default repository is implicitly used

The repository (owner/repo) to use.

`submodules`^Optional

public readonly submodules: CheckoutSubmodules;

Type: CheckoutSubmodules
Default: CheckoutSubmodules.DISABLED

Whether to checkout Git submodules.

`token`^Optional

public readonly token: string;

Type: string
Default: the default GITHUB_TOKEN is implicitly used

A GitHub token to use when checking out the repository.

If the intent is to push changes back to the branch, then you must use a PAT with repo (and possibly workflows) permissions.

`patchFile`^Optional

public readonly patchFile: string;

Type: string
Default: ".repo.patch"

The name of the artifact the patch is stored as.

`jobId`^Required

public readonly jobId: string;

Type: string

The id of the job that created the patch file.

`outputName`^Required

public readonly outputName: string;

Type: string

The name of the output that indicates if a patch has been created.

PullRequestSourceBranchOptions

Options for PullRequestSource.fromBranch.

Initializer

import { github } from 'projen'

const pullRequestSourceBranchOptions: github.PullRequestSourceBranchOptions = { ... }

Properties

Name	Type	Description
`authors`	`string[]`	The GitHub usernames that may author the pull request.
`branch`	`string`	The exact branch the pull request comes from.
`branchPrefix`	`string`	A prefix the branch the pull request comes from must start with.
`targetBranches`	`string[]`	The branches the pull request may target.

`authors`^Optional

public readonly authors: string[];

Type: string[]
Default: any author

The GitHub usernames that may author the pull request.

`branch`^Optional

public readonly branch: string;

Type: string
Default: use branchPrefix

The exact branch the pull request comes from.

`branchPrefix`^Optional

public readonly branchPrefix: string;

Type: string
Default: use branch

A prefix the branch the pull request comes from must start with.

Make sure to include a separator at the end like / or -.

`targetBranches`^Optional

public readonly targetBranches: string[];

Type: string[]
Default: any target branch

The branches the pull request may target.

PullRequestSourceUsersOptions

Options for PullRequestSource.fromUsers.

Initializer

import { github } from 'projen'

const pullRequestSourceUsersOptions: github.PullRequestSourceUsersOptions = { ... }

Properties

Name	Type	Description
`logins`	`string[]`	The GitHub usernames that may author the pull request.

`logins`^Required

public readonly logins: string[];

Type: string[]

The GitHub usernames that may author the pull request.

PullRequestTemplateOptions

Options for PullRequestTemplate.

Initializer

import { github } from 'projen'

const pullRequestTemplateOptions: github.PullRequestTemplateOptions = { ... }

Properties

Name	Type	Description
`lines`	`string[]`	The contents of the template.

`lines`^Optional

public readonly lines: string[];

Type: string[]
Default: a standard default template will be created.

The contents of the template.

You can use addLine() to add additional lines.

SemanticTitleOptions

Options for linting that PR titles follow Conventional Commits.

https://www.conventionalcommits.org/

Initializer

import { github } from 'projen'

const semanticTitleOptions: github.SemanticTitleOptions = { ... }

Properties

Name	Type	Description
`requireScope`	`boolean`	Configure that a scope must always be provided.
`scopes`	`string[]`	Configure which scopes are allowed (newline-delimited).
`types`	`string[]`	Configure a list of commit types that are allowed.

`requireScope`^Optional

public readonly requireScope: boolean;

Type: boolean
Default: false

Configure that a scope must always be provided.

e.g. feat(ui), fix(core)

`scopes`^Optional

public readonly scopes: string[];

Type: string[]
Default: all scopes allowed

Configure which scopes are allowed (newline-delimited).

These are regex patterns auto-wrapped in ^ $.

`types`^Optional

public readonly types: string[];

Type: string[]
Default: ["feat", "fix", "chore"]

Configure a list of commit types that are allowed.

SetupGitIdentityOptions

Initializer

import { github } from 'projen'

const setupGitIdentityOptions: github.SetupGitIdentityOptions = { ... }

Properties

Name	Type	Description
`env`	`{[ key: string ]: string}`	Sets environment variables for steps to use in the runner environment.
`id`	`string`	A unique identifier for the step.
`if`	`string`	You can use the if conditional to prevent a job from running unless a condition is met.
`name`	`string`	A name for your step to display on GitHub.
`shell`	`string`	Overrides the default shell settings in the runner's operating system and the job's default.
`workingDirectory`	`string`	Specifies a working directory for a step.
`background`	`boolean`	Runs a step asynchronously so the job continues to the next step without waiting for it to finish.
`cancel`	`string`	Gracefully terminates a running background step, referenced by its `id`.
`continueOnError`	`boolean`	Prevents a job from failing when a step fails.
`parallel`	`JobStep[]`	Runs a group of steps concurrently, then waits for all of them to finish before continuing.
`timeoutMinutes`	`number`	The maximum number of minutes to run the step before killing the process.
`wait`	`string[]`	Pauses the job until one or more background steps complete. Provide the `id`s of the background steps to wait for.
`waitAll`	`boolean`	Pauses the job until all active background steps complete.
`gitIdentity`	`GitIdentity`	The identity to use.

`env`^Optional

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

Type: {[ key: string ]: string}

Sets environment variables for steps to use in the runner environment.

You can also set environment variables for the entire workflow or a job.

`id`^Optional

public readonly id: string;

Type: string

A unique identifier for the step.

You can use the id to reference the step in contexts.

`if`^Optional

public readonly if: string;

Type: string

You can use the if conditional to prevent a job from running unless a condition is met.

You can use any supported context and expression to create a conditional.

`name`^Optional

public readonly name: string;

Type: string

A name for your step to display on GitHub.

`shell`^Optional

public readonly shell: string;

Type: string

Overrides the default shell settings in the runner's operating system and the job's default.

Refer to GitHub documentation for allowed values.

https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsshell

`workingDirectory`^Optional

public readonly workingDirectory: string;

Type: string

Specifies a working directory for a step.

Overrides a job's working directory.

`background`^Optional

public readonly background: boolean;

Type: boolean

Runs a step asynchronously so the job continues to the next step without waiting for it to finish.

Use for long-running processes, such as databases, servers, or monitoring tasks, that need to run alongside other steps.

Synchronize with background steps later using wait or waitAll, or stop them with cancel. Give the step an id so it can be referenced.

A maximum of 10 background steps can run concurrently in a single job; additional background steps are queued until a slot is free.

https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsbackground

`cancel`^Optional

public readonly cancel: string;

Type: string

Gracefully terminates a running background step, referenced by its id.

The runner sends the step's process a termination signal (SIGTERM) so it can clean up, and forcibly stops it (SIGKILL) if it does not exit within a short grace period.

https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepscancel

`continueOnError`^Optional

public readonly continueOnError: boolean;

Type: boolean

Prevents a job from failing when a step fails.

Set to true to allow a job to pass when this step fails.

`parallel`^Optional

public readonly parallel: JobStep[];

Type: JobStep[]

Runs a group of steps concurrently, then waits for all of them to finish before continuing.

This is shorthand for declaring each step with background: true followed by a wait step.

Each step in the group is subject to the same 10-step concurrency limit as other background steps. Cannot be used inside a composite action.

https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsparallel

`timeoutMinutes`^Optional

public readonly timeoutMinutes: number;

Type: number

The maximum number of minutes to run the step before killing the process.

`wait`^Optional

public readonly wait: string[];

Type: string[]

Pauses the job until one or more background steps complete. Provide the ids of the background steps to wait for.

This step performs no work itself; it only blocks until the referenced background steps finish. If a referenced background step failed, the wait step fails too.

https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepswait

`waitAll`^Optional

public readonly waitAll: boolean;

Type: boolean

Pauses the job until all active background steps complete.

Fails if any of the background steps it waits on failed, unless continueOnError is set on this step.

https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepswait-all

`gitIdentity`^Required

public readonly gitIdentity: GitIdentity;

Type: GitIdentity

The identity to use.

StaleBehavior

Stale behavior.

Initializer

import { github } from 'projen'

const staleBehavior: github.StaleBehavior = { ... }

Properties

Name	Type	Description
`closeMessage`	`string`	The comment to add to the issue/PR when it's closed.
`daysBeforeClose`	`number`	Days until the issue/PR is closed after it is marked as "Stale".
`daysBeforeStale`	`number`	How many days until the issue or pull request is marked as "Stale".
`enabled`	`boolean`	Determines if this behavior is enabled.
`exemptLabels`	`string[]`	Label which exempt an issue/PR from becoming stale.
`staleLabel`	`string`	The label to apply to the issue/PR when it becomes stale.
`staleMessage`	`string`	The comment to add to the issue/PR when it becomes stale.

`closeMessage`^Optional

public readonly closeMessage: string;

Type: string
Default: "Closing this pull request as it hasn't seen activity for a while. Please add a comment

The comment to add to the issue/PR when it's closed.

`daysBeforeClose`^Optional

public readonly daysBeforeClose: number;

Type: number
Default:

Days until the issue/PR is closed after it is marked as "Stale".

Set to -1 to disable.

`daysBeforeStale`^Optional

public readonly daysBeforeStale: number;

Type: number
Default:

How many days until the issue or pull request is marked as "Stale".

Set to -1 to disable.

`enabled`^Optional

public readonly enabled: boolean;

Type: boolean
Default: true

Determines if this behavior is enabled.

Same as setting daysBeforeStale and daysBeforeClose to -1.

`exemptLabels`^Optional

public readonly exemptLabels: string[];

Type: string[]
Default: ["backlog"]

Label which exempt an issue/PR from becoming stale.

Set to [] to disable.

`staleLabel`^Optional

public readonly staleLabel: string;

Type: string
Default: "stale"

The label to apply to the issue/PR when it becomes stale.

`staleMessage`^Optional

public readonly staleMessage: string;

Type: string
Default: "This pull request is now marked as stale because hasn't seen activity for a while. Add a comment or it will be closed soon."

The comment to add to the issue/PR when it becomes stale.

StaleOptions

Options for Stale.

Initializer

import { github } from 'projen'

const staleOptions: github.StaleOptions = { ... }

Properties

Name	Type	Description
`runsOn`	`string[]`	Github Runner selection labels.
`runsOnGroup`	`projen.GroupRunnerOptions`	Github Runner Group selection options.
`issues`	`StaleBehavior`	How to handle stale issues.
`pullRequest`	`StaleBehavior`	How to handle stale pull requests.

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

`issues`^Optional

public readonly issues: StaleBehavior;

Type: StaleBehavior
Default: By default, stale issues with no activity will be marked as stale after 60 days and closed within 7 days.

How to handle stale issues.

`pullRequest`^Optional

public readonly pullRequest: StaleBehavior;

Type: StaleBehavior
Default: By default, pull requests with no activity will be marked as stale after 14 days and closed within 2 days with relevant comments.

How to handle stale pull requests.

TaskWorkflowJobOptions

Options to create the Job associated with a TaskWorkflow.

Initializer

import { github } from 'projen'

const taskWorkflowJobOptions: github.TaskWorkflowJobOptions = { ... }

Properties

Name	Type	Description
`permissions`	`JobPermissions`	Permissions for the build job.
`artifactsDirectory`	`string`	A directory name which contains artifacts to be uploaded (e.g. `dist`). If this is set, the contents of this directory will be uploaded as an artifact at the end of the workflow run, even if other steps fail.
`checkoutSubmodules`	`CheckoutSubmodules`	Whether to checkout Git submodules.
`checkoutWith`	`CheckoutWith`	Override for the `with` property of the source code checkout step.
`condition`	`string`	Adds an 'if' condition to the workflow.
`container`	`ContainerOptions`	No description.
`downloadLfs`	`boolean`	Whether to download files from Git LFS for this workflow.
`env`	`{[ key: string ]: string}`	Workflow environment variables.
`environment`	`string`	The GitHub Actions environment used for the job.
`gitIdentity`	`GitIdentity`	The git identity to use in this workflow.
`jobDefaults`	`JobDefaults`	Default settings for all steps in the TaskWorkflow Job.
`outputs`	`{[ key: string ]: JobStepOutput}`	Mapping of job output names to values/expressions.
`postBuildSteps`	`JobStep[]`	Actions to run after the main build step.
`preBuildSteps`	`JobStep[]`	Steps to run before the main build step.
`preCheckoutSteps`	`JobStep[]`	Initial steps to run before the source code checkout.
`runsOn`	`string[]`	Github Runner selection labels.
`runsOnGroup`	`projen.GroupRunnerOptions`	Github Runner Group selection options.

`permissions`^Required

public readonly permissions: JobPermissions;

Type: JobPermissions

Permissions for the build job.

`artifactsDirectory`^Optional

public readonly artifactsDirectory: string;

Type: string
Default: not set

A directory name which contains artifacts to be uploaded (e.g. dist). If this is set, the contents of this directory will be uploaded as an artifact at the end of the workflow run, even if other steps fail.

`checkoutSubmodules`^Optional

public readonly checkoutSubmodules: CheckoutSubmodules;

Type: CheckoutSubmodules
Default: Use the setting on the corresponding GitHub project

Whether to checkout Git submodules.

`checkoutWith`^Optional

public readonly checkoutWith: CheckoutWith;

Type: CheckoutWith
Default: not set

Override for the with property of the source code checkout step.

`condition`^Optional

public readonly condition: string;

Type: string

Adds an 'if' condition to the workflow.

`container`^Optional

public readonly container: ContainerOptions;

Type: ContainerOptions
Default: default image

`downloadLfs`^Optional

public readonly downloadLfs: boolean;

Type: boolean
Default: Use the setting on the corresponding GitHub project

Whether to download files from Git LFS for this workflow.

`env`^Optional

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

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

Workflow environment variables.

`environment`^Optional

public readonly environment: string;

Type: string
Default: no environment used

The GitHub Actions environment used for the job.

`gitIdentity`^Optional

public readonly gitIdentity: GitIdentity;

Type: GitIdentity
Default: default GitHub Actions user

The git identity to use in this workflow.

`jobDefaults`^Optional

public readonly jobDefaults: JobDefaults;

Type: JobDefaults

Default settings for all steps in the TaskWorkflow Job.

`outputs`^Optional

public readonly outputs: {[ key: string ]: JobStepOutput};

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

Mapping of job output names to values/expressions.

`postBuildSteps`^Optional

public readonly postBuildSteps: JobStep[];

Type: JobStep[]
Default: not set

Actions to run after the main build step.

`preBuildSteps`^Optional

public readonly preBuildSteps: JobStep[];

Type: JobStep[]
Default: not set

Steps to run before the main build step.

`preCheckoutSteps`^Optional

public readonly preCheckoutSteps: JobStep[];

Type: JobStep[]
Default: not set

Initial steps to run before the source code checkout.

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

TaskWorkflowOptions

Options to create a TaskWorkflow.

Initializer

import { github } from 'projen'

const taskWorkflowOptions: github.TaskWorkflowOptions = { ... }

Properties

Name	Type	Description
`permissions`	`JobPermissions`	Permissions for the build job.
`artifactsDirectory`	`string`	A directory name which contains artifacts to be uploaded (e.g. `dist`). If this is set, the contents of this directory will be uploaded as an artifact at the end of the workflow run, even if other steps fail.
`checkoutSubmodules`	`CheckoutSubmodules`	Whether to checkout Git submodules.
`checkoutWith`	`CheckoutWith`	Override for the `with` property of the source code checkout step.
`condition`	`string`	Adds an 'if' condition to the workflow.
`container`	`ContainerOptions`	No description.
`downloadLfs`	`boolean`	Whether to download files from Git LFS for this workflow.
`env`	`{[ key: string ]: string}`	Workflow environment variables.
`environment`	`string`	The GitHub Actions environment used for the job.
`gitIdentity`	`GitIdentity`	The git identity to use in this workflow.
`jobDefaults`	`JobDefaults`	Default settings for all steps in the TaskWorkflow Job.
`outputs`	`{[ key: string ]: JobStepOutput}`	Mapping of job output names to values/expressions.
`postBuildSteps`	`JobStep[]`	Actions to run after the main build step.
`preBuildSteps`	`JobStep[]`	Steps to run before the main build step.
`preCheckoutSteps`	`JobStep[]`	Initial steps to run before the source code checkout.
`runsOn`	`string[]`	Github Runner selection labels.
`runsOnGroup`	`projen.GroupRunnerOptions`	Github Runner Group selection options.
`name`	`string`	The workflow name.
`task`	`projen.Task`	The main task to be executed.
`jobId`	`string`	The primary job id.
`triggers`	`Triggers`	The triggers for the workflow.

`permissions`^Required

public readonly permissions: JobPermissions;

Type: JobPermissions

Permissions for the build job.

`artifactsDirectory`^Optional

public readonly artifactsDirectory: string;

Type: string
Default: not set

`checkoutSubmodules`^Optional

public readonly checkoutSubmodules: CheckoutSubmodules;

Type: CheckoutSubmodules
Default: Use the setting on the corresponding GitHub project

Whether to checkout Git submodules.

`checkoutWith`^Optional

public readonly checkoutWith: CheckoutWith;

Type: CheckoutWith
Default: not set

Override for the with property of the source code checkout step.

`condition`^Optional

public readonly condition: string;

Type: string

Adds an 'if' condition to the workflow.

`container`^Optional

public readonly container: ContainerOptions;

Type: ContainerOptions
Default: default image

`downloadLfs`^Optional

public readonly downloadLfs: boolean;

Type: boolean
Default: Use the setting on the corresponding GitHub project

Whether to download files from Git LFS for this workflow.

`env`^Optional

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

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

Workflow environment variables.

`environment`^Optional

public readonly environment: string;

Type: string
Default: no environment used

The GitHub Actions environment used for the job.

`gitIdentity`^Optional

public readonly gitIdentity: GitIdentity;

Type: GitIdentity
Default: default GitHub Actions user

The git identity to use in this workflow.

`jobDefaults`^Optional

public readonly jobDefaults: JobDefaults;

Type: JobDefaults

Default settings for all steps in the TaskWorkflow Job.

`outputs`^Optional

public readonly outputs: {[ key: string ]: JobStepOutput};

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

Mapping of job output names to values/expressions.

`postBuildSteps`^Optional

public readonly postBuildSteps: JobStep[];

Type: JobStep[]
Default: not set

Actions to run after the main build step.

`preBuildSteps`^Optional

public readonly preBuildSteps: JobStep[];

Type: JobStep[]
Default: not set

Steps to run before the main build step.

`preCheckoutSteps`^Optional

public readonly preCheckoutSteps: JobStep[];

Type: JobStep[]
Default: not set

Initial steps to run before the source code checkout.

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

`name`^Required

public readonly name: string;

Type: string

The workflow name.

`task`^Required

public readonly task: Task;

Type: projen.Task

The main task to be executed.

`jobId`^Optional

public readonly jobId: string;

Type: string
Default: "build"

The primary job id.

`triggers`^Optional

public readonly triggers: Triggers;

Type: Triggers
Default: by default workflows can only be triggered by manually.

The triggers for the workflow.

UploadArtifactOptions

Initializer

import { github } from 'projen'

const uploadArtifactOptions: github.UploadArtifactOptions = { ... }

Properties

Name	Type	Description
`env`	`{[ key: string ]: string}`	Sets environment variables for steps to use in the runner environment.
`id`	`string`	A unique identifier for the step.
`if`	`string`	You can use the if conditional to prevent a job from running unless a condition is met.
`name`	`string`	A name for your step to display on GitHub.
`shell`	`string`	Overrides the default shell settings in the runner's operating system and the job's default.
`workingDirectory`	`string`	Specifies a working directory for a step.
`background`	`boolean`	Runs a step asynchronously so the job continues to the next step without waiting for it to finish.
`cancel`	`string`	Gracefully terminates a running background step, referenced by its `id`.
`continueOnError`	`boolean`	Prevents a job from failing when a step fails.
`parallel`	`JobStep[]`	Runs a group of steps concurrently, then waits for all of them to finish before continuing.
`timeoutMinutes`	`number`	The maximum number of minutes to run the step before killing the process.
`wait`	`string[]`	Pauses the job until one or more background steps complete. Provide the `id`s of the background steps to wait for.
`waitAll`	`boolean`	Pauses the job until all active background steps complete.
`with`	`UploadArtifactWith`	Options for `upload-artifact`.

`env`^Optional

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

Type: {[ key: string ]: string}

Sets environment variables for steps to use in the runner environment.

You can also set environment variables for the entire workflow or a job.

`id`^Optional

public readonly id: string;

Type: string

A unique identifier for the step.

You can use the id to reference the step in contexts.

`if`^Optional

public readonly if: string;

Type: string

You can use the if conditional to prevent a job from running unless a condition is met.

You can use any supported context and expression to create a conditional.

`name`^Optional

public readonly name: string;

Type: string

A name for your step to display on GitHub.

`shell`^Optional

public readonly shell: string;

Type: string

Overrides the default shell settings in the runner's operating system and the job's default.

Refer to GitHub documentation for allowed values.

https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsshell

`workingDirectory`^Optional

public readonly workingDirectory: string;

Type: string

Specifies a working directory for a step.

Overrides a job's working directory.

`background`^Optional

public readonly background: boolean;

Type: boolean

Runs a step asynchronously so the job continues to the next step without waiting for it to finish.

Use for long-running processes, such as databases, servers, or monitoring tasks, that need to run alongside other steps.

Synchronize with background steps later using wait or waitAll, or stop them with cancel. Give the step an id so it can be referenced.

A maximum of 10 background steps can run concurrently in a single job; additional background steps are queued until a slot is free.

https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsbackground

`cancel`^Optional

public readonly cancel: string;

Type: string

Gracefully terminates a running background step, referenced by its id.

The runner sends the step's process a termination signal (SIGTERM) so it can clean up, and forcibly stops it (SIGKILL) if it does not exit within a short grace period.

https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepscancel

`continueOnError`^Optional

public readonly continueOnError: boolean;

Type: boolean

Prevents a job from failing when a step fails.

Set to true to allow a job to pass when this step fails.

`parallel`^Optional

public readonly parallel: JobStep[];

Type: JobStep[]

Runs a group of steps concurrently, then waits for all of them to finish before continuing.

This is shorthand for declaring each step with background: true followed by a wait step.

Each step in the group is subject to the same 10-step concurrency limit as other background steps. Cannot be used inside a composite action.

https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsparallel

`timeoutMinutes`^Optional

public readonly timeoutMinutes: number;

Type: number

The maximum number of minutes to run the step before killing the process.

`wait`^Optional

public readonly wait: string[];

Type: string[]

Pauses the job until one or more background steps complete. Provide the ids of the background steps to wait for.

This step performs no work itself; it only blocks until the referenced background steps finish. If a referenced background step failed, the wait step fails too.

https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepswait

`waitAll`^Optional

public readonly waitAll: boolean;

Type: boolean

Pauses the job until all active background steps complete.

Fails if any of the background steps it waits on failed, unless continueOnError is set on this step.

https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepswait-all

`with`^Required

public readonly with: UploadArtifactWith;

Type: UploadArtifactWith

Options for upload-artifact.

UploadArtifactWith

Initializer

import { github } from 'projen'

const uploadArtifactWith: github.UploadArtifactWith = { ... }

Properties

Name	Type	Description
`path`	`string`	A file, directory or wildcard pattern that describes what to upload.
`compressionLevel`	`number`	The level of compression for Zlib to be applied to the artifact archive.
`ifNoFilesFound`	`string`	The desired behavior if no files are found using the provided path.
`includeHiddenFiles`	`boolean`	Whether to include hidden files in the provided path in the artifact.
`name`	`string`	Name of the artifact to upload.
`overwrite`	`boolean`	Whether action should overwrite an existing artifact with the same name (should one exist).
`retentionDays`	`number`	Duration after which artifact will expire in days. 0 means using default repository retention.

`path`^Required

public readonly path: string;

Type: string

A file, directory or wildcard pattern that describes what to upload.

`compressionLevel`^Optional

public readonly compressionLevel: number;

Type: number
Default: 6

The level of compression for Zlib to be applied to the artifact archive.

The value can range from 0 to 9. For large files that are not easily compressed, a value of 0 is recommended for significantly faster uploads.

`ifNoFilesFound`^Optional

public readonly ifNoFilesFound: string;

Type: string
Default: "warn"

The desired behavior if no files are found using the provided path.

Available Options: warn: Output a warning but do not fail the action error: Fail the action with an error message ignore: Do not output any warnings or errors, the action does not fail

`includeHiddenFiles`^Optional

public readonly includeHiddenFiles: boolean;

Type: boolean
Default: false

Whether to include hidden files in the provided path in the artifact.

The file contents of any hidden files in the path should be validated before enabled this to avoid uploading sensitive information.

`name`^Optional

public readonly name: string;

Type: string
Default: "artifact"

Name of the artifact to upload.

`overwrite`^Optional

public readonly overwrite: boolean;

Type: boolean
Default: true

Whether action should overwrite an existing artifact with the same name (should one exist).

Introduced in v4 and represents a breaking change from the behavior of the v3 action. To maintain backwards compatibility with existing, this should be set the true (the default).

`retentionDays`^Optional

public readonly retentionDays: number;

Type: number
Default: The default repository retention

Duration after which artifact will expire in days. 0 means using default repository retention.

Minimum 1 day. Maximum 90 days unless changed from the repository settings page.

UploadGitPatchOptions

Options for uploadGitPatch.

Initializer

import { github } from 'projen'

const uploadGitPatchOptions: github.UploadGitPatchOptions = { ... }

Properties

Name	Type	Description
`outputName`	`string`	The name of the output to emit.
`stepId`	`string`	The step ID which produces the output which indicates if a patch was created.
`mutationError`	`string`	Fail if a mutation was found and print this error message.
`patchFile`	`string`	The name of the artifact the patch is stored as.
`stepName`	`string`	The name of the step.

`outputName`^Required

public readonly outputName: string;

Type: string

The name of the output to emit.

It will be set to true if there was a diff.

`stepId`^Required

public readonly stepId: string;

Type: string

The step ID which produces the output which indicates if a patch was created.

`mutationError`^Optional

public readonly mutationError: string;

Type: string
Default: do not fail upon mutation

Fail if a mutation was found and print this error message.

`patchFile`^Optional

public readonly patchFile: string;

Type: string
Default: ".repo.patch"

The name of the artifact the patch is stored as.

`stepName`^Optional

public readonly stepName: string;

Type: string
Default: "Find mutations"

The name of the step.

Classes

ActionRefs

Fully qualified references (owner/repo@ref) for GitHub Actions.

Use these when authoring workflow steps, so that every step references a reviewed action version.

Constants

Name	Type	Description
`ACTIONS_CHECKOUT`	`string`	actions/checkout at v7.0.1.
`ACTIONS_CREATE_GITHUB_APP_TOKEN`	`string`	actions/create-github-app-token at v3.2.0 (immutable).
`ACTIONS_DEPENDENCY_REVIEW_ACTION`	`string`	actions/dependency-review-action at v5.0.0.
`ACTIONS_DOWNLOAD_ARTIFACT`	`string`	actions/download-artifact at v8.0.1.
`ACTIONS_GITHUB_SCRIPT`	`string`	actions/github-script at v9.0.0.
`ACTIONS_SETUP_DOTNET`	`string`	actions/setup-dotnet at v6.0.0 (immutable).
`ACTIONS_SETUP_GO`	`string`	actions/setup-go at v7.0.0 (immutable).
`ACTIONS_SETUP_JAVA`	`string`	actions/setup-java at v6.0.0 (immutable).
`ACTIONS_SETUP_NODE`	`string`	actions/setup-node at v7.0.0 (immutable).
`ACTIONS_SETUP_PYTHON`	`string`	actions/setup-python at v7.0.0 (immutable).
`ACTIONS_STALE`	`string`	actions/stale at v11.0.0 (immutable).
`ACTIONS_UPLOAD_ARTIFACT`	`string`	actions/upload-artifact at v7.0.1.
`AMANNN_ACTION_SEMANTIC_PULL_REQUEST`	`string`	amannn/action-semantic-pull-request at v6.1.1.
`AWS_ACTIONS_CONFIGURE_AWS_CREDENTIALS`	`string`	aws-actions/configure-aws-credentials at v6.2.3 (immutable).
`CODECOV_CODECOV_ACTION`	`string`	codecov/codecov-action at v7.0.0 (immutable).
`OVEN_SH_SETUP_BUN`	`string`	oven-sh/setup-bun at v2.2.0.
`PETER_EVANS_CREATE_PULL_REQUEST`	`string`	peter-evans/create-pull-request at v8.1.1 (immutable).
`PNPM_ACTION_SETUP`	`string`	pnpm/action-setup at v6.0.10 (immutable).
`SQREN_BACKPORT_GITHUB_ACTION`	`string`	sqren/backport-github-action at v12.0.4.

`ACTIONS_CHECKOUT`^Required

public readonly ACTIONS_CHECKOUT: string;

Type: string

actions/checkout at v7.0.1.

`ACTIONS_CREATE_GITHUB_APP_TOKEN`^Required

public readonly ACTIONS_CREATE_GITHUB_APP_TOKEN: string;

Type: string

actions/create-github-app-token at v3.2.0 (immutable).

`ACTIONS_DEPENDENCY_REVIEW_ACTION`^Required

public readonly ACTIONS_DEPENDENCY_REVIEW_ACTION: string;

Type: string

actions/dependency-review-action at v5.0.0.

`ACTIONS_DOWNLOAD_ARTIFACT`^Required

public readonly ACTIONS_DOWNLOAD_ARTIFACT: string;

Type: string

actions/download-artifact at v8.0.1.

`ACTIONS_GITHUB_SCRIPT`^Required

public readonly ACTIONS_GITHUB_SCRIPT: string;

Type: string

actions/github-script at v9.0.0.

`ACTIONS_SETUP_DOTNET`^Required

public readonly ACTIONS_SETUP_DOTNET: string;

Type: string

actions/setup-dotnet at v6.0.0 (immutable).

`ACTIONS_SETUP_GO`^Required

public readonly ACTIONS_SETUP_GO: string;

Type: string

actions/setup-go at v7.0.0 (immutable).

`ACTIONS_SETUP_JAVA`^Required

public readonly ACTIONS_SETUP_JAVA: string;

Type: string

actions/setup-java at v6.0.0 (immutable).

`ACTIONS_SETUP_NODE`^Required

public readonly ACTIONS_SETUP_NODE: string;

Type: string

actions/setup-node at v7.0.0 (immutable).

`ACTIONS_SETUP_PYTHON`^Required

public readonly ACTIONS_SETUP_PYTHON: string;

Type: string

actions/setup-python at v7.0.0 (immutable).

`ACTIONS_STALE`^Required

public readonly ACTIONS_STALE: string;

Type: string

actions/stale at v11.0.0 (immutable).

`ACTIONS_UPLOAD_ARTIFACT`^Required

public readonly ACTIONS_UPLOAD_ARTIFACT: string;

Type: string

actions/upload-artifact at v7.0.1.

`AMANNN_ACTION_SEMANTIC_PULL_REQUEST`^Required

public readonly AMANNN_ACTION_SEMANTIC_PULL_REQUEST: string;

Type: string

amannn/action-semantic-pull-request at v6.1.1.

`AWS_ACTIONS_CONFIGURE_AWS_CREDENTIALS`^Required

public readonly AWS_ACTIONS_CONFIGURE_AWS_CREDENTIALS: string;

Type: string

aws-actions/configure-aws-credentials at v6.2.3 (immutable).

`CODECOV_CODECOV_ACTION`^Required

public readonly CODECOV_CODECOV_ACTION: string;

Type: string

codecov/codecov-action at v7.0.0 (immutable).

`OVEN_SH_SETUP_BUN`^Required

public readonly OVEN_SH_SETUP_BUN: string;

Type: string

oven-sh/setup-bun at v2.2.0.

`PETER_EVANS_CREATE_PULL_REQUEST`^Required

public readonly PETER_EVANS_CREATE_PULL_REQUEST: string;

Type: string

peter-evans/create-pull-request at v8.1.1 (immutable).

`PNPM_ACTION_SETUP`^Required

public readonly PNPM_ACTION_SETUP: string;

Type: string

pnpm/action-setup at v6.0.10 (immutable).

`SQREN_BACKPORT_GITHUB_ACTION`^Required

public readonly SQREN_BACKPORT_GITHUB_ACTION: string;

Type: string

sqren/backport-github-action at v12.0.4.

GitHubActionsProvider

Manage the versions used for GitHub Actions used in steps.

Initializers

import { github } from 'projen'

new github.GitHubActionsProvider()

Name	Type	Description

Methods

Name	Description
`get`	Resolve an action name to the version that should be used, taking into account any overrides.
`set`	Define an override for a given action.

`get`

public get(action: string): string

Resolve an action name to the version that should be used, taking into account any overrides.

`action`^Required

Type: string

`set`

public set(action: string, override: string): void

Define an override for a given action.

Specify the action name without a version to override all usages of the action. You can also override a specific action version, by providing the version string. Specific overrides take precedence over overrides without a version.

If an override for the same action name is set multiple times, the last override is used.

Example

// Force any use of `actions/checkout` to use a pin a specific commit
project.github.actions.set("actions/checkout", "actions/checkout@aaaaaa");

// But pin usage of `v4` to a different commit
project.github.actions.set("actions/checkout@v6", "actions/checkout@ffffff");

`action`^Required

Type: string

`override`^Required

Type: string

GithubCredentials

Represents a method of providing GitHub API access for projen workflows.

Static Functions

Name	Description
`fromApp`	Provide API access through a GitHub App.
`fromPersonalAccessToken`	Provide API access through a GitHub personal access token.

`fromApp`

import { github } from 'projen'

github.GithubCredentials.fromApp(options?: GithubCredentialsAppOptions)

Provide API access through a GitHub App.

The GitHub App must be installed on the GitHub repo, its App ID and a private key must be added as secrets to the repo. The name of the secrets can be specified here.

https://projen.io/docs/integrations/github/#github-app

`options`^Optional

Type: GithubCredentialsAppOptions

`fromPersonalAccessToken`

import { github } from 'projen'

github.GithubCredentials.fromPersonalAccessToken(options?: GithubCredentialsPersonalAccessTokenOptions)

Provide API access through a GitHub personal access token.

The token must be added as a secret to the GitHub repo, and the name of the secret can be specified here.

https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token

`options`^Optional

Type: GithubCredentialsPersonalAccessTokenOptions

Properties

Name	Type	Description
`setupSteps`	`JobStep[]`	Setup steps to obtain GitHub credentials.
`tokenRef`	`string`	The value to use in a workflow when a GitHub token is expected.
`environment`	`string`	The GitHub Actions environment the credentials have been added to.

`setupSteps`^Required

public readonly setupSteps: JobStep[];

Type: JobStep[]

Setup steps to obtain GitHub credentials.

`tokenRef`^Required

public readonly tokenRef: string;

Type: string

The value to use in a workflow when a GitHub token is expected.

This typically looks like "${{ some.path.to.a.value }}".

`environment`^Optional

public readonly environment: string;

Type: string

The GitHub Actions environment the credentials have been added to.

PullRequestSource

Describes where a pull request comes from.

Used to select which pull requests a workflow acts on, e.g. which pull requests are auto-approved.

Static Functions

Name	Description
`fromBranch`	Pull requests from a head branch in this repository.
`fromUsers`	Pull requests authored by any of the given users.

`fromBranch`

import { github } from 'projen'

github.PullRequestSource.fromBranch(options: PullRequestSourceBranchOptions)

Pull requests from a head branch in this repository.

Anyone who can push to the head branch controls the content of the pull request. Protect the matching branches with a ruleset that only allows the intended automation to create, update and delete them.

`options`^Required

Type: PullRequestSourceBranchOptions

`fromUsers`

import { github } from 'projen'

github.PullRequestSource.fromUsers(options: PullRequestSourceUsersOptions)

Pull requests authored by any of the given users.

Anyone with access to the credentials of these users can author a matching pull request.

`options`^Required

Type: PullRequestSourceUsersOptions

WorkflowActions

A set of utility functions for creating GitHub actions in workflows.

Initializers

import { github } from 'projen'

new github.WorkflowActions()

Name	Type	Description

Static Functions

Name	Description
`checkoutWithPatch`	Checks out a repository and applies a git patch that was created using `uploadGitPatch`.
`createPullRequest`	A step that creates a pull request based on the current repo state.
`uploadGitPatch`	Creates a .patch file from the current git diff and uploads it as an artifact. Use `checkoutWithPatch` to download and apply in another job.

`checkoutWithPatch`

import { github } from 'projen'

github.WorkflowActions.checkoutWithPatch(options?: CheckoutWithPatchOptions)

Checks out a repository and applies a git patch that was created using uploadGitPatch.

`options`^Optional

Type: CheckoutWithPatchOptions

Options.

`createPullRequest`

import { github } from 'projen'

github.WorkflowActions.createPullRequest(options: CreatePullRequestOptions)

A step that creates a pull request based on the current repo state.

`options`^Required

Type: CreatePullRequestOptions

Options.

`uploadGitPatch`

import { github } from 'projen'

github.WorkflowActions.uploadGitPatch(options: UploadGitPatchOptions)

Creates a .patch file from the current git diff and uploads it as an artifact. Use checkoutWithPatch to download and apply in another job.

If a patch was uploaded, the action can optionally fail the job.

`options`^Required

Type: UploadGitPatchOptions

Options.

WorkflowJobs

A set of utility functions for creating jobs in GitHub Workflows.

Initializers

import { github } from 'projen'

new github.WorkflowJobs()

Name	Type	Description

Static Functions

Name	Description
`pullRequestFromPatch`	Creates a pull request with the changes of a patch file.

`pullRequestFromPatch`

import { github } from 'projen'

github.WorkflowJobs.pullRequestFromPatch(options: PullRequestFromPatchOptions)

Creates a pull request with the changes of a patch file.

`options`^Required

Type: PullRequestFromPatchOptions

WorkflowSteps

A collection of very commonly used, individual, GitHub Workflow Job steps.

Initializers

import { github } from 'projen'

new github.WorkflowSteps()

Name	Type	Description

Static Functions

Name	Description
`checkout`	Checks out a repository.
`downloadArtifact`	Downloads an artifact.
`setupGitIdentity`	Configures the git identity (user name and email).
`tagExists`	Checks if a tag exists.
`uploadArtifact`	Uploads an artifact.

`checkout`

import { github } from 'projen'

github.WorkflowSteps.checkout(options?: CheckoutOptions)

Checks out a repository.

`options`^Optional

Type: CheckoutOptions

Options to configure the checkout JobStep.

`downloadArtifact`

import { github } from 'projen'

github.WorkflowSteps.downloadArtifact(options?: DownloadArtifactOptions)

Downloads an artifact.

`options`^Optional

Type: DownloadArtifactOptions

Options to configure the download-artifact JobStep.

`setupGitIdentity`

import { github } from 'projen'

github.WorkflowSteps.setupGitIdentity(options: SetupGitIdentityOptions)

Configures the git identity (user name and email).

`options`^Required

Type: SetupGitIdentityOptions

Options to configure the git identity JobStep.

`tagExists`

import { github } from 'projen'

github.WorkflowSteps.tagExists(tag: string, options: JobStepConfiguration)

Checks if a tag exists.

Requires a checkout step to have been run before this step with "fetch-depth" set to "0".

Outputs:

exists: A string value of 'true' or 'false' indicating if the tag exists.

`tag`^Required

Type: string

The tag to check.

You may use valid bash code instead of a literal string in this field.

`options`^Required

Type: JobStepConfiguration

Options to configure the tag-exists JobStep.

`uploadArtifact`

import { github } from 'projen'

github.WorkflowSteps.uploadArtifact(options: UploadArtifactOptions)

Uploads an artifact.

`options`^Required

Type: UploadArtifactOptions

Options to configure the upload-artifact JobStep.

Protocols

IAddConditionsLater

Implemented By: IAddConditionsLater

Methods

Name	Description
`render`	No description.

`render`

public render(): string[]

Enums

CheckoutSubmodules

Whether to checkout Git submodules in CI workflows.

Members

Name	Description
`DISABLED`	Don't checkout submodules.
`ENABLED`	Checkout only top-level submodules.
`RECURSIVE`	Checkout submodules recursively.

`DISABLED`

Don't checkout submodules.

`ENABLED`

Checkout only top-level submodules.

`RECURSIVE`

Checkout submodules recursively.

DependabotGroupAppliesTo

The type of update a group applies to.

Members

Name	Description
`VERSION_UPDATES`	Apply only to version updates.
`SECURITY_UPDATES`	Apply only to security updates.

`VERSION_UPDATES`

Apply only to version updates.

`SECURITY_UPDATES`

Apply only to security updates.

DependabotGroupDependencyType

The type of dependency a group may be limited to.

Members

Name	Description
`DEVELOPMENT`	Include only dependencies in the "Development dependency group".
`PRODUCTION`	Include only dependencies in the "Production dependency group".

`DEVELOPMENT`

Include only dependencies in the "Development dependency group".

`PRODUCTION`

Include only dependencies in the "Production dependency group".

DependabotGroupUpdateType

The semantic versioning levels a group may be limited to.

Members

Name	Description
`MAJOR`	Include major releases.
`MINOR`	Include minor releases.
`PATCH`	Include patch releases.

`MAJOR`

Include major releases.

`MINOR`

Include minor releases.

`PATCH`

Include patch releases.

DependabotRegistryType

Each configuration type requires you to provide particular settings.

Some types allow more than one way to connect

https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/configuration-options-for-dependency-updates#configuration-options-for-private-registries

Members

Name	Description
`COMPOSER_REGISTRY`	The composer-repository type supports username and password.
`DOCKER_REGISTRY`	The docker-registry type supports username and password.
`GIT`	The git type supports username and password.
`HEX_ORGANIZATION`	The hex-organization type supports organization and key.
`MAVEN_REPOSITORY`	The maven-repository type supports username and password, or token.
`NPM_REGISTRY`	The npm-registry type supports username and password, or token.
`NUGET_FEED`	The nuget-feed type supports username and password, or token.
`PYTHON_INDEX`	The python-index type supports username and password, or token.
`RUBYGEMS_SERVER`	The rubygems-server type supports username and password, or token.
`TERRAFORM_REGISTRY`	The terraform-registry type supports a token.

`COMPOSER_REGISTRY`

The composer-repository type supports username and password.

https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/configuration-options-for-dependency-updates#composer-repository

`DOCKER_REGISTRY`

The docker-registry type supports username and password.

The docker-registry type can also be used to pull from Amazon ECR using static AWS credentials

https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/configuration-options-for-dependency-updates#docker-registry

`GIT`

The git type supports username and password.

https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/configuration-options-for-dependency-updates#git

`HEX_ORGANIZATION`

The hex-organization type supports organization and key.

https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/configuration-options-for-dependency-updates#hex-organization

`MAVEN_REPOSITORY`

The maven-repository type supports username and password, or token.

https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/configuration-options-for-dependency-updates#maven-repository

`NPM_REGISTRY`

The npm-registry type supports username and password, or token.

https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/configuration-options-for-dependency-updates#npm-registry

`NUGET_FEED`

The nuget-feed type supports username and password, or token.

https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/configuration-options-for-dependency-updates#nuget-feed

`PYTHON_INDEX`

The python-index type supports username and password, or token.

https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/configuration-options-for-dependency-updates#python-index

`RUBYGEMS_SERVER`

The rubygems-server type supports username and password, or token.

https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/configuration-options-for-dependency-updates#rubygems-server

`TERRAFORM_REGISTRY`

The terraform-registry type supports a token.

https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/configuration-options-for-dependency-updates#terraform-registry

DependabotScheduleInterval

How often to check for new versions and raise pull requests for version updates.

Members

Name	Description
`DAILY`	Runs on every weekday, Monday to Friday.
`WEEKLY`	Runs once each week.
`MONTHLY`	Runs once each month.

`DAILY`

Runs on every weekday, Monday to Friday.

`WEEKLY`

Runs once each week.

By default, this is on Monday.

`MONTHLY`

Runs once each month.

This is on the first day of the month.

MergeMethod

The merge method used to add the PR to the merge queue.

Behavior can be further configured in repository settings.

Members

Name	Description
`SQUASH`	No description.
`MERGE`	No description.
`REBASE`	No description.

`SQUASH`

`MERGE`

`REBASE`

VersioningStrategy

The strategy to use when edits manifest and lock files.

Members

Name	Description
`LOCKFILE_ONLY`	Only create pull requests to update lockfiles updates.
`AUTO`	- For apps, the version requirements are increased.
`WIDEN`	Relax the version requirement to include both the new and old version, when possible.
`INCREASE`	Always increase the version requirement to match the new version.
`INCREASE_IF_NECESSARY`	Increase the version requirement only when required by the new version.

`LOCKFILE_ONLY`

Only create pull requests to update lockfiles updates.

Ignore any new versions that would require package manifest changes.

`AUTO`

For apps, the version requirements are increased.

For libraries, the range of versions is widened.

`WIDEN`

Relax the version requirement to include both the new and old version, when possible.

`INCREASE`

Always increase the version requirement to match the new version.

`INCREASE_IF_NECESSARY`

Increase the version requirement only when required by the new version.

Constructs ​

AutoApprove ​

Initializers ​

githubRequired ​

optionsOptional ​

Methods ​

toString ​

with ​

mixinsRequired ​

postProjectCreation ​

initProjectRequired ​

postSynthesize ​

preSynthesize ​

projectCreation ​

initProjectRequired ​

synthesize ​

addSource ​

sourceRequired ​

Static Functions ​

isConstruct ​

xRequired ​

isComponent ​

xRequired ​

Properties ​

nodeRequired ​

projectRequired ​

labelRequired ​

AutoMerge ​

Initializers ​

githubRequired ​

optionsOptional ​

Methods ​

toString ​

with ​

mixinsRequired ​

postProjectCreation ​

initProjectRequired ​

postSynthesize ​

preSynthesize ​

projectCreation ​

initProjectRequired ​

synthesize ​

addConditions ​

conditionsRequired ​

addConditionsLater ​

laterRequired ​

Static Functions ​

isConstruct ​

xRequired ​

isComponent ​

xRequired ​

Properties ​

nodeRequired ​

projectRequired ​

AutoQueue ​

Initializers ​

scopeRequired ​

optionsOptional ​

Methods ​

toString ​

with ​

mixinsRequired ​

postProjectCreation ​

initProjectRequired ​

postSynthesize ​

preSynthesize ​

projectCreation ​

initProjectRequired ​

synthesize ​

Static Functions ​

isConstruct ​

xRequired ​

isComponent ​

xRequired ​

Properties ​

nodeRequired ​

projectRequired ​

Dependabot ​

Initializers ​

githubRequired ​

Constructs

AutoApprove

Initializers

`github`^Required

`options`^Optional

Methods

`toString`

`with`

`mixins`^Required

`postProjectCreation`

`initProject`^Required

`postSynthesize`

`preSynthesize`

`projectCreation`

`initProject`^Required

`synthesize`

`addSource`

`source`^Required

Static Functions

`isConstruct`

`x`^Required

`isComponent`

`x`^Required

Properties

`node`^Required

`project`^Required

`label`^Required

AutoMerge

Initializers

`github`^Required

`options`^Optional

Methods

`toString`

`with`

`mixins`^Required

`postProjectCreation`

`initProject`^Required

`postSynthesize`

`preSynthesize`

`projectCreation`

`initProject`^Required

`synthesize`

`addConditions`

`conditions`^Required

`addConditionsLater`

`later`^Required

Static Functions

`isConstruct`

`x`^Required

`isComponent`

`x`^Required

Properties

`node`^Required

`project`^Required

AutoQueue

Initializers

`scope`^Required

`options`^Optional

Methods

`toString`

`with`

`mixins`^Required

`postProjectCreation`

`initProject`^Required

`postSynthesize`

`preSynthesize`

`projectCreation`

`initProject`^Required

`synthesize`

Static Functions

`isConstruct`

`x`^Required

`isComponent`

`x`^Required

Properties

`node`^Required

`project`^Required

Dependabot

Initializers

`github`^Required