Skip to main content

github Submodule

Constructs

AutoApprove

Auto approve pull requests that meet a criteria.

Initializers

import { github } from 'projen'

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

githubRequired

optionsOptional

Methods

NameDescription
toString
Returns a string representation of this construct.
postSynthesize
Called after synthesis.
preSynthesize
Called before synthesis.
synthesize
Synthesizes files to the project output directory.

toString
public toString(): string

Returns a string representation of this construct.

postSynthesize
public postSynthesize(): void

Called after synthesis.

Order is not guaranteed.

preSynthesize
public preSynthesize(): void

Called before synthesis.

synthesize
public synthesize(): void

Synthesizes files to the project output directory.

Static Functions

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

xRequired
  • Type: any

Any object.


isComponent
import { github } from 'projen'

github.AutoApprove.isComponent(x: any)

Test whether the given construct is a component.

xRequired
  • Type: any

Properties

NameTypeDescription
node
constructs.NodeThe tree node.
project
projen.ProjectNo description.
label
stringNo description.

nodeRequired
public readonly node: Node;
  • Type: constructs.Node

The tree node.


projectRequired
public readonly project: Project;
  • Type: projen.Project

labelRequired
public readonly label: string;
  • Type: string

AutoMerge

Sets up mergify to merging approved pull requests.

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.

Initializers

import { github } from 'projen'

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

githubRequired

optionsOptional

Methods

NameDescription
toString
Returns a string representation of this construct.
postSynthesize
Called after synthesis.
preSynthesize
Called before synthesis.
synthesize
Synthesizes files to the project output directory.
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.

postSynthesize
public postSynthesize(): void

Called after synthesis.

Order is not guaranteed.

preSynthesize
public preSynthesize(): void

Called before synthesis.

synthesize
public synthesize(): void

Synthesizes files to the project output directory.

addConditions
public addConditions(conditions: string): void

Adds conditions to the auto merge rule.

conditionsRequired
  • Type: string

The conditions to add (mergify syntax).


addConditionsLater
public addConditionsLater(later: IAddConditionsLater): void

Adds conditions that will be rendered only during synthesis.

laterRequired

The later.


Static Functions

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

Explanation: in JavaScript, multiple copies of the constructs library on disk are seen as independent, completely different libraries. As a consequence, the class Construct in each copy of the constructs library is seen as a different class, and an instance of one class will not test as instanceof the other class. npm install will not create installations like this, but users may manually symlink construct libraries together or use a monorepo tool: in those cases, multiple copies of the constructs library can be accidentally installed, and instanceof will behave unpredictably. It is safest to avoid using instanceof, and using this type-testing method instead.

xRequired
  • Type: any

Any object.


isComponent
import { github } from 'projen'

github.AutoMerge.isComponent(x: any)

Test whether the given construct is a component.

xRequired
  • Type: any

Properties

NameTypeDescription
node
constructs.NodeThe tree node.
project
projen.ProjectNo description.

nodeRequired
public readonly node: Node;
  • Type: constructs.Node

The tree node.


projectRequired
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)
NameTypeDescription
github
GitHub
No description.
options
DependabotOptions
No description.

githubRequired

optionsOptional

Methods

NameDescription
toString
Returns a string representation of this construct.
postSynthesize
Called after synthesis.
preSynthesize
Called before synthesis.
synthesize
Synthesizes files to the project output directory.
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.

postSynthesize
public postSynthesize(): void

Called after synthesis.

Order is not guaranteed.

preSynthesize
public preSynthesize(): void

Called before synthesis.

synthesize
public synthesize(): void

Synthesizes files to the project output directory.

addAllow
public addAllow(dependencyName: string): void

Allows a dependency from automatic updates.

dependencyNameRequired
  • 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.

dependencyNameRequired
  • Type: string

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


versionsRequired
  • 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

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

Explanation: in JavaScript, multiple copies of the constructs library on disk are seen as independent, completely different libraries. As a consequence, the class Construct in each copy of the constructs library is seen as a different class, and an instance of one class will not test as instanceof the other class. npm install will not create installations like this, but users may manually symlink construct libraries together or use a monorepo tool: in those cases, multiple copies of the constructs library can be accidentally installed, and instanceof will behave unpredictably. It is safest to avoid using instanceof, and using this type-testing method instead.

xRequired
  • Type: any

Any object.


isComponent
import { github } from 'projen'

github.Dependabot.isComponent(x: any)

Test whether the given construct is a component.

xRequired
  • Type: any

Properties

NameTypeDescription
node
constructs.NodeThe tree node.
project
projen.ProjectNo description.
config
anyThe raw dependabot configuration.
ignoresProjen
booleanWhether or not projen is also upgraded in this config,.

nodeRequired
public readonly node: Node;
  • Type: constructs.Node

The tree node.


projectRequired
public readonly project: Project;
  • Type: projen.Project

configRequired
public readonly config: any;
  • Type: any

The raw dependabot configuration.

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


ignoresProjenRequired
public readonly ignoresProjen: boolean;
  • Type: boolean

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


GitHub

Initializers

import { github } from 'projen'

new github.GitHub(project: Project, options?: GitHubOptions)
NameTypeDescription
project
projen.ProjectNo description.
options
GitHubOptions
No description.

projectRequired
  • Type: projen.Project

optionsOptional

Methods

NameDescription
toString
Returns a string representation of this construct.
postSynthesize
Called after synthesis.
preSynthesize
Called before synthesis.
synthesize
Synthesizes files to the project output directory.
addDependabot
No description.
addPullRequestTemplate
No description.
addWorkflow
Adds a workflow to the project.
tryFindWorkflow
Finds a GitHub workflow by name.

toString
public toString(): string

Returns a string representation of this construct.

postSynthesize
public postSynthesize(): void

Called after synthesis.

Order is not guaranteed.

preSynthesize
public preSynthesize(): void

Called before synthesis.

synthesize
public synthesize(): void

Synthesizes files to the project output directory.

addDependabot
public addDependabot(options?: DependabotOptions): Dependabot
optionsOptional

addPullRequestTemplate
public addPullRequestTemplate(content: string): PullRequestTemplate
contentRequired
  • Type: string

addWorkflow
public addWorkflow(name: string): GithubWorkflow

Adds a workflow to the project.

nameRequired
  • Type: string

Name of the workflow.


tryFindWorkflow
public tryFindWorkflow(name: string): GithubWorkflow

Finds a GitHub workflow by name.

Returns undefined if the workflow cannot be found.

nameRequired
  • Type: string

The name of the GitHub workflow.


Static Functions

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

Explanation: in JavaScript, multiple copies of the constructs library on disk are seen as independent, completely different libraries. As a consequence, the class Construct in each copy of the constructs library is seen as a different class, and an instance of one class will not test as instanceof the other class. npm install will not create installations like this, but users may manually symlink construct libraries together or use a monorepo tool: in those cases, multiple copies of the constructs library can be accidentally installed, and instanceof will behave unpredictably. It is safest to avoid using instanceof, and using this type-testing method instead.

xRequired
  • Type: any

Any object.


isComponent
import { github } from 'projen'

github.GitHub.isComponent(x: any)

Test whether the given construct is a component.

xRequired
  • 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.

projectRequired
  • Type: projen.Project

Properties

NameTypeDescription
node
constructs.NodeThe tree node.
project
projen.ProjectNo description.
actions
GitHubActionsProvider
No description.
downloadLfs
booleanWhether downloading from LFS is enabled for this GitHub project.
projenCredentials
GithubCredentials
GitHub API authentication method used by projen workflows.
workflows
GithubWorkflow[]
All workflows.
workflowsEnabled
booleanAre workflows enabled?
mergify
Mergify
The Mergify configured on this repository.

nodeRequired
public readonly node: Node;
  • Type: constructs.Node

The tree node.


projectRequired
public readonly project: Project;
  • Type: projen.Project

actionsRequired
public readonly actions: GitHubActionsProvider;

downloadLfsRequired
public readonly downloadLfs: boolean;
  • Type: boolean

Whether downloading from LFS is enabled for this GitHub project.


projenCredentialsRequired
public readonly projenCredentials: GithubCredentials;

GitHub API authentication method used by projen workflows.


workflowsRequired
public readonly workflows: GithubWorkflow[];

All workflows.


workflowsEnabledRequired
public readonly workflowsEnabled: boolean;
  • Type: boolean

Are workflows enabled?


mergifyOptional
public readonly mergify: Mergify;

The Mergify configured on this repository.

This is undefined if Mergify was not enabled when creating the repository.


GitHubProject

GitHub-based project.

Initializers

import { github } from 'projen'

new github.GitHubProject(options: GitHubProjectOptions)
NameTypeDescription
options
GitHubProjectOptions
No description.

optionsRequired

Methods

NameDescription
toString
Returns a string representation of 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.
addTip
Prints a "tip" message during synthesis.
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.
tryFindJsonFile
Finds a json file by name.
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.

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.

globsRequired
  • Type: string

The glob patterns to match.


addGitIgnore
public addGitIgnore(pattern: string): void

Adds a .gitignore pattern.

patternRequired
  • 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.

_patternRequired
  • 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.

nameRequired
  • Type: string

The task name to add.


propsOptional
  • Type: projen.TaskOptions

Task properties.


addTip
public addTip(message: string): void

Prints a "tip" message during synthesis.

messageRequired
  • Type: string

The message.


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

globRequired
  • 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.

nameRequired
  • 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>

taskRequired
  • Type: projen.Task

The task for which the command is required.


synth
public synth(): void

Synthesize all project files into outdir.

  1. Call "this.preSynthesize()"
  2. Delete all generated files
  3. Synthesize all subprojects
  4. Synthesize all components of this project
  5. Call "postSynthesize()" for all components of this project
  6. Call "this.postSynthesize()"
tryFindFile
public tryFindFile(filePath: string): FileBase

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

filePathRequired
  • Type: string

The file path.

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


tryFindJsonFile
public tryFindJsonFile(filePath: string): JsonFile

Finds a json file by name.

filePathRequired
  • Type: string

The file path.


tryFindObjectFile
public tryFindObjectFile(filePath: string): ObjectFile

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

filePathRequired
  • 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.

filePathRequired
  • Type: string

The file path.

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


Static Functions

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

Explanation: in JavaScript, multiple copies of the constructs library on disk are seen as independent, completely different libraries. As a consequence, the class Construct in each copy of the constructs library is seen as a different class, and an instance of one class will not test as instanceof the other class. npm install will not create installations like this, but users may manually symlink construct libraries together or use a monorepo tool: in those cases, multiple copies of the constructs library can be accidentally installed, and instanceof will behave unpredictably. It is safest to avoid using instanceof, and using this type-testing method instead.

xRequired
  • Type: any

Any object.


isProject
import { github } from 'projen'

github.GitHubProject.isProject(x: any)

Test whether the given construct is a project.

xRequired
  • 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.

constructRequired
  • Type: constructs.IConstruct

Properties

NameTypeDescription
node
constructs.NodeThe tree node.
buildTask
projen.TaskNo description.
commitGenerated
booleanWhether to commit the managed files by default.
compileTask
projen.TaskNo description.
components
projen.Component[]Returns all the components within this project.
deps
projen.DependenciesProject dependencies.
ejected
booleanWhether or not the project is being ejected.
files
projen.FileBase[]All files in this project.
gitattributes
projen.GitAttributesFileThe .gitattributes file for this repository.
gitignore
projen.IgnoreFile.gitignore.
logger
projen.LoggerLogging utilities.
name
stringProject name.
outdir
stringAbsolute output directory of this project.
packageTask
projen.TaskNo description.
postCompileTask
projen.TaskNo description.
preCompileTask
projen.TaskNo description.
projectBuild
projen.ProjectBuildManages the build process of the project.
projenCommand
stringThe command to use in order to run the projen CLI.
root
projen.ProjectThe root project.
subprojects
projen.Project[]Returns all the subprojects within this project.
tasks
projen.TasksProject tasks.
testTask
projen.TaskNo description.
defaultTask
projen.TaskThis is the "default" task, the one that executes "projen".
initProject
projen.InitProjectThe options used when this project is bootstrapped via projen new.
parent
projen.ProjectA parent project.
projectType
projen.ProjectTypeNo description.
autoApprove
AutoApprove
Auto approve set up for this project.
devContainer
projen.vscode.DevContainerAccess for .devcontainer.json (used for GitHub Codespaces).
github
GitHub
Access all github components.
gitpod
projen.GitpodAccess for Gitpod.
vscode
projen.vscode.VsCodeAccess all VSCode components.

nodeRequired
  • 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.


buildTaskRequired
  • 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

commitGeneratedRequired
  • 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.


compileTaskRequired
  • 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

componentsRequired
  • 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.


depsRequired
  • 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.


ejectedRequired
  • 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.


filesRequired
  • 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.


gitattributesRequired
  • 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.


gitignoreRequired
  • 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.


loggerRequired
  • 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.


nameRequired
  • 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.


outdirRequired
  • 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.


packageTaskRequired
  • 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

postCompileTaskRequired
  • 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

preCompileTaskRequired
  • 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

projectBuildRequired
  • 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.


projenCommandRequired
  • 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.


rootRequired
  • 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.


subprojectsRequired
  • 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.


tasksRequired
  • 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.


testTaskRequired
  • 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

defaultTaskOptional
  • 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.


initProjectOptional
  • 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 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.


parentOptional
  • 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.


projectTypeRequired
  • 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 projectType: ProjectType;
  • Type: projen.ProjectType

autoApproveOptional
  • 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;

Auto approve set up for this project.


devContainerOptional
  • 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


githubOptional
  • 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;

Access all github components.

This will be undefined for subprojects.


gitpodOptional
  • 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


vscodeOptional
  • 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

NameTypeDescription
DEFAULT_TASK
stringThe name of the default task (the task executed when projen is run without arguments).

DEFAULT_TASKRequired
  • 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)
NameTypeDescription
github
GitHub
No description.
name
stringNo description.
options
GithubWorkflowOptions
No description.

githubRequired

nameRequired
  • Type: string

optionsOptional

Methods

NameDescription
toString
Returns a string representation of this construct.
postSynthesize
Called after synthesis.
preSynthesize
Called before synthesis.
synthesize
Synthesizes files to the project output directory.
addJob
Adds a single job to the workflow.
addJobs
Add jobs to the workflow.
getJob
Get a single job from the workflow.
on
Add events to triggers the workflow.
removeJob
Removes a single job to the workflow.
updateJob
Updates a single job to the workflow.
updateJobs
Updates jobs for this worklow Does a complete replace, it does not try to merge the jobs.

toString
public toString(): string

Returns a string representation of this construct.

postSynthesize
public postSynthesize(): void

Called after synthesis.

Order is not guaranteed.

preSynthesize
public preSynthesize(): void

Called before synthesis.

synthesize
public synthesize(): void

Synthesizes files to the project output directory.

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

Adds a single job to the workflow.

idRequired
  • Type: string

The job name (unique within the workflow).


jobRequired

The job specification.


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

Add jobs to the workflow.

jobsRequired

Jobs to add.


getJob
public getJob(id: string): JobCallingReusableWorkflow | Job

Get a single job from the workflow.

idRequired
  • Type: string

The job name (unique within the workflow).


on
public on(events: Triggers): void

Add events to triggers the workflow.

eventsRequired

The event(s) to trigger the workflow.


removeJob
public removeJob(id: string): void

Removes a single job to the workflow.

idRequired
  • Type: string

The job name (unique within the workflow).


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

Updates a single job to the workflow.

idRequired
  • Type: string

The job name (unique within the workflow).


jobRequired

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

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

jobsRequired

Jobs to update.


Static Functions

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

Explanation: in JavaScript, multiple copies of the constructs library on disk are seen as independent, completely different libraries. As a consequence, the class Construct in each copy of the constructs library is seen as a different class, and an instance of one class will not test as instanceof the other class. npm install will not create installations like this, but users may manually symlink construct libraries together or use a monorepo tool: in those cases, multiple copies of the constructs library can be accidentally installed, and instanceof will behave unpredictably. It is safest to avoid using instanceof, and using this type-testing method instead.

xRequired
  • Type: any

Any object.


isComponent
import { github } from 'projen'

github.GithubWorkflow.isComponent(x: any)

Test whether the given construct is a component.

xRequired
  • Type: any

Properties

NameTypeDescription
node
constructs.NodeThe tree node.
project
projen.ProjectNo description.
name
stringThe name of the workflow.
projenCredentials
GithubCredentials
GitHub API authentication method used by projen workflows.
concurrency
stringConcurrency ensures that only a single job or workflow using the same concurrency group will run at a time.
file
projen.YamlFileThe workflow YAML file.
runName
stringThe name for workflow runs generated from the workflow.

nodeRequired
public readonly node: Node;
  • Type: constructs.Node

The tree node.


projectRequired
public readonly project: Project;
  • Type: projen.Project

nameRequired
public readonly name: string;
  • Type: string

The name of the workflow.


projenCredentialsRequired
public readonly projenCredentials: GithubCredentials;

GitHub API authentication method used by projen workflows.


concurrencyOptional
public readonly concurrency: string;
  • Type: string
  • Default: disabled

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


fileOptional
public readonly file: YamlFile;
  • Type: projen.YamlFile

The workflow YAML file.

May not exist if workflowsEnabled is false on GitHub.


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


Mergify

Initializers

import { github } from 'projen'

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

githubRequired

optionsOptional

Methods

NameDescription
toString
Returns a string representation of this construct.
postSynthesize
Called after synthesis.
preSynthesize
Called before synthesis.
synthesize
Synthesizes files to the project output directory.
addQueue
No description.
addRule
No description.

toString
public toString(): string

Returns a string representation of this construct.

postSynthesize
public postSynthesize(): void

Called after synthesis.

Order is not guaranteed.

preSynthesize
public preSynthesize(): void

Called before synthesis.

synthesize
public synthesize(): void

Synthesizes files to the project output directory.

addQueue
public addQueue(queue: MergifyQueue): void
queueRequired

addRule
public addRule(rule: MergifyRule): void
ruleRequired

Static Functions

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

Explanation: in JavaScript, multiple copies of the constructs library on disk are seen as independent, completely different libraries. As a consequence, the class Construct in each copy of the constructs library is seen as a different class, and an instance of one class will not test as instanceof the other class. npm install will not create installations like this, but users may manually symlink construct libraries together or use a monorepo tool: in those cases, multiple copies of the constructs library can be accidentally installed, and instanceof will behave unpredictably. It is safest to avoid using instanceof, and using this type-testing method instead.

xRequired
  • Type: any

Any object.


isComponent
import { github } from 'projen'

github.Mergify.isComponent(x: any)

Test whether the given construct is a component.

xRequired
  • Type: any

Properties

NameTypeDescription
node
constructs.NodeThe tree node.
project
projen.ProjectNo description.

nodeRequired
public readonly node: Node;
  • Type: constructs.Node

The tree node.


projectRequired
public readonly project: Project;
  • Type: projen.Project

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)
NameTypeDescription
github
GitHub
No description.
options
PullRequestLintOptions
No description.

githubRequired

optionsOptional

Methods

NameDescription
toString
Returns a string representation of this construct.
postSynthesize
Called after synthesis.
preSynthesize
Called before synthesis.
synthesize
Synthesizes files to the project output directory.

toString
public toString(): string

Returns a string representation of this construct.

postSynthesize
public postSynthesize(): void

Called after synthesis.

Order is not guaranteed.

preSynthesize
public preSynthesize(): void

Called before synthesis.

synthesize
public synthesize(): void

Synthesizes files to the project output directory.

Static Functions

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

Explanation: in JavaScript, multiple copies of the constructs library on disk are seen as independent, completely different libraries. As a consequence, the class Construct in each copy of the constructs library is seen as a different class, and an instance of one class will not test as instanceof the other class. npm install will not create installations like this, but users may manually symlink construct libraries together or use a monorepo tool: in those cases, multiple copies of the constructs library can be accidentally installed, and instanceof will behave unpredictably. It is safest to avoid using instanceof, and using this type-testing method instead.

xRequired
  • Type: any

Any object.


isComponent
import { github } from 'projen'

github.PullRequestLint.isComponent(x: any)

Test whether the given construct is a component.

xRequired
  • Type: any

Properties

NameTypeDescription
node
constructs.NodeThe tree node.
project
projen.ProjectNo description.

nodeRequired
public readonly node: Node;
  • Type: constructs.Node

The tree node.


projectRequired
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)
NameTypeDescription
github
GitHub
No description.
options
PullRequestTemplateOptions
No description.

githubRequired

optionsOptional

Methods

NameDescription
toString
Returns a string representation of this construct.
postSynthesize
Called after synthesis.
preSynthesize
Called before synthesis.
synthesize
Writes the file to the project's output directory.
addLine
Adds a line to the text file.

toString
public toString(): string

Returns a string representation of this construct.

postSynthesize
public postSynthesize(): void

Called after synthesis.

Order is not guaranteed.

preSynthesize
public preSynthesize(): void

Called before synthesis.

synthesize
public synthesize(): void

Writes the file to the project's output directory.

addLine
public addLine(line: string): void

Adds a line to the text file.

lineRequired
  • Type: string

the line to add (can use tokens).


Static Functions

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

Explanation: in JavaScript, multiple copies of the constructs library on disk are seen as independent, completely different libraries. As a consequence, the class Construct in each copy of the constructs library is seen as a different class, and an instance of one class will not test as instanceof the other class. npm install will not create installations like this, but users may manually symlink construct libraries together or use a monorepo tool: in those cases, multiple copies of the constructs library can be accidentally installed, and instanceof will behave unpredictably. It is safest to avoid using instanceof, and using this type-testing method instead.

xRequired
  • Type: any

Any object.


isComponent
import { github } from 'projen'

github.PullRequestTemplate.isComponent(x: any)

Test whether the given construct is a component.

xRequired
  • 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.

projectRequired
  • Type: projen.Project

The project.


Properties

NameTypeDescription
node
constructs.NodeThe tree node.
project
projen.ProjectNo description.
absolutePath
stringThe absolute path of this file.
path
stringThe file path, relative to the project's outdir.
changed
booleanIndicates if the file has been changed during synthesis.
marker
stringThe projen marker, used to identify files as projen-generated.
executable
booleanIndicates if the file should be marked as executable.
readonly
booleanIndicates if the file should be read-only or read-write.

nodeRequired
public readonly node: Node;
  • Type: constructs.Node

The tree node.


projectRequired
public readonly project: Project;
  • Type: projen.Project

absolutePathRequired
public readonly absolutePath: string;
  • Type: string

The absolute path of this file.


pathRequired
public readonly path: string;
  • Type: string

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


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


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


executableRequired
public readonly executable: boolean;
  • Type: boolean

Indicates if the file should be marked as executable.


readonlyRequired
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)
NameTypeDescription
github
GitHub
No description.
options
StaleOptions
No description.

githubRequired

optionsOptional

Methods

NameDescription
toString
Returns a string representation of this construct.
postSynthesize
Called after synthesis.
preSynthesize
Called before synthesis.
synthesize
Synthesizes files to the project output directory.

toString
public toString(): string

Returns a string representation of this construct.

postSynthesize
public postSynthesize(): void

Called after synthesis.

Order is not guaranteed.

preSynthesize
public preSynthesize(): void

Called before synthesis.

synthesize
public synthesize(): void

Synthesizes files to the project output directory.

Static Functions

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

Explanation: in JavaScript, multiple copies of the constructs library on disk are seen as independent, completely different libraries. As a consequence, the class Construct in each copy of the constructs library is seen as a different class, and an instance of one class will not test as instanceof the other class. npm install will not create installations like this, but users may manually symlink construct libraries together or use a monorepo tool: in those cases, multiple copies of the constructs library can be accidentally installed, and instanceof will behave unpredictably. It is safest to avoid using instanceof, and using this type-testing method instead.

xRequired
  • Type: any

Any object.


isComponent
import { github } from 'projen'

github.Stale.isComponent(x: any)

Test whether the given construct is a component.

xRequired
  • Type: any

Properties

NameTypeDescription
node
constructs.NodeThe tree node.
project
projen.ProjectNo description.

nodeRequired
public readonly node: Node;
  • Type: constructs.Node

The tree node.


projectRequired
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)
NameTypeDescription
github
GitHub
No description.
options
TaskWorkflowOptions
No description.

githubRequired

optionsRequired

Methods

NameDescription
toString
Returns a string representation of this construct.
postSynthesize
Called after synthesis.
preSynthesize
Called before synthesis.
synthesize
Synthesizes files to the project output directory.
addJob
Adds a single job to the workflow.
addJobs
Add jobs to the workflow.
getJob
Get a single job from the workflow.
on
Add events to triggers the workflow.
removeJob
Removes a single job to the workflow.
updateJob
Updates a single job to the workflow.
updateJobs
Updates jobs for this worklow Does a complete replace, it does not try to merge the jobs.

toString
public toString(): string

Returns a string representation of this construct.

postSynthesize
public postSynthesize(): void

Called after synthesis.

Order is not guaranteed.

preSynthesize
public preSynthesize(): void

Called before synthesis.

synthesize
public synthesize(): void

Synthesizes files to the project output directory.

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

Adds a single job to the workflow.

idRequired
  • Type: string

The job name (unique within the workflow).


jobRequired

The job specification.


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

Add jobs to the workflow.

jobsRequired

Jobs to add.


getJob
public getJob(id: string): JobCallingReusableWorkflow | Job

Get a single job from the workflow.

idRequired
  • Type: string

The job name (unique within the workflow).


on
public on(events: Triggers): void

Add events to triggers the workflow.

eventsRequired

The event(s) to trigger the workflow.


removeJob
public removeJob(id: string): void

Removes a single job to the workflow.

idRequired
  • Type: string

The job name (unique within the workflow).


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

Updates a single job to the workflow.

idRequired
  • Type: string

The job name (unique within the workflow).


jobRequired

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

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

jobsRequired

Jobs to update.


Static Functions

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

Explanation: in JavaScript, multiple copies of the constructs library on disk are seen as independent, completely different libraries. As a consequence, the class Construct in each copy of the constructs library is seen as a different class, and an instance of one class will not test as instanceof the other class. npm install will not create installations like this, but users may manually symlink construct libraries together or use a monorepo tool: in those cases, multiple copies of the constructs library can be accidentally installed, and instanceof will behave unpredictably. It is safest to avoid using instanceof, and using this type-testing method instead.

xRequired
  • Type: any

Any object.


isComponent
import { github } from 'projen'

github.TaskWorkflow.isComponent(x: any)

Test whether the given construct is a component.

xRequired
  • Type: any

Properties

NameTypeDescription
node
constructs.NodeThe tree node.
project
projen.ProjectNo description.
name
stringThe name of the workflow.
projenCredentials
GithubCredentials
GitHub API authentication method used by projen workflows.
concurrency
stringConcurrency ensures that only a single job or workflow using the same concurrency group will run at a time.
file
projen.YamlFileThe workflow YAML file.
runName
stringThe name for workflow runs generated from the workflow.
jobId
stringNo description.
artifactsDirectory
stringNo description.

nodeRequired
public readonly node: Node;
  • Type: constructs.Node

The tree node.


projectRequired
public readonly project: Project;
  • Type: projen.Project

nameRequired
public readonly name: string;
  • Type: string

The name of the workflow.


projenCredentialsRequired
public readonly projenCredentials: GithubCredentials;

GitHub API authentication method used by projen workflows.


concurrencyOptional
public readonly concurrency: string;
  • Type: string
  • Default: disabled

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


fileOptional
public readonly file: YamlFile;
  • Type: projen.YamlFile

The workflow YAML file.

May not exist if workflowsEnabled is false on GitHub.


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


jobIdRequired
public readonly jobId: string;
  • Type: string

artifactsDirectoryOptional
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)
NameTypeDescription
scope
constructs.IConstructshould be part of the project the Task belongs to.
task
projen.Taskthe main task that is run as part of this job.
options
TaskWorkflowJobOptions
options to configure the TaskWorkflowJob.

scopeRequired
  • Type: constructs.IConstruct

should be part of the project the Task belongs to.


taskRequired
  • Type: projen.Task

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


optionsRequired

options to configure the TaskWorkflowJob.


Methods

NameDescription
toString
Returns a string representation of this construct.
postSynthesize
Called after synthesis.
preSynthesize
Called before synthesis.
synthesize
Synthesizes files to the project output directory.

toString
public toString(): string

Returns a string representation of this construct.

postSynthesize
public postSynthesize(): void

Called after synthesis.

Order is not guaranteed.

preSynthesize
public preSynthesize(): void

Called before synthesis.

synthesize
public synthesize(): void

Synthesizes files to the project output directory.

Static Functions

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

Explanation: in JavaScript, multiple copies of the constructs library on disk are seen as independent, completely different libraries. As a consequence, the class Construct in each copy of the constructs library is seen as a different class, and an instance of one class will not test as instanceof the other class. npm install will not create installations like this, but users may manually symlink construct libraries together or use a monorepo tool: in those cases, multiple copies of the constructs library can be accidentally installed, and instanceof will behave unpredictably. It is safest to avoid using instanceof, and using this type-testing method instead.

xRequired
  • Type: any

Any object.


isComponent
import { github } from 'projen'

github.TaskWorkflowJob.isComponent(x: any)

Test whether the given construct is a component.

xRequired
  • Type: any

Properties

NameTypeDescription
node
constructs.NodeThe tree node.
project
projen.ProjectNo description.
permissions
JobPermissions
No description.
steps
JobStep[]
No description.
concurrency
anyNo description.
container
ContainerOptions
No description.
continueOnError
booleanNo description.
defaults
JobDefaults
No description.
env
{[ key: string ]: string}No description.
environment
anyNo description.
if
stringNo description.
name
stringNo description.
needs
string[]No description.
outputs
{[ key: string ]: JobStepOutput}
No description.
runsOn
string[]No description.
runsOnGroup
projen.GroupRunnerOptionsNo description.
services
{[ key: string ]: ContainerOptions}
No description.
strategy
JobStrategy
No description.
timeoutMinutes
numberNo description.
tools
Tools
No description.

nodeRequired
public readonly node: Node;
  • Type: constructs.Node

The tree node.


projectRequired
public readonly project: Project;
  • Type: projen.Project

permissionsRequired
public readonly permissions: JobPermissions;

stepsRequired
public readonly steps: JobStep[];

concurrencyOptional
public readonly concurrency: any;
  • Type: any

containerOptional
public readonly container: ContainerOptions;

continueOnErrorOptional
public readonly continueOnError: boolean;
  • Type: boolean

defaultsOptional
public readonly defaults: JobDefaults;

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

environmentOptional
public readonly environment: any;
  • Type: any

ifOptional
public readonly if: string;
  • Type: string

nameOptional
public readonly name: string;
  • Type: string

needsOptional
public readonly needs: string[];
  • Type: string[]

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

runsOnOptional
public readonly runsOn: string[];
  • Type: string[]

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

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

strategyOptional
public readonly strategy: JobStrategy;

timeoutMinutesOptional
public readonly timeoutMinutes: number;
  • Type: number

toolsOptional
public readonly tools: Tools;

Structs

AutoApproveOptions

Options for 'AutoApprove'.

Initializer

import { github } from 'projen'

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

Properties

NameTypeDescription
allowedUsernames
string[]Only pull requests authored by these Github usernames will be auto-approved.
label
stringOnly pull requests with this label will be auto-approved.
runsOn
string[]Github Runner selection labels.
runsOnGroup
projen.GroupRunnerOptionsGithub Runner Group selection options.
secret
stringA GitHub secret name which contains a GitHub Access Token with write permissions for the pull_request scope.

allowedUsernamesOptional
public readonly allowedUsernames: string[];
  • Type: string[]
  • Default: ['github-bot']

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


labelOptional
public readonly label: string;
  • Type: string
  • Default: 'auto-approve'

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


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

Github Runner selection labels.


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

Github Runner Group selection options.


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

AutoMergeOptions

Initializer

import { github } from 'projen'

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

Properties

NameTypeDescription
approvedReviews
numberNumber of approved code reviews.
blockingLabels
string[]List of labels that will prevent auto-merging.
queueName
stringName of the mergify queue.
ruleName
stringName of the mergify rule.

approvedReviewsOptional
public readonly approvedReviews: number;
  • Type: number
  • Default: 1

Number of approved code reviews.


blockingLabelsOptional
public readonly blockingLabels: string[];
  • Type: string[]
  • Default: ['do-not-merge']

List of labels that will prevent auto-merging.


queueNameOptional
public readonly queueName: string;
  • Type: string
  • Default: 'default'

Name of the mergify queue.


ruleNameOptional
public readonly ruleName: string;
  • Type: string
  • Default: 'Automatic merge on approval and successful build'

Name of the mergify rule.


CheckoutOptions

Initializer

import { github } from 'projen'

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

Properties

NameTypeDescription
env
{[ key: string ]: string}Sets environment variables for steps to use in the runner environment.
id
stringA unique identifier for the step.
if
stringYou can use the if conditional to prevent a job from running unless a condition is met.
name
stringA name for your step to display on GitHub.
workingDirectory
stringSpecifies a working directory for a step.
continueOnError
booleanPrevents a job from failing when a step fails.
timeoutMinutes
numberThe maximum number of minutes to run the step before killing the process.
with
CheckoutWith
Options for checkout.

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


idOptional
public readonly id: string;
  • Type: string

A unique identifier for the step.

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


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


nameOptional
public readonly name: string;
  • Type: string

A name for your step to display on GitHub.


workingDirectoryOptional
public readonly workingDirectory: string;
  • Type: string

Specifies a working directory for a step.

Overrides a job's working directory.


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


timeoutMinutesOptional
public readonly timeoutMinutes: number;
  • Type: number

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


withOptional
public readonly with: CheckoutWith;

Options for checkout.


CheckoutWith

Options for checkout.

Initializer

import { github } from 'projen'

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

Properties

NameTypeDescription
fetchDepth
numberNumber of commits to fetch.
lfs
booleanWhether LFS is enabled for the GitHub repository.
ref
stringBranch or tag name.
repository
stringThe repository (owner/repo) to use.
token
stringA GitHub token to use when checking out the repository.

fetchDepthOptional
public readonly fetchDepth: number;
  • Type: number
  • Default: 1

Number of commits to fetch.

0 indicates all history for all branches and tags.


lfsOptional
public readonly lfs: boolean;
  • Type: boolean
  • Default: false

Whether LFS is enabled for the GitHub repository.


refOptional
public readonly ref: string;
  • Type: string
  • Default: the default branch is implicitly used

Branch or tag name.


repositoryOptional
public readonly repository: string;
  • Type: string
  • Default: the default repository is implicitly used

The repository (owner/repo) to use.


tokenOptional
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

NameTypeDescription
fetchDepth
numberNumber of commits to fetch.
lfs
booleanWhether LFS is enabled for the GitHub repository.
ref
stringBranch or tag name.
repository
stringThe repository (owner/repo) to use.
token
stringA GitHub token to use when checking out the repository.
patchFile
stringThe name of the artifact the patch is stored as.

fetchDepthOptional
public readonly fetchDepth: number;
  • Type: number
  • Default: 1

Number of commits to fetch.

0 indicates all history for all branches and tags.


lfsOptional
public readonly lfs: boolean;
  • Type: boolean
  • Default: false

Whether LFS is enabled for the GitHub repository.


refOptional
public readonly ref: string;
  • Type: string
  • Default: the default branch is implicitly used

Branch or tag name.


repositoryOptional
public readonly repository: string;
  • Type: string
  • Default: the default repository is implicitly used

The repository (owner/repo) to use.


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


patchFileOptional
public readonly patchFile: string;
  • Type: string
  • Default: ".repo.patch"

The name of the artifact the patch is stored as.


ContributorStatementOptions

Options for requiring a contributor statement on Pull Requests.

Initializer

import { github } from 'projen'

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

Properties

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

exemptLabelsOptional
public readonly exemptLabels: string[];
  • Type: string[]
  • Default: no labels are excluded

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


exemptUsersOptional
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

NameTypeDescription
pullRequestDescription
stringDescription added to the pull request.
pullRequestTitle
stringThe full title used to create the pull request.
workflowName
stringThe name of the workflow that will create the PR.
assignees
string[]Assignees to add on the PR.
baseBranch
stringSets the pull request base branch.
branchName
stringThe pull request branch name.
credentials
GithubCredentials
The job credentials used to create the pull request.
gitIdentity
GitIdentity
The git identity used to create the commit.
labels
string[]Labels to apply on the PR.
signoff
booleanAdd Signed-off-by line by the committer at the end of the commit log message.
stepId
stringThe step ID which produces the output which indicates if a patch was created.
stepName
stringThe name of the step displayed on GitHub.

pullRequestDescriptionRequired
public readonly pullRequestDescription: string;
  • Type: string

Description added to the pull request.

Providence information are automatically added.


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


workflowNameRequired
public readonly workflowName: string;
  • Type: string

The name of the workflow that will create the PR.


assigneesOptional
public readonly assignees: string[];
  • Type: string[]
  • Default: no assignees

Assignees to add on the PR.


baseBranchOptional
public readonly baseBranch: string;
  • Type: string
  • Default: The branch checked out in the workflow.

Sets the pull request base branch.


branchNameOptional
public readonly branchName: string;
  • Type: string
  • Default: github-actions/${options.workflowName}

The pull request branch name.


credentialsOptional
public readonly credentials: GithubCredentials;

The job credentials used to create the pull request.

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


gitIdentityOptional
public readonly gitIdentity: GitIdentity;
  • Type: GitIdentity
  • Default: the default github-actions user

The git identity used to create the commit.


labelsOptional
public readonly labels: string[];
  • Type: string[]
  • Default: no labels.

Labels to apply on the PR.


signoffOptional
public readonly signoff: boolean;
  • Type: boolean
  • Default: true

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


stepIdOptional
public readonly stepId: string;
  • Type: string
  • Default: "create_pr"

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


stepNameOptional
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

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

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


DependabotGroup

Defines a single group for dependency updates.

Initializer

import { github } from 'projen'

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

Properties

NameTypeDescription
patterns
string[]Define a list of strings (with or without wildcards) that will match package names to form this dependency group.
excludePatterns
string[]Optionally you can use this to exclude certain dependencies from the group.

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


excludePatternsOptional
public readonly excludePatterns: string[];
  • Type: string[]

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


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

NameTypeDescription
dependencyName
stringUse 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.

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


versionsOptional
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

NameTypeDescription
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.
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
booleanIgnores updates to projen.
labels
string[]List of labels to apply to the created PR's.
openPullRequestsLimit
numberSets 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.
versioningStrategy
VersioningStrategy
The strategy to use when edits manifest and lock files.

allowOptional
public readonly allow: DependabotAllow[];

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.


assigneesOptional
public readonly assignees: string[];
  • Type: string[]
  • Default: []

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


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

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.


ignoreOptional
public readonly ignore: DependabotIgnore[];

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

The ignore option supports the following options.


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


labelsOptional
public readonly labels: string[];
  • Type: string[]

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


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


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

Map of package registries to use.


reviewersOptional
public readonly reviewers: string[];
  • Type: string[]
  • Default: []

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


scheduleIntervalOptional
public readonly scheduleInterval: DependabotScheduleInterval;

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


versioningStrategyOptional
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

NameTypeDescription
type
DependabotRegistryType
Registry type e.g. 'npm-registry' or 'docker-registry'.
url
stringUrl for the registry e.g. 'https://npm.pkg.github.com' or 'registry.hub.docker.com'.
key
stringA reference to a Dependabot secret containing an access key for this registry.
organization
stringUsed with the hex-organization registry type.
password
stringA reference to a Dependabot secret containing the password for the specified user.
replacesBase
booleanFor 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
stringSecret token for dependabot access e.g. '${{ secrets.DEPENDABOT_PACKAGE_TOKEN }}'.
username
stringThe username that Dependabot uses to access the registry.

typeRequired
public readonly type: DependabotRegistryType;

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


urlRequired
public readonly url: string;
  • Type: string

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


keyOptional
public readonly key: string;
  • Type: string
  • Default: undefined

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


organizationOptional
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


passwordOptional
public readonly password: string;
  • Type: string
  • Default: undefined

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


replacesBaseOptional
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).


tokenOptional
public readonly token: string;
  • Type: string
  • Default: undefined

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


usernameOptional
public readonly username: string;
  • Type: string
  • Default: do not authenticate

The username that Dependabot uses to access the registry.


DownloadArtifactOptions

Initializer

import { github } from 'projen'

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

Properties

NameTypeDescription
env
{[ key: string ]: string}Sets environment variables for steps to use in the runner environment.
id
stringA unique identifier for the step.
if
stringYou can use the if conditional to prevent a job from running unless a condition is met.
name
stringA name for your step to display on GitHub.
workingDirectory
stringSpecifies a working directory for a step.
continueOnError
booleanPrevents a job from failing when a step fails.
timeoutMinutes
numberThe maximum number of minutes to run the step before killing the process.
with
DownloadArtifactWith
Options for download-artifact.

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


idOptional
public readonly id: string;
  • Type: string

A unique identifier for the step.

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


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


nameOptional
public readonly name: string;
  • Type: string

A name for your step to display on GitHub.


workingDirectoryOptional
public readonly workingDirectory: string;
  • Type: string

Specifies a working directory for a step.

Overrides a job's working directory.


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


timeoutMinutesOptional
public readonly timeoutMinutes: number;
  • Type: number

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


withRequired
public readonly with: DownloadArtifactWith;

Options for download-artifact.


DownloadArtifactWith

Initializer

import { github } from 'projen'

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

Properties

NameTypeDescription
mergeMultiple
booleanWhen 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
stringName of the artifact to download.
path
stringA file, directory or wildcard pattern that describes what to download.
pattern
stringA glob pattern to the artifacts that should be downloaded This is ignored if name is specified.
repository
stringThe 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
stringThe 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
stringThe GitHub token used to authenticate with the GitHub API to download artifacts from a different repository or from a different workflow run.

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


nameOptional
public readonly name: string;
  • Type: string
  • Default: If unspecified, all artifacts for the run are downloaded

Name of the artifact to download.


pathOptional
public readonly path: string;
  • Type: string
  • Default: $GITHUB_WORKSPACE

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

Supports basic tilde expansion.


patternOptional
public readonly pattern: string;
  • Type: string

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


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


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


tokenOptional
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

NameTypeDescription
appIdSecret
stringNo description.
permissions
AppPermissions
The permissions granted to the token.
privateKeySecret
stringNo description.

appIdSecretOptional
public readonly appIdSecret: string;
  • Type: string

permissionsOptional
public readonly permissions: AppPermissions;

The permissions granted to the token.


privateKeySecretOptional
public readonly privateKeySecret: string;
  • Type: string

GithubCredentialsPersonalAccessTokenOptions

Options for GithubCredentials.fromPersonalAccessToken.

Initializer

import { github } from 'projen'

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

Properties

NameTypeDescription
secret
stringNo description.

secretOptional
public readonly secret: string;
  • Type: string

GitHubOptions

Initializer

import { github } from 'projen'

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

Properties

NameTypeDescription
downloadLfs
booleanDownload files in LFS in workflows.
mergify
booleanWhether 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.
projenTokenSecret
stringThe name of a secret which includes a GitHub Personal Access Token to be used by projen workflows.
pullRequestLint
booleanAdd 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.
workflows
booleanEnables GitHub workflows.

downloadLfsOptional
public readonly downloadLfs: boolean;
  • Type: boolean
  • Default: true if the associated project has lfsPatterns, false otherwise

Download files in LFS in workflows.


mergifyOptional
public readonly mergify: boolean;
  • Type: boolean
  • Default: true

Whether mergify should be enabled on this repository or not.


mergifyOptionsOptional
public readonly mergifyOptions: MergifyOptions;

Options for Mergify.


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


projenTokenSecretOptional
  • Deprecated: - use projenCredentials
public readonly projenTokenSecret: string;
  • Type: string
  • Default: "PROJEN_GITHUB_TOKEN"

The name of a secret which includes a GitHub Personal Access Token to be used by projen workflows.

This token needs to have the repo, workflows and packages scope.


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


pullRequestLintOptionsOptional
public readonly pullRequestLintOptions: PullRequestLintOptions;

Options for configuring a pull request linter.


workflowsOptional
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

NameTypeDescription
name
stringThis is the name of your project.
commitGenerated
booleanWhether to commit the managed files by default.
gitIgnoreOptions
projen.IgnoreFileOptionsConfiguration options for .gitignore file.
gitOptions
projen.GitOptionsConfiguration options for git.
logging
projen.LoggerOptionsConfigure logging options such as verbosity.
outdir
stringThe root directory of the project.
parent
projen.ProjectThe parent project, if this project is part of a bigger project.
projenCommand
stringThe shell command to use in order to run the projen CLI.
projenrcJson
booleanGenerate (once) .projenrc.json (in JSON). Set to false in order to disable .projenrc.json generation.
projenrcJsonOptions
projen.ProjenrcJsonOptionsOptions for .projenrc.json.
renovatebot
booleanUse renovatebot to handle dependency upgrades.
renovatebotOptions
projen.RenovatebotOptionsOptions for renovatebot.
autoApproveOptions
AutoApproveOptions
Enable and configure the 'auto approve' workflow.
autoMerge
booleanEnable automatic merging on GitHub.
autoMergeOptions
AutoMergeOptions
Configure options for automatic merging on GitHub.
clobber
booleanAdd a clobber task which resets the repo to origin.
devContainer
booleanAdd a VSCode development environment (used for GitHub Codespaces).
github
booleanEnable GitHub integration.
githubOptions
GitHubOptions
Options for GitHub integration.
gitpod
booleanAdd a Gitpod development environment.
mergify
booleanWhether mergify should be enabled on this repository or not.
mergifyOptions
MergifyOptions
Options for mergify.
projectType
projen.ProjectTypeWhich type of project this is (library/app).
projenCredentials
GithubCredentials
Choose a method of providing GitHub API access for projen workflows.
projenTokenSecret
stringThe name of a secret which includes a GitHub Personal Access Token to be used by projen workflows.
readme
projen.SampleReadmePropsThe README setup.
stale
booleanAuto-close of stale issues and pull request.
staleOptions
StaleOptions
Auto-close stale issues and pull requests.
vscode
booleanEnable VSCode integration.

nameRequired
public readonly name: string;
  • Type: string
  • Default: $BASEDIR

This is the name of your project.


commitGeneratedOptional
public readonly commitGenerated: boolean;
  • Type: boolean
  • Default: true

Whether to commit the managed files by default.


gitIgnoreOptionsOptional
public readonly gitIgnoreOptions: IgnoreFileOptions;
  • Type: projen.IgnoreFileOptions

Configuration options for .gitignore file.


gitOptionsOptional
public readonly gitOptions: GitOptions;
  • Type: projen.GitOptions

Configuration options for git.


loggingOptional
public readonly logging: LoggerOptions;
  • Type: projen.LoggerOptions
  • Default: {}

Configure logging options such as verbosity.


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


parentOptional
public readonly parent: Project;
  • Type: projen.Project

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


projenCommandOptional
public readonly projenCommand: string;
  • Type: string
  • Default: "npx projen"

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

Can be used to customize in special environments.


projenrcJsonOptional
public readonly projenrcJson: boolean;
  • Type: boolean
  • Default: false

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


projenrcJsonOptionsOptional
public readonly projenrcJsonOptions: ProjenrcJsonOptions;
  • Type: projen.ProjenrcJsonOptions
  • Default: default options

Options for .projenrc.json.


renovatebotOptional
public readonly renovatebot: boolean;
  • Type: boolean
  • Default: false

Use renovatebot to handle dependency upgrades.


renovatebotOptionsOptional
public readonly renovatebotOptions: RenovatebotOptions;
  • Type: projen.RenovatebotOptions
  • Default: default options

Options for renovatebot.


autoApproveOptionsOptional
public readonly autoApproveOptions: AutoApproveOptions;

Enable and configure the 'auto approve' workflow.


autoMergeOptional
public readonly autoMerge: boolean;
  • Type: boolean
  • Default: true

Enable automatic merging on GitHub.

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


autoMergeOptionsOptional
public readonly autoMergeOptions: AutoMergeOptions;

Configure options for automatic merging on GitHub.

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


clobberOptional
public readonly clobber: boolean;
  • Type: boolean
  • Default: true, but false for subprojects

Add a clobber task which resets the repo to origin.


devContainerOptional
public readonly devContainer: boolean;
  • Type: boolean
  • Default: false

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


githubOptional
public readonly github: boolean;
  • Type: boolean
  • Default: true

Enable GitHub integration.

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


githubOptionsOptional
public readonly githubOptions: GitHubOptions;

Options for GitHub integration.


gitpodOptional
public readonly gitpod: boolean;
  • Type: boolean
  • Default: false

Add a Gitpod development environment.


mergifyOptional
  • Deprecated: use githubOptions.mergify instead
public readonly mergify: boolean;
  • Type: boolean
  • Default: true

Whether mergify should be enabled on this repository or not.


mergifyOptionsOptional
  • Deprecated: use githubOptions.mergifyOptions instead
public readonly mergifyOptions: MergifyOptions;

Options for mergify.


projectTypeOptional
  • Deprecated: no longer supported at the base project level
public readonly projectType: ProjectType;
  • Type: projen.ProjectType
  • Default: ProjectType.UNKNOWN

Which type of project this is (library/app).


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


projenTokenSecretOptional
  • Deprecated: use projenCredentials
public readonly projenTokenSecret: string;
  • Type: string
  • Default: "PROJEN_GITHUB_TOKEN"

The name of a secret which includes a GitHub Personal Access Token to be used by projen workflows.

This token needs to have the repo, workflows and packages scope.


readmeOptional
public readonly readme: SampleReadmeProps;
  • Type: projen.SampleReadmeProps
  • Default: { filename: 'README.md', contents: '# replace this' }

The README setup.


Example

"{ filename: 'readme.md', contents: '# title' }"
staleOptional
public readonly stale: boolean;
  • Type: boolean
  • Default: false

Auto-close of stale issues and pull request.

See staleOptions for options.


staleOptionsOptional
public readonly staleOptions: StaleOptions;

Auto-close stale issues and pull requests.

To disable set stale to false.


vscodeOptional
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

NameTypeDescription
concurrency
stringConcurrency ensures that only a single job or workflow using the same concurrency group will run at a time.
force
booleanForce the creation of the workflow even if workflows is disabled in GitHub.

concurrencyOptional
public readonly concurrency: string;
  • Type: string
  • Default: disabled

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


forceOptional
public readonly force: boolean;
  • Type: boolean
  • Default: false

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


GitIdentity

Represents the git identity.

Initializer

import { github } from 'projen'

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

Properties

NameTypeDescription
email
stringThe email address of the git user.
name
stringThe name of the user.

emailRequired
public readonly email: string;
  • Type: string

The email address of the git user.


nameRequired
public readonly name: string;
  • Type: string

The name of the user.


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

NameTypeDescription
and
string | MergifyConditionalOperator[]
No description.
or
string | MergifyConditionalOperator[]
No description.

andOptional