github
Submodule
Constructs
AutoApprove
Auto approve pull requests that meet a criteria.
Initializers
import { github } from 'projen'
new github.AutoApprove(github: GitHub, options?: AutoApproveOptions)
Name | Type | Description |
---|---|---|
|
| No description. |
|
| No description. |
github
Required
- Type: GitHub
options
Optional
- Type: AutoApproveOptions
Methods
Name | Description |
---|---|
| Returns a string representation of this construct. |
| Called after synthesis. |
| Called before synthesis. |
| 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
Name | Description |
---|---|
| Checks if x is a construct. |
| Test whether the given construct is a component. |
isConstruct
import { github } from 'projen'
github.AutoApprove.isConstruct(x: any)
Checks if x
is a construct.
Use this method instead of instanceof
to properly detect Construct
instances, even when the construct library is symlinked.
Explanation: in JavaScript, multiple copies of the constructs
library on
disk are seen as independent, completely different libraries. As a
consequence, the class Construct
in each copy of the constructs
library
is seen as a different class, and an instance of one class will not test as
instanceof
the other class. npm install
will not create installations
like this, but users may manually symlink construct libraries together or
use a monorepo tool: in those cases, multiple copies of the constructs
library can be accidentally installed, and instanceof
will behave
unpredictably. It is safest to avoid using instanceof
, and using
this type-testing method instead.
x
Required
- Type: any
Any object.
isComponent
import { github } from 'projen'
github.AutoApprove.isComponent(x: any)
Test whether the given construct is a component.
x
Required
- Type: any
Properties
Name | Type | Description |
---|---|---|
| constructs.Node | The tree node. |
| projen.Project | No description. |
| string | No description. |
node
Required
public readonly node: Node;
- Type: constructs.Node
The tree node.
project
Required
public readonly project: Project;
- Type: projen.Project
label
Required
public readonly label: string;
- Type: string
AutoMerge
Automatically merge Pull Requests using Mergify.
[!NOTE] GitHub now natively provides the same features, so you don't need Mergify anymore. See
GitHubOptions.mergeQueue
andMergeQueueOptions.autoQueue
.
If buildJob
is specified, the specified GitHub workflow job ID is required
to succeed in order for the PR to be merged.
approvedReviews
specified the number of code review approvals required for
the PR to be merged.
Initializers
import { github } from 'projen'
new github.AutoMerge(github: GitHub, options?: AutoMergeOptions)
Name | Type | Description |
---|---|---|
|
| No description. |
|
| No description. |
github
Required
- Type: GitHub
options
Optional
- Type: AutoMergeOptions
Methods
Name | Description |
---|---|
| Returns a string representation of this construct. |
| Called after synthesis. |
| Called before synthesis. |
| Synthesizes files to the project output directory. |
| Adds conditions to the auto merge rule. |
| 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.
conditions
Required
- Type: ...string[]
The conditions to add (mergify syntax).
addConditionsLater
public addConditionsLater(later: IAddConditionsLater): void
Adds conditions that will be rendered only during synthesis.
later
Required
- Type: IAddConditionsLater
The later.
Static Functions
Name | Description |
---|---|
| Checks if x is a construct. |
| 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.
x
Required
- Type: any
Any object.
isComponent
import { github } from 'projen'
github.AutoMerge.isComponent(x: any)
Test whether the given construct is a component.
x
Required
- Type: any
Properties
Name | Type | Description |
---|---|---|
| constructs.Node | The tree node. |
| projen.Project | No description. |
node
Required
public readonly node: Node;
- Type: constructs.Node
The tree node.
project
Required
public readonly project: Project;
- Type: projen.Project
AutoQueue
Automatically add pull requests to the merge queue PRs will be merged once they pass required checks.
Initializers
import { github } from 'projen'
new github.AutoQueue(scope: IConstruct, options?: AutoQueueOptions)
Name | Type | Description |
---|---|---|
| constructs.IConstruct | No description. |
|
| No description. |
scope
Required
- Type: constructs.IConstruct
options
Optional
- Type: AutoQueueOptions
Methods
Name | Description |
---|---|
| Returns a string representation of this construct. |
| Called after synthesis. |
| Called before synthesis. |
| 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
Name | Description |
---|---|
| Checks if x is a construct. |
| Test whether the given construct is a component. |
isConstruct
import { github } from 'projen'
github.AutoQueue.isConstruct(x: any)
Checks if x
is a construct.
Use this method instead of instanceof
to properly detect Construct
instances, even when the construct library is symlinked.
Explanation: in JavaScript, multiple copies of the constructs
library on
disk are seen as independent, completely different libraries. As a
consequence, the class Construct
in each copy of the constructs
library
is seen as a different class, and an instance of one class will not test as
instanceof
the other class. npm install
will not create installations
like this, but users may manually symlink construct libraries together or
use a monorepo tool: in those cases, multiple copies of the constructs
library can be accidentally installed, and instanceof
will behave
unpredictably. It is safest to avoid using instanceof
, and using
this type-testing method instead.
x
Required
- Type: any
Any object.
isComponent
import { github } from 'projen'
github.AutoQueue.isComponent(x: any)
Test whether the given construct is a component.
x
Required
- Type: any
Properties
Name | Type | Description |
---|---|---|
| constructs.Node | The tree node. |
| projen.Project | No description. |
node
Required
public readonly node: Node;
- Type: constructs.Node
The tree node.
project
Required
public readonly project: Project;
- Type: projen.Project
Dependabot
Defines dependabot configuration for node projects.
Since module versions are managed in projen, the versioning strategy will be configured to "lockfile-only" which means that only updates that can be done on the lockfile itself will be proposed.
Initializers
import { github } from 'projen'
new github.Dependabot(github: GitHub, options?: DependabotOptions)
Name | Type | Description |
---|---|---|
|
| No description. |
|
| No description. |
github
Required
- Type: GitHub
options
Optional
- Type: DependabotOptions
Methods
Name | Description |
---|---|
| Returns a string representation of this construct. |
| Called after synthesis. |
| Called before synthesis. |
| Synthesizes files to the project output directory. |
| Allows a dependency from automatic updates. |
| 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.
dependencyName
Required
- Type: string
Use to allow updates for dependencies with matching names, optionally using *
to match zero or more characters.
addIgnore
public addIgnore(dependencyName: string, versions: ...string[]): void
Ignores a dependency from automatic updates.
dependencyName
Required
- Type: string
Use to ignore updates for dependencies with matching names, optionally using *
to match zero or more characters.
versions
Required
- Type: ...string[]
Use to ignore specific versions or ranges of versions.
If
you want to define a range, use the standard pattern for the package
manager (for example: ^1.0.0
for npm, or ~> 2.0
for Bundler).
Static Functions
Name | Description |
---|---|
| Checks if x is a construct. |
| 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.
x
Required
- Type: any
Any object.
isComponent
import { github } from 'projen'
github.Dependabot.isComponent(x: any)
Test whether the given construct is a component.
x
Required
- Type: any
Properties
Name | Type | Description |
---|---|---|
| constructs.Node | The tree node. |
| projen.Project | No description. |
| any | The raw dependabot configuration. |
| boolean | Whether or not projen is also upgraded in this config,. |
node
Required
public readonly node: Node;
- Type: constructs.Node
The tree node.
project
Required
public readonly project: Project;
- Type: projen.Project
config
Required
public readonly config: any;
- Type: any
The raw dependabot configuration.
ignoresProjen
Required
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)
Name | Type | Description |
---|---|---|
| projen.Project | No description. |
|
| No description. |
project
Required
- Type: projen.Project
options
Optional
- Type: GitHubOptions
Methods
Name | Description |
---|---|
| Returns a string representation of this construct. |
| Called after synthesis. |
| Called before synthesis. |
| Synthesizes files to the project output directory. |
| No description. |
| No description. |
| Adds a workflow to the project. |
| 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
options
Optional
- Type: DependabotOptions
addPullRequestTemplate
public addPullRequestTemplate(content: ...string[]): PullRequestTemplate
content
Required
- Type: ...string[]
addWorkflow
public addWorkflow(name: string): GithubWorkflow
Adds a workflow to the project.
name
Required
- Type: string
Name of the workflow.
tryFindWorkflow
public tryFindWorkflow(name: string): GithubWorkflow
Finds a GitHub workflow by name.
Returns undefined
if the workflow cannot be found.
name
Required
- Type: string
The name of the GitHub workflow.
Static Functions
Name | Description |
---|---|
| Checks if x is a construct. |
| Test whether the given construct is a component. |
| 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.
x
Required
- Type: any
Any object.
isComponent
import { github } from 'projen'
github.GitHub.isComponent(x: any)
Test whether the given construct is a component.
x
Required
- Type: any
of
import { github } from 'projen'
github.GitHub.of(project: Project)
Returns the GitHub
component of a project or undefined
if the project does not have a GitHub component.
project
Required
- Type: projen.Project
Properties
Name | Type | Description |
---|---|---|
| constructs.Node | The tree node. |
| projen.Project | No description. |
|
| The GitHub Actions provider used to manage the versions of actions used in steps. |
| boolean | Whether downloading from LFS is enabled for this GitHub project. |
|
| GitHub API authentication method used by projen workflows. |
|
| All workflows. |
| boolean | Are workflows enabled? |
|
| The MergeQueue component configured on this repository This is undefined if merge queues are not enabled for this repository. |
|
| The Mergify component configured on this repository This is undefined if Mergify is not enabled for this repository. |
node
Required
public readonly node: Node;
- Type: constructs.Node
The tree node.
project
Required
public readonly project: Project;
- Type: projen.Project
actions
Required
public readonly actions: GitHubActionsProvider;
- Type: GitHubActionsProvider
The GitHub Actions provider used to manage the versions of actions used in steps.
downloadLfs
Required
public readonly downloadLfs: boolean;
- Type: boolean
Whether downloading from LFS is enabled for this GitHub project.
projenCredentials
Required
public readonly projenCredentials: GithubCredentials;
- Type: GithubCredentials
GitHub API authentication method used by projen workflows.
workflows
Required
public readonly workflows: GithubWorkflow[];
- Type: GithubWorkflow[]
All workflows.
workflowsEnabled
Required
public readonly workflowsEnabled: boolean;
- Type: boolean
Are workflows enabled?
mergeQueue
Optional
public readonly mergeQueue: MergeQueue;
- Type: MergeQueue
The MergeQueue
component configured on this repository This is undefined
if merge queues are not enabled for this repository.
mergify
Optional
public readonly mergify: Mergify;
- Type: Mergify
The Mergify
component configured on this repository This is undefined
if Mergify is not enabled for this repository.
GitHubProject
GitHub-based project.
Initializers
import { github } from 'projen'
new github.GitHubProject(options: GitHubProjectOptions)
Name | Type | Description |
---|---|---|
|
| No description. |
options
Required
- Type: GitHubProjectOptions
Methods
Name | Description |
---|---|
| Returns a string representation of this construct. |
| Exclude the matching files from pre-synth cleanup. |
| Adds a .gitignore pattern. |
| Exclude these files from the bundled package. |
| Adds a new task to this project. |
| Prints a "tip" message during synthesis. |
| Marks the provided file(s) as being generated. |
| Called after all components are synthesized. |
| Called before all components are synthesized. |
| Removes a task from a project. |
| Returns the shell command to execute in order to run a task. |
| Synthesize all project files into outdir . |
| Finds a file at the specified relative path within this project and all its subprojects. |
| Finds a json file by name. |
| Finds an object file (like JsonFile, YamlFile, etc.) by name. |
| Finds a file at the specified relative path within this project and removes it. |
toString
toString
public toString(): string
Returns a string representation of this construct.
addExcludeFromCleanup
addExcludeFromCleanup
public addExcludeFromCleanup(globs: ...string[]): void
Exclude the matching files from pre-synth cleanup.
Can be used when, for example, some source files include the projen marker and we don't want them to be erased during synth.
globs
Required
- Type: ...string[]
The glob patterns to match.
addGitIgnore
addGitIgnore
public addGitIgnore(pattern: string): void
Adds a .gitignore pattern.
pattern
Required
- Type: string
The glob pattern to ignore.
addPackageIgnore
addPackageIgnore
public addPackageIgnore(_pattern: string): void
Exclude these files from the bundled package.
Implemented by project types based on the
packaging mechanism. For example, NodeProject
delegates this to .npmignore
.
_pattern
Required
- Type: string
The glob pattern to exclude.
addTask
addTask
public addTask(name: string, props?: TaskOptions): Task
Adds a new task to this project.
This will fail if the project already has a task with this name.
name
Required
- Type: string
The task name to add.
props
Optional
- Type: projen.TaskOptions
Task properties.
addTip
addTip
public addTip(message: string): void
Prints a "tip" message during synthesis.
message
Required
- Type: string
The message.
annotateGenerated
annotateGenerated
public annotateGenerated(glob: string): void
Marks the provided file(s) as being generated.
This is achieved using the github-linguist attributes. Generated files do not count against the repository statistics and language breakdown.
https://github.com/github/linguist/blob/master/docs/overrides.md
glob
Required
- Type: string
the glob pattern to match (could be a file path).
postSynthesize
postSynthesize
public postSynthesize(): void
Called after all components are synthesized.
Order is not guaranteed.
preSynthesize
preSynthesize
public preSynthesize(): void
Called before all components are synthesized.
removeTask
removeTask
public removeTask(name: string): Task
Removes a task from a project.
name
Required
- Type: string
The name of the task to remove.
runTaskCommand
runTaskCommand
public runTaskCommand(task: Task): string
Returns the shell command to execute in order to run a task.
By default, this is npx projen@<version> <task>
task
Required
- Type: projen.Task
The task for which the command is required.
synth
synth
public synth(): void
Synthesize all project files into outdir
.
- Call "this.preSynthesize()"
- Delete all generated files
- Synthesize all subprojects
- Synthesize all components of this project
- Call "postSynthesize()" for all components of this project
- Call "this.postSynthesize()"
tryFindFile
tryFindFile
public tryFindFile(filePath: string): FileBase
Finds a file at the specified relative path within this project and all its subprojects.
filePath
Required
- Type: string
The file path.
If this path is relative, it will be resolved from the root of this project.
tryFindJsonFile
tryFindJsonFile
public tryFindJsonFile(filePath: string): JsonFile
Finds a json file by name.
filePath
Required
- Type: string
The file path.
tryFindObjectFile
tryFindObjectFile
public tryFindObjectFile(filePath: string): ObjectFile
Finds an object file (like JsonFile, YamlFile, etc.) by name.
filePath
Required
- Type: string
The file path.
tryRemoveFile
tryRemoveFile
public tryRemoveFile(filePath: string): FileBase
Finds a file at the specified relative path within this project and removes it.
filePath
Required
- Type: string
The file path.
If this path is relative, it will be resolved from the root of this project.
Static Functions
Name | Description |
---|---|
| Checks if x is a construct. |
| Test whether the given construct is a project. |
| Find the closest ancestor project for given construct. |
isConstruct
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.
x
Required
- Type: any
Any object.
isProject
isProject
import { github } from 'projen'
github.GitHubProject.isProject(x: any)
Test whether the given construct is a project.
x
Required
- Type: any
of
of
import { github } from 'projen'
github.GitHubProject.of(construct: IConstruct)
Find the closest ancestor project for given construct.
When given a project, this it the project itself.
construct
Required
- Type: constructs.IConstruct
Properties
Name | Type | Description |
---|---|---|
| constructs.Node | The tree node. |
| projen.Task | No description. |
| boolean | Whether to commit the managed files by default. |
| projen.Task | No description. |
| projen.Component[] | Returns all the components within this project. |
| projen.Dependencies | Project dependencies. |
| boolean | Whether or not the project is being ejected. |
| projen.FileBase[] | All files in this project. |
| projen.GitAttributesFile | The .gitattributes file for this repository. |
| projen.IgnoreFile | .gitignore. |
| projen.Logger | Logging utilities. |
| string | Project name. |
| string | Absolute output directory of this project. |
| projen.Task | No description. |
| projen.Task | No description. |
| projen.Task | No description. |
| projen.ProjectBuild | Manages the build process of the project. |
| string | The command to use in order to run the projen CLI. |
| projen.Project | The root project. |
| projen.Project[] | Returns all the subprojects within this project. |
| projen.Tasks | Project tasks. |
| projen.Task | No description. |
| projen.Task | This is the "default" task, the one that executes "projen". |
| projen.InitProject | The options used when this project is bootstrapped via projen new . |
| projen.Project | A parent project. |
| projen.ProjectType | No description. |
|
| Auto approve set up for this project. |
| projen.vscode.DevContainer | Access for .devcontainer.json (used for GitHub Codespaces). |
|
| Access all github components. |
| projen.Gitpod | Access for Gitpod. |
| projen.vscode.VsCode | Access all VSCode components. |
node
Required
node
- Deprecated: This is a temporary class. At the moment, our base project
types such as
NodeProject
andJavaProject
are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.
public readonly node: Node;
- Type: constructs.Node
The tree node.
buildTask
Required
buildTask
- Deprecated: This is a temporary class. At the moment, our base project
types such as
NodeProject
andJavaProject
are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.
public readonly buildTask: Task;
- Type: projen.Task
commitGenerated
Required
commitGenerated
- Deprecated: This is a temporary class. At the moment, our base project
types such as
NodeProject
andJavaProject
are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.
public readonly commitGenerated: boolean;
- Type: boolean
Whether to commit the managed files by default.
compileTask
Required
compileTask
- Deprecated: This is a temporary class. At the moment, our base project
types such as
NodeProject
andJavaProject
are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.
public readonly compileTask: Task;
- Type: projen.Task
components
Required
components
- Deprecated: This is a temporary class. At the moment, our base project
types such as
NodeProject
andJavaProject
are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.
public readonly components: Component[];
- Type: projen.Component[]
Returns all the components within this project.
deps
Required
deps
- Deprecated: This is a temporary class. At the moment, our base project
types such as
NodeProject
andJavaProject
are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.
public readonly deps: Dependencies;
- Type: projen.Dependencies
Project dependencies.
ejected
Required
ejected
- Deprecated: This is a temporary class. At the moment, our base project
types such as
NodeProject
andJavaProject
are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.
public readonly ejected: boolean;
- Type: boolean
Whether or not the project is being ejected.
files
Required
files
- Deprecated: This is a temporary class. At the moment, our base project
types such as
NodeProject
andJavaProject
are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.
public readonly files: FileBase[];
- Type: projen.FileBase[]
All files in this project.
gitattributes
Required
gitattributes
- Deprecated: This is a temporary class. At the moment, our base project
types such as
NodeProject
andJavaProject
are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.
public readonly gitattributes: GitAttributesFile;
- Type: projen.GitAttributesFile
The .gitattributes file for this repository.
gitignore
Required
gitignore
- Deprecated: This is a temporary class. At the moment, our base project
types such as
NodeProject
andJavaProject
are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.
public readonly gitignore: IgnoreFile;
- Type: projen.IgnoreFile
.gitignore.
logger
Required
logger
- Deprecated: This is a temporary class. At the moment, our base project
types such as
NodeProject
andJavaProject
are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.
public readonly logger: Logger;
- Type: projen.Logger
Logging utilities.
name
Required
name
- Deprecated: This is a temporary class. At the moment, our base project
types such as
NodeProject
andJavaProject
are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.
public readonly name: string;
- Type: string
Project name.
outdir
Required
outdir
- Deprecated: This is a temporary class. At the moment, our base project
types such as
NodeProject
andJavaProject
are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.
public readonly outdir: string;
- Type: string
Absolute output directory of this project.
packageTask
Required
packageTask
- Deprecated: This is a temporary class. At the moment, our base project
types such as
NodeProject
andJavaProject
are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.
public readonly packageTask: Task;
- Type: projen.Task
postCompileTask
Required
postCompileTask
- Deprecated: This is a temporary class. At the moment, our base project
types such as
NodeProject
andJavaProject
are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.
public readonly postCompileTask: Task;
- Type: projen.Task
preCompileTask
Required
preCompileTask
- Deprecated: This is a temporary class. At the moment, our base project
types such as
NodeProject
andJavaProject
are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.
public readonly preCompileTask: Task;
- Type: projen.Task
projectBuild
Required
projectBuild
- Deprecated: This is a temporary class. At the moment, our base project
types such as
NodeProject
andJavaProject
are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.
public readonly projectBuild: ProjectBuild;
- Type: projen.ProjectBuild
Manages the build process of the project.
projenCommand
Required
projenCommand
- Deprecated: This is a temporary class. At the moment, our base project
types such as
NodeProject
andJavaProject
are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.
public readonly projenCommand: string;
- Type: string
The command to use in order to run the projen CLI.
root
Required
root
- Deprecated: This is a temporary class. At the moment, our base project
types such as
NodeProject
andJavaProject
are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.
public readonly root: Project;
- Type: projen.Project
The root project.
subprojects
Required
subprojects
- Deprecated: This is a temporary class. At the moment, our base project
types such as
NodeProject
andJavaProject
are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.
public readonly subprojects: Project[];
- Type: projen.Project[]
Returns all the subprojects within this project.
tasks
Required
tasks
- Deprecated: This is a temporary class. At the moment, our base project
types such as
NodeProject
andJavaProject
are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.
public readonly tasks: Tasks;
- Type: projen.Tasks
Project tasks.
testTask
Required
testTask
- Deprecated: This is a temporary class. At the moment, our base project
types such as
NodeProject
andJavaProject
are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.
public readonly testTask: Task;
- Type: projen.Task
defaultTask
Optional
defaultTask
- Deprecated: This is a temporary class. At the moment, our base project
types such as
NodeProject
andJavaProject
are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.
public readonly defaultTask: Task;
- Type: projen.Task
This is the "default" task, the one that executes "projen".
Undefined if the project is being ejected.
initProject
Optional
initProject
- Deprecated: This is a temporary class. At the moment, our base project
types such as
NodeProject
andJavaProject
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.
parent
Optional
parent
- Deprecated: This is a temporary class. At the moment, our base project
types such as
NodeProject
andJavaProject
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.
projectType
Required
projectType
- Deprecated: This is a temporary class. At the moment, our base project
types such as
NodeProject
andJavaProject
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
autoApprove
Optional
autoApprove
- Deprecated: This is a temporary class. At the moment, our base project
types such as
NodeProject
andJavaProject
are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.
public readonly autoApprove: AutoApprove;
- Type: AutoApprove
Auto approve set up for this project.
devContainer
Optional
devContainer
- Deprecated: This is a temporary class. At the moment, our base project
types such as
NodeProject
andJavaProject
are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.
public readonly devContainer: DevContainer;
- Type: projen.vscode.DevContainer
Access for .devcontainer.json (used for GitHub Codespaces).
This will be undefined
if devContainer boolean is false
github
Optional
github
- Deprecated: This is a temporary class. At the moment, our base project
types such as
NodeProject
andJavaProject
are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.
public readonly github: GitHub;
- Type: GitHub
Access all github components.
This will be undefined
for subprojects.
gitpod
Optional
gitpod
- Deprecated: This is a temporary class. At the moment, our base project
types such as
NodeProject
andJavaProject
are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.
public readonly gitpod: Gitpod;
- Type: projen.Gitpod
Access for Gitpod.
This will be undefined
if gitpod boolean is false
vscode
Optional
vscode
- Deprecated: This is a temporary class. At the moment, our base project
types such as
NodeProject
andJavaProject
are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.
public readonly vscode: VsCode;
- Type: projen.vscode.VsCode
Access all VSCode components.
This will be undefined
for subprojects.
Constants
Name | Type | Description |
---|---|---|
| string | The name of the default task (the task executed when projen is run without arguments). |
DEFAULT_TASK
Required
DEFAULT_TASK
- Deprecated: This is a temporary class. At the moment, our base project
types such as
NodeProject
andJavaProject
are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.
public readonly DEFAULT_TASK: string;
- Type: string
The name of the default task (the task executed when projen
is run without arguments).
Normally this task should synthesize the project files.
GithubWorkflow
Workflow for GitHub.
A workflow is a configurable automated process made up of one or more jobs.
https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions
Initializers
import { github } from 'projen'
new github.GithubWorkflow(github: GitHub, name: string, options?: GithubWorkflowOptions)
Name | Type | Description |
---|---|---|
|
| The GitHub component of the project this workflow belongs to. |
| string | The name of the workflow, displayed under the repository's "Actions" tab. |
|
| Additional options to configure the workflow. |
github
Required
- Type: GitHub
The GitHub component of the project this workflow belongs to.
name
Required
- Type: string
The name of the workflow, displayed under the repository's "Actions" tab.
options
Optional
- Type: GithubWorkflowOptions
Additional options to configure the workflow.
Methods
Name | Description |
---|---|
| Returns a string representation of this construct. |
| Called after synthesis. |
| Called before synthesis. |
| Synthesizes files to the project output directory. |
| Adds a single job to the workflow. |
| Add jobs to the workflow. |
| Get a single job from the workflow. |
| Add events to triggers the workflow. |
| Removes a single job to the workflow. |
| Updates a single job to the workflow. |
| 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.
id
Required
- Type: string
The job name (unique within the workflow).
job
Required
- Type: JobCallingReusableWorkflow | Job
The job specification.
addJobs
public addJobs(jobs: {[ key: string ]: JobCallingReusableWorkflow | Job}): void
Add jobs to the workflow.
jobs
Required
- Type: {[ key: string ]: JobCallingReusableWorkflow | Job}
Jobs to add.
getJob
public getJob(id: string): JobCallingReusableWorkflow | Job
Get a single job from the workflow.
id
Required
- Type: string
The job name (unique within the workflow).
on
public on(events: Triggers): void
Add events to triggers the workflow.
events
Required
- Type: Triggers
The event(s) to trigger the workflow.
removeJob
public removeJob(id: string): void
Removes a single job to the workflow.
id
Required
- 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.
id
Required
- Type: string
The job name (unique within the workflow).
job
Required
- Type: JobCallingReusableWorkflow | Job
updateJobs
public updateJobs(jobs: {[ key: string ]: JobCallingReusableWorkflow | Job}): void
Updates jobs for this worklow Does a complete replace, it does not try to merge the jobs.
jobs
Required
- Type: {[ key: string ]: JobCallingReusableWorkflow | Job}
Jobs to update.
Static Functions
Name | Description |
---|---|
| Checks if x is a construct. |
| 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.
x
Required
- Type: any
Any object.
isComponent
import { github } from 'projen'
github.GithubWorkflow.isComponent(x: any)
Test whether the given construct is a component.
x
Required
- Type: any
Properties
Name | Type | Description |
---|---|---|
| constructs.Node | The tree node. |
| projen.Project | No description. |
| string | The name of the workflow. |
|
| GitHub API authentication method used by projen workflows. |
|
| The concurrency configuration of the workflow. |
| {[ key: string ]: string} | Additional environment variables to set for the workflow. |
| projen.YamlFile | The workflow YAML file. |
| string | The name for workflow runs generated from the workflow. |
node
Required
public readonly node: Node;
- Type: constructs.Node
The tree node.
project
Required
public readonly project: Project;
- Type: projen.Project
name
Required
public readonly name: string;
- Type: string
The name of the workflow.
GitHub displays the names of your workflows under your repository's "Actions" tab.
https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#name
projenCredentials
Required
public readonly projenCredentials: GithubCredentials;
- Type: GithubCredentials
GitHub API authentication method used by projen workflows.
concurrency
Optional
public readonly concurrency: ConcurrencyOptions;
- Type: ConcurrencyOptions
The concurrency configuration of the workflow.
undefined means no concurrency limitations.
env
Optional
public readonly env: {[ key: string ]: string};
- Type: {[ key: string ]: string}
Additional environment variables to set for the workflow.
file
Optional
public readonly file: YamlFile;
- Type: projen.YamlFile
The workflow YAML file.
May not exist if workflowsEnabled
is false on GitHub
.
runName
Optional
public readonly runName: string;
- Type: string
The name for workflow runs generated from the workflow.
GitHub displays the
workflow run name in the list of workflow runs on your repository's
"Actions" tab. If run-name
is omitted or is only whitespace, then the run
name is set to event-specific information for the workflow run. For
example, for a workflow triggered by a push
or pull_request
event, it
is set as the commit message.
This value can include expressions and can reference github
and inputs
contexts.
MergeQueue
Merge pull requests using a merge queue.
Initializers
import { github } from 'projen'
new github.MergeQueue(scope: IConstruct, options?: MergeQueueOptions)
Name | Type | Description |
---|---|---|
| constructs.IConstruct | No description. |
|
| No description. |
scope
Required
- Type: constructs.IConstruct
options
Optional
- Type: MergeQueueOptions
Methods
Name | Description |
---|---|
| Returns a string representation of this construct. |
| Called after synthesis. |
| Called before synthesis. |
| 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
Name | Description |
---|---|
| Checks if x is a construct. |
| Test whether the given construct is a component. |
isConstruct
import { github } from 'projen'
github.MergeQueue.isConstruct(x: any)
Checks if x
is a construct.
Use this method instead of instanceof
to properly detect Construct
instances, even when the construct library is symlinked.
Explanation: in JavaScript, multiple copies of the constructs
library on
disk are seen as independent, completely different libraries. As a
consequence, the class Construct
in each copy of the constructs
library
is seen as a different class, and an instance of one class will not test as
instanceof
the other class. npm install
will not create installations
like this, but users may manually symlink construct libraries together or
use a monorepo tool: in those cases, multiple copies of the constructs
library can be accidentally installed, and instanceof
will behave
unpredictably. It is safest to avoid using instanceof
, and using
this type-testing method instead.
x
Required
- Type: any
Any object.
isComponent
import { github } from 'projen'
github.MergeQueue.isComponent(x: any)
Test whether the given construct is a component.
x
Required
- Type: any
Properties
Name | Type | Description |
---|---|---|
| constructs.Node | The tree node. |
| projen.Project | No description. |
node
Required
public readonly node: Node;
- Type: constructs.Node
The tree node.
project
Required
public readonly project: Project;
- Type: projen.Project
Mergify
Initializers
import { github } from 'projen'
new github.Mergify(github: GitHub, options?: MergifyOptions)
Name | Type | Description |
---|---|---|
|
| No description. |
|
| No description. |
github
Required
- Type: GitHub
options
Optional
- Type: MergifyOptions
Methods
Name | Description |
---|---|
| Returns a string representation of this construct. |
| Called after synthesis. |
| Called before synthesis. |
| Synthesizes files to the project output directory. |
| No description. |
| 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
queue
Required
- Type: MergifyQueue
addRule
public addRule(rule: MergifyRule): void
rule
Required
- Type: MergifyRule
Static Functions
Name | Description |
---|---|
| Checks if x is a construct. |
| 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.
x
Required
- Type: any
Any object.
isComponent
import { github } from 'projen'
github.Mergify.isComponent(x: any)
Test whether the given construct is a component.
x
Required
- Type: any
Properties
Name | Type | Description |
---|---|---|
| constructs.Node | The tree node. |
| projen.Project | No description. |
node
Required
public readonly node: Node;
- Type: constructs.Node
The tree node.
project
Required
public readonly project: Project;
- Type: projen.Project
PullRequestBackport
Initializers
import { github } from 'projen'
new github.PullRequestBackport(scope: IConstruct, options?: PullRequestBackportOptions)
Name | Type | Description |
---|---|---|
| constructs.IConstruct | No description. |
|
| No description. |
scope
Required
- Type: constructs.IConstruct
options
Optional
Methods
Name | Description |
---|---|
| Returns a string representation of this construct. |
| Called after synthesis. |
| Called before synthesis. |
| 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
Name | Description |
---|---|
| Checks if x is a construct. |
| Test whether the given construct is a component. |
isConstruct
import { github } from 'projen'
github.PullRequestBackport.isConstruct(x: any)
Checks if x
is a construct.
Use this method instead of instanceof
to properly detect Construct
instances, even when the construct library is symlinked.
Explanation: in JavaScript, multiple copies of the constructs
library on
disk are seen as independent, completely different libraries. As a
consequence, the class Construct
in each copy of the constructs
library
is seen as a different class, and an instance of one class will not test as
instanceof
the other class. npm install
will not create installations
like this, but users may manually symlink construct libraries together or
use a monorepo tool: in those cases, multiple copies of the constructs
library can be accidentally installed, and instanceof
will behave
unpredictably. It is safest to avoid using instanceof
, and using
this type-testing method instead.
x
Required
- Type: any
Any object.
isComponent
import { github } from 'projen'
github.PullRequestBackport.isComponent(x: any)
Test whether the given construct is a component.
x
Required
- Type: any
Properties
Name | Type | Description |
---|---|---|
| constructs.Node | The tree node. |
| projen.Project | No description. |
| projen.JsonFile | No description. |
|
| No description. |
node
Required
public readonly node: Node;
- Type: constructs.Node
The tree node.
project
Required
public readonly project: Project;
- Type: projen.Project
file
Required
public readonly file: JsonFile;
- Type: projen.JsonFile
workflow
Required
public readonly workflow: GithubWorkflow;
- Type: GithubWorkflow
PullRequestLint
Configure validations to run on GitHub pull requests.
Only generates a file if at least one linter is configured.
Initializers
import { github } from 'projen'
new github.PullRequestLint(github: GitHub, options?: PullRequestLintOptions)
Name | Type | Description |
---|---|---|
|
| No description. |
|
| No description. |
github
Required
- Type: GitHub
options
Optional
- Type: PullRequestLintOptions
Methods
Name | Description |
---|---|
| Returns a string representation of this construct. |
| Called after synthesis. |
| Called before synthesis. |
| 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
Name | Description |
---|---|
| Checks if x is a construct. |
| 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.
x
Required
- Type: any
Any object.
isComponent
import { github } from 'projen'
github.PullRequestLint.isComponent(x: any)
Test whether the given construct is a component.
x
Required
- Type: any
Properties
Name | Type | Description |
---|---|---|
| constructs.Node | The tree node. |
| projen.Project | No description. |
node
Required
public readonly node: Node;
- Type: constructs.Node
The tree node.
project
Required
public readonly project: Project;
- Type: projen.Project
PullRequestTemplate
Template for GitHub pull requests.
Initializers
import { github } from 'projen'
new github.PullRequestTemplate(github: GitHub, options?: PullRequestTemplateOptions)
Name | Type | Description |
---|---|---|
|
| No description. |
|
| No description. |
github
Required
- Type: GitHub
options
Optional
Methods
Name | Description |
---|---|
| Returns a string representation of this construct. |
| Called after synthesis. |
| Called before synthesis. |
| Writes the file to the project's output directory. |
| 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.
line
Required
- Type: string
the line to add (can use tokens).
Static Functions
Name | Description |
---|---|
| Checks if x is a construct. |
| Test whether the given construct is a component. |
| 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.
x
Required
- Type: any
Any object.
isComponent
import { github } from 'projen'
github.PullRequestTemplate.isComponent(x: any)
Test whether the given construct is a component.
x
Required
- Type: any
of
import { github } from 'projen'
github.PullRequestTemplate.of(project: Project)
Returns the PullRequestTemplate
instance associated with a project or undefined
if there is no PullRequestTemplate.
project
Required
- Type: projen.Project
The project.
Properties
Name | Type | Description |
---|---|---|
| constructs.Node | The tree node. |
| projen.Project | No description. |
| string | The absolute path of this file. |
| string | The file path, relative to the project's outdir. |
| boolean | Indicates if the file has been changed during synthesis. |
| string | The projen marker, used to identify files as projen-generated. |
| boolean | Indicates if the file should be marked as executable. |
| boolean | Indicates if the file should be read-only or read-write. |
node
Required
public readonly node: Node;
- Type: constructs.Node
The tree node.
project
Required
public readonly project: Project;
- Type: projen.Project
absolutePath
Required
public readonly absolutePath: string;
- Type: string
The absolute path of this file.
path
Required
public readonly path: string;
- Type: string
The file path, relative to the project's outdir.
changed
Optional
public readonly changed: boolean;
- Type: boolean
Indicates if the file has been changed during synthesis.
This property is
only available in postSynthesize()
hooks. If this is undefined
, the
file has not been synthesized yet.
marker
Optional
public readonly marker: string;
- Type: string
The projen marker, used to identify files as projen-generated.
Value is undefined if the project is being ejected.
executable
Required
public readonly executable: boolean;
- Type: boolean
Indicates if the file should be marked as executable.
readonly
Required
public readonly readonly: boolean;
- Type: boolean
Indicates if the file should be read-only or read-write.
Stale
Warns and then closes issues and PRs that have had no activity for a specified amount of time.
The default configuration will:
- Add a "Stale" label to pull requests after 14 days and closed after 2 days
- Add a "Stale" label to issues after 60 days and closed after 7 days
- If a comment is added, the label will be removed and timer is restarted.
Initializers
import { github } from 'projen'
new github.Stale(github: GitHub, options?: StaleOptions)
Name | Type | Description |
---|---|---|
|
| No description. |
|
| No description. |
github
Required
- Type: GitHub
options
Optional
- Type: StaleOptions
Methods
Name | Description |
---|---|
| Returns a string representation of this construct. |
| Called after synthesis. |
| Called before synthesis. |
| 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
Name | Description |
---|---|
| Checks if x is a construct. |
| 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.
x
Required
- Type: any
Any object.
isComponent
import { github } from 'projen'
github.Stale.isComponent(x: any)
Test whether the given construct is a component.
x
Required
- Type: any
Properties
Name | Type | Description |
---|---|---|
| constructs.Node | The tree node. |
| projen.Project | No description. |
node
Required
public readonly node: Node;
- Type: constructs.Node
The tree node.
project
Required
public readonly project: Project;
- Type: projen.Project
TaskWorkflow
A GitHub workflow for common build tasks within a project.
Initializers
import { github } from 'projen'
new github.TaskWorkflow(github: GitHub, options: TaskWorkflowOptions)
Name | Type | Description |
---|---|---|
|
| No description. |
|
| No description. |
github
Required
- Type: GitHub
options
Required
- Type: TaskWorkflowOptions
Methods
Name | Description |
---|---|
| Returns a string representation of this construct. |
| Called after synthesis. |
| Called before synthesis. |
| Synthesizes files to the project output directory. |
| Adds a single job to the workflow. |
| Add jobs to the workflow. |
| Get a single job from the workflow. |
| Add events to triggers the workflow. |
| Removes a single job to the workflow. |
| Updates a single job to the workflow. |
| 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.
id
Required
- Type: string
The job name (unique within the workflow).
job
Required
- Type: JobCallingReusableWorkflow | Job
The job specification.
addJobs
public addJobs(jobs: {[ key: string ]: JobCallingReusableWorkflow | Job}): void
Add jobs to the workflow.
jobs
Required
- Type: {[ key: string ]: JobCallingReusableWorkflow | Job}
Jobs to add.
getJob
public getJob(id: string): JobCallingReusableWorkflow | Job
Get a single job from the workflow.
id
Required
- Type: string
The job name (unique within the workflow).
on
public on(events: Triggers): void
Add events to triggers the workflow.
events
Required
- Type: Triggers
The event(s) to trigger the workflow.
removeJob
public removeJob(id: string): void
Removes a single job to the workflow.
id
Required
- 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.
id
Required
- Type: string
The job name (unique within the workflow).
job
Required
- Type: JobCallingReusableWorkflow | Job
updateJobs
public updateJobs(jobs: {[ key: string ]: JobCallingReusableWorkflow | Job}): void
Updates jobs for this worklow Does a complete replace, it does not try to merge the jobs.
jobs
Required
- Type: {[ key: string ]: JobCallingReusableWorkflow | Job}
Jobs to update.
Static Functions
Name | Description |
---|---|
| Checks if x is a construct. |
| 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.
x
Required
- Type: any
Any object.
isComponent
import { github } from 'projen'
github.TaskWorkflow.isComponent(x: any)
Test whether the given construct is a component.
x
Required
- Type: any
Properties
Name | Type | Description |
---|---|---|
| constructs.Node | The tree node. |
| projen.Project | No description. |
| string | The name of the workflow. |
|
| GitHub API authentication method used by projen workflows. |
|
| The concurrency configuration of the workflow. |
| {[ key: string ]: string} | Additional environment variables to set for the workflow. |
| projen.YamlFile | The workflow YAML file. |
| string | The name for workflow runs generated from the workflow. |
| string | No description. |
| string | No description. |
node
Required
public readonly node: Node;
- Type: constructs.Node
The tree node.
project
Required
public readonly project: Project;
- Type: projen.Project
name
Required
public readonly name: string;
- Type: string
The name of the workflow.
GitHub displays the names of your workflows under your repository's "Actions" tab.
https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#name
projenCredentials
Required
public readonly projenCredentials: GithubCredentials;
- Type: GithubCredentials
GitHub API authentication method used by projen workflows.
concurrency
Optional
public readonly concurrency: ConcurrencyOptions;
- Type: ConcurrencyOptions
The concurrency configuration of the workflow.
undefined means no concurrency limitations.
env
Optional
public readonly env: {[ key: string ]: string};
- Type: {[ key: string ]: string}
Additional environment variables to set for the workflow.
file
Optional
public readonly file: YamlFile;
- Type: projen.YamlFile
The workflow YAML file.
May not exist if workflowsEnabled
is false on GitHub
.
runName
Optional
public readonly runName: string;
- Type: string
The name for workflow runs generated from the workflow.
GitHub displays the
workflow run name in the list of workflow runs on your repository's
"Actions" tab. If run-name
is omitted or is only whitespace, then the run
name is set to event-specific information for the workflow run. For
example, for a workflow triggered by a push
or pull_request
event, it
is set as the commit message.
This value can include expressions and can reference github
and inputs
contexts.
jobId
Required
public readonly jobId: string;
- Type: string
artifactsDirectory
Optional
public readonly artifactsDirectory: string;
- Type: string
TaskWorkflowJob
The primary or initial job of a TaskWorkflow.
Initializers
import { github } from 'projen'
new github.TaskWorkflowJob(scope: IConstruct, task: Task, options: TaskWorkflowJobOptions)
Name | Type | Description |
---|---|---|
| constructs.IConstruct | should be part of the project the Task belongs to. |
| projen.Task | the main task that is run as part of this job. |
|
| options to configure the TaskWorkflowJob. |
scope
Required
- Type: constructs.IConstruct
should be part of the project the Task belongs to.
task
Required
- Type: projen.Task
the main task that is run as part of this job.
options
Required
- Type: TaskWorkflowJobOptions
options to configure the TaskWorkflowJob.
Methods
Name | Description |
---|---|
| Returns a string representation of this construct. |
| Called after synthesis. |
| Called before synthesis. |
| 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
Name | Description |
---|---|
| Checks if x is a construct. |
| 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.
x
Required
- Type: any
Any object.
isComponent
import { github } from 'projen'
github.TaskWorkflowJob.isComponent(x: any)
Test whether the given construct is a component.
x
Required
- Type: any
Properties
Name | Type | Description |
---|---|---|
| constructs.Node | The tree node. |
| projen.Project | No description. |
|
| No description. |
|
| No description. |
| any | No description. |
|
| No description. |
| boolean | No description. |
|
| No description. |
| {[ key: string ]: string} | No description. |
| any | No description. |
| string | No description. |
| string | No description. |
| string[] | No description. |
|
| No description. |
| string[] | No description. |
| projen.GroupRunnerOptions | No description. |
|
| No description. |
|
| No description. |
| number | No description. |
|
| No description. |
node
Required
public readonly node: Node;
- Type: constructs.Node
The tree node.
project
Required
public readonly project: Project;
- Type: projen.Project
permissions
Required
public readonly permissions: JobPermissions;
- Type: JobPermissions
steps
Required
public readonly steps: JobStep[];
- Type: JobStep[]
concurrency
Optional
public readonly concurrency: any;
- Type: any
container
Optional
public readonly container: ContainerOptions;
- Type: ContainerOptions
continueOnError
Optional
public readonly continueOnError: boolean;
- Type: boolean
defaults
Optional
public readonly defaults: JobDefaults;
- Type: JobDefaults
env
Optional
public readonly env: {[ key: string ]: string};
- Type: {[ key: string ]: string}
environment
Optional
public readonly environment: any;
- Type: any
if
Optional
public readonly if: string;
- Type: string
name
Optional
public readonly name: string;
- Type: string
needs
Optional
public readonly needs: string[];
- Type: string[]
outputs
Optional
public readonly outputs: {[ key: string ]: JobStepOutput};
- Type: {[ key: string ]: JobStepOutput}
runsOn
Optional
public readonly runsOn: string[];
- Type: string[]
runsOnGroup
Optional
public readonly runsOnGroup: GroupRunnerOptions;
- Type: projen.GroupRunnerOptions
services
Optional
public readonly services: {[ key: string ]: ContainerOptions};
- Type: {[ key: string ]: ContainerOptions}
strategy
Optional
public readonly strategy: JobStrategy;
- Type: JobStrategy
timeoutMinutes
Optional
public readonly timeoutMinutes: number;
- Type: number
tools
Optional
public readonly tools: Tools;
- Type: Tools
Structs
AutoApproveOptions
Options for 'AutoApprove'.
Initializer
import { github } from 'projen'
const autoApproveOptions: github.AutoApproveOptions = { ... }
Properties
Name | Type | Description |
---|---|---|
| string[] | Only pull requests authored by these Github usernames will be auto-approved. |
| string | Only pull requests with this label will be auto-approved. |
| string[] | Github Runner selection labels. |
| projen.GroupRunnerOptions | Github Runner Group selection options. |
| string | A GitHub secret name which contains a GitHub Access Token with write permissions for the pull_request scope. |
allowedUsernames
Optional
public readonly allowedUsernames: string[];
- Type: string[]
- Default: ['github-bot']
Only pull requests authored by these Github usernames will be auto-approved.
label
Optional
public readonly label: string;
- Type: string
- Default: 'auto-approve'
Only pull requests with this label will be auto-approved.
runsOn
Optional
public readonly runsOn: string[];
- Type: string[]
- Default: ["ubuntu-latest"]
Github Runner selection labels.
runsOnGroup
Optional
public readonly runsOnGroup: GroupRunnerOptions;
- Type: projen.GroupRunnerOptions
Github Runner Group selection options.
secret
Optional
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 inNodeProjectOptions
, then you must use a different token here.
AutoMergeOptions
Initializer
import { github } from 'projen'
const autoMergeOptions: github.AutoMergeOptions = { ... }
Properties
Name | Type | Description |
---|---|---|
| number | Number of approved code reviews. |
| string[] | List of labels that will prevent auto-merging. |
| string | Name of the mergify queue. |
| string | Name of the mergify rule. |
approvedReviews
Optional
public readonly approvedReviews: number;
- Type: number
- Default: 1
Number of approved code reviews.
blockingLabels
Optional
public readonly blockingLabels: string[];
- Type: string[]
- Default: ['do-not-merge']
List of labels that will prevent auto-merging.
queueName
Optional
public readonly queueName: string;
- Type: string
- Default: 'default'
Name of the mergify queue.
ruleName
Optional
public readonly ruleName: string;
- Type: string
- Default: 'Automatic merge on approval and successful build'
Name of the mergify rule.
AutoQueueOptions
Options for 'AutoQueue'.
Initializer
import { github } from 'projen'
const autoQueueOptions: github.AutoQueueOptions = { ... }
Properties
Name | Type | Description |
---|---|---|
| string[] | Only pull requests authored by these Github usernames will have auto-queue enabled. |
| string[] | Only pull requests with one of this labels will have auto-queue enabled. |
|
| The method used to add the PR to the merge queue Any branch protection rules must allow this merge method. |
|
| Choose a method for authenticating with GitHub to enable auto-queue on pull requests. |
| string[] | Github Runner selection labels. |
| string[] | The branch names that we should auto-queue for. |
allowedUsernames
Optional
public readonly allowedUsernames: string[];
- Type: string[]
- Default: pull requests from all users are eligible for auto-queuing
Only pull requests authored by these Github usernames will have auto-queue enabled.
labels
Optional
public readonly labels: string[];
- Type: string[]
- Default: all pull requests are eligible for auto-queueing
Only pull requests with one of this labels will have auto-queue enabled.
mergeMethod
Optional
public readonly mergeMethod: MergeMethod;
- Type: MergeMethod
- Default: MergeMethod.SQUASH
The method used to add the PR to the merge queue Any branch protection rules must allow this merge method.
projenCredentials
Optional
public readonly projenCredentials: GithubCredentials;
- Type: GithubCredentials
- Default: uses credentials from the GitHub component
Choose a method for authenticating with GitHub to enable auto-queue on pull requests.
The workflow cannot use a default github token. Queuing a PR with the default token will not trigger any merge queue workflows, which results in the PR just not getting merged at all.
runsOn
Optional
public readonly runsOn: string[];
- Type: string[]
- Default: ["ubuntu-latest"]
Github Runner selection labels.
targetBranches
Optional
public readonly targetBranches: string[];
- Type: string[]
The branch names that we should auto-queue for.
This set of branches should be a subset of MergeQueueOptions.targetBranches
.
Be sure not to enable autoQueue
for branches that don't have branch rules
with merge requirements set up, otherwise new PRs will be merged
immediately after creating without a chance for review.
Automatically merging a set of Stacked PRs
If you set this to ['main']
you can automatically merge a set of Stacked PRs
in the right order. It works like this:
- Create PR #1 from branch
a
, targetingmain
. - Create PR #2 from branch
b
, targeting brancha
. - Create PR #3 from branch
c
, targeting branchb
.
Initially, PR #1 will be set to auto-merge, PRs #2 and #3 will not.
Once PR #1 passes all of its requirements it will merge. That will delete
branch a
and change the target branch of PR #2 change to main
. At that
point, auto-queueing will switch on for PR #2 and it gets merged, etc.
[!IMPORTANT] This component will never disable AutoMerge, only enable it. So if a PR is initially targeted at one of the branches in this list, and then subsequently retargeted to another branch, AutoMerge is not automatically turned off.
CheckoutOptions
Initializer
import { github } from 'projen'
const checkoutOptions: github.CheckoutOptions = { ... }
Properties
Name | Type | Description |
---|---|---|
| {[ key: string ]: string} | Sets environment variables for steps to use in the runner environment. |
| string | A unique identifier for the step. |
| string | You can use the if conditional to prevent a job from running unless a condition is met. |
| string | A name for your step to display on GitHub. |
| string | Specifies a working directory for a step. |
| boolean | Prevents a job from failing when a step fails. |
| number | The maximum number of minutes to run the step before killing the process. |
|
| Options for checkout . |
env
Optional
public readonly env: {[ key: string ]: string};
- Type: {[ key: string ]: string}
Sets environment variables for steps to use in the runner environment.
You can also set environment variables for the entire workflow or a job.
id
Optional
public readonly id: string;
- Type: string
A unique identifier for the step.
You can use the id to reference the step in contexts.
if
Optional
public readonly if: string;
- Type: string
You can use the if conditional to prevent a job from running unless a condition is met.
You can use any supported context and expression to create a conditional.
name
Optional
public readonly name: string;
- Type: string
A name for your step to display on GitHub.
workingDirectory
Optional
public readonly workingDirectory: string;
- Type: string
Specifies a working directory for a step.
Overrides a job's working directory.
continueOnError
Optional
public readonly continueOnError: boolean;
- Type: boolean
Prevents a job from failing when a step fails.
Set to true to allow a job to pass when this step fails.
timeoutMinutes
Optional
public readonly timeoutMinutes: number;
- Type: number
The maximum number of minutes to run the step before killing the process.
with
Optional
public readonly with: CheckoutWith;
- Type: CheckoutWith
Options for checkout
.
CheckoutWith
Options for checkout
.
Initializer
import { github } from 'projen'
const checkoutWith: github.CheckoutWith = { ... }
Properties
Name | Type | Description |
---|---|---|
| number | Number of commits to fetch. |
| boolean | Whether LFS is enabled for the GitHub repository. |
| string | Relative path under $GITHUB_WORKSPACE to place the repository. |
| string | Branch or tag name. |
| string | The repository (owner/repo) to use. |
| string | A GitHub token to use when checking out the repository. |
fetchDepth
Optional
public readonly fetchDepth: number;
- Type: number
- Default: 1
Number of commits to fetch.
0 indicates all history for all branches and tags.
lfs
Optional
public readonly lfs: boolean;
- Type: boolean
- Default: false
Whether LFS is enabled for the GitHub repository.
path
Optional
public readonly path: string;
- Type: string
- Default: $GITHUB_WORKSPACE
Relative path under $GITHUB_WORKSPACE to place the repository.
ref
Optional
public readonly ref: string;
- Type: string
- Default: the default branch is implicitly used
Branch or tag name.
repository
Optional
public readonly repository: string;
- Type: string
- Default: the default repository is implicitly used
The repository (owner/repo) to use.
token
Optional
public readonly token: string;
- Type: string
- Default: the default GITHUB_TOKEN is implicitly used
A GitHub token to use when checking out the repository.
If the intent is to push changes back to the branch, then you must use a
PAT with repo
(and possibly workflows
) permissions.
CheckoutWithPatchOptions
Options for checkoutWithPatch
.
Initializer
import { github } from 'projen'
const checkoutWithPatchOptions: github.CheckoutWithPatchOptions = { ... }
Properties
Name | Type | Description |
---|---|---|
| number | Number of commits to fetch. |
| boolean | Whether LFS is enabled for the GitHub repository. |
| string | Relative path under $GITHUB_WORKSPACE to place the repository. |
| string | Branch or tag name. |
| string | The repository (owner/repo) to use. |
| string | A GitHub token to use when checking out the repository. |
| string | The name of the artifact the patch is stored as. |
fetchDepth
Optional
public readonly fetchDepth: number;
- Type: number
- Default: 1
Number of commits to fetch.
0 indicates all history for all branches and tags.
lfs
Optional
public readonly lfs: boolean;
- Type: boolean
- Default: false
Whether LFS is enabled for the GitHub repository.
path
Optional
public readonly path: string;
- Type: string
- Default: $GITHUB_WORKSPACE
Relative path under $GITHUB_WORKSPACE to place the repository.
ref
Optional
public readonly ref: string;
- Type: string
- Default: the default branch is implicitly used
Branch or tag name.
repository
Optional
public readonly repository: string;
- Type: string
- Default: the default repository is implicitly used
The repository (owner/repo) to use.
token
Optional
public readonly token: string;
- Type: string
- Default: the default GITHUB_TOKEN is implicitly used
A GitHub token to use when checking out the repository.
If the intent is to push changes back to the branch, then you must use a
PAT with repo
(and possibly workflows
) permissions.
patchFile
Optional
public readonly patchFile: string;
- Type: string
- Default: ".repo.patch"
The name of the artifact the patch is stored as.
ConcurrencyOptions
Options for concurrency
.
Initializer
import { github } from 'projen'
const concurrencyOptions: github.ConcurrencyOptions = { ... }
Properties
Name | Type | Description |
---|---|---|
| boolean | When a workflow is triggered while another one (in the same group) is running, should GitHub cancel the running workflow? |
| string | Concurrency group controls which workflow runs will share the same concurrency limit. |
cancelInProgress
Optional
public readonly cancelInProgress: boolean;
- Type: boolean
- Default: false
When a workflow is triggered while another one (in the same group) is running, should GitHub cancel the running workflow?
group
Optional
public readonly group: string;
- Type: string
- Default: ${{ github.workflow }}
Concurrency group controls which workflow runs will share the same concurrency limit.
For example, if you specify ${{ github.workflow }}-${{ github.ref }}
, workflow runs triggered
on the same branch cannot run concurrenty, but workflows runs triggered on different branches can.
ContributorStatementOptions
Options for requiring a contributor statement on Pull Requests.
Initializer
import { github } from 'projen'
const contributorStatementOptions: github.ContributorStatementOptions = { ... }
Properties
Name | Type | Description |
---|---|---|
| string[] | Pull requests with one of these labels are exempted from a contributor statement. |
| string[] | Pull requests from these GitHub users are exempted from a contributor statement. |
exemptLabels
Optional
public readonly exemptLabels: string[];
- Type: string[]
- Default: no labels are excluded
Pull requests with one of these labels are exempted from a contributor statement.
exemptUsers
Optional
public readonly exemptUsers: string[];
- Type: string[]
- Default: no users are exempted
Pull requests from these GitHub users are exempted from a contributor statement.
CreatePullRequestOptions
Initializer
import { github } from 'projen'
const createPullRequestOptions: github.CreatePullRequestOptions = { ... }
Properties
Name | Type | Description |
---|---|---|
| string | Description added to the pull request. |
| string | The full title used to create the pull request. |
| string | The name of the workflow that will create the PR. |
| string[] | Assignees to add on the PR. |
| string | Sets the pull request base branch. |
| string | The pull request branch name. |
|
| The job credentials used to create the pull request. |
|
| The git identity used to create the commit. |
| string[] | Labels to apply on the PR. |
| boolean | Add Signed-off-by line by the committer at the end of the commit log message. |
| string | The step ID which produces the output which indicates if a patch was created. |
| string | The name of the step displayed on GitHub. |
pullRequestDescription
Required
public readonly pullRequestDescription: string;
- Type: string
Description added to the pull request.
Providence information are automatically added.
pullRequestTitle
Required
public readonly pullRequestTitle: string;
- Type: string
The full title used to create the pull request.
If PR titles are validated in this repo, the title should comply with the respective rules.
workflowName
Required
public readonly workflowName: string;
- Type: string
The name of the workflow that will create the PR.
assignees
Optional
public readonly assignees: string[];
- Type: string[]
- Default: no assignees
Assignees to add on the PR.
baseBranch
Optional
public readonly baseBranch: string;
- Type: string
- Default: The branch checked out in the workflow.
Sets the pull request base branch.
branchName
Optional
public readonly branchName: string;
- Type: string
- Default:
github-actions/${options.workflowName}
The pull request branch name.
credentials
Optional
public readonly credentials: GithubCredentials;
- Type: GithubCredentials
The job credentials used to create the pull request.
Provided credentials must have permissions to create a pull request on the repository.
gitIdentity
Optional
public readonly gitIdentity: GitIdentity;
- Type: GitIdentity
- Default: the default github-actions user
The git identity used to create the commit.
labels
Optional
public readonly labels: string[];
- Type: string[]
- Default: no labels.
Labels to apply on the PR.
signoff
Optional
public readonly signoff: boolean;
- Type: boolean
- Default: true
Add Signed-off-by line by the committer at the end of the commit log message.
stepId
Optional
public readonly stepId: string;
- Type: string
- Default: "create_pr"
The step ID which produces the output which indicates if a patch was created.
stepName
Optional
public readonly stepName: string;
- Type: string
- Default: "Create Pull Request"
The name of the step displayed on GitHub.
DependabotAllow
You can use the allow
option to customize which dependencies are updated.
The allow option supports the following options.
Initializer
import { github } from 'projen'
const dependabotAllow: github.DependabotAllow = { ... }
Properties
Name | Type | Description |
---|---|---|
| string | Use to allow updates for dependencies with matching names, optionally using * to match zero or more characters. |
dependencyName
Required
public readonly dependencyName: string;
- Type: string
Use to allow updates for dependencies with matching names, optionally using *
to match zero or more characters.
For Java dependencies, the format of the dependency-name attribute is:
groupId:artifactId
, for example: org.kohsuke:github-api
.
DependabotGroup
Defines a single group for dependency updates.
Initializer
import { github } from 'projen'
const dependabotGroup: github.DependabotGroup = { ... }
Properties
Name | Type | Description |
---|---|---|
| string[] | Define a list of strings (with or without wildcards) that will match package names to form this dependency group. |
| string[] | Optionally you can use this to exclude certain dependencies from the group. |
patterns
Required
public readonly patterns: string[];
- Type: string[]
Define a list of strings (with or without wildcards) that will match package names to form this dependency group.
excludePatterns
Optional
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
Name | Type | Description |
---|---|---|
| string | Use to ignore updates for dependencies with matching names, optionally using * to match zero or more characters. |
| string[] | Use to ignore specific versions or ranges of versions. |
dependencyName
Required
public readonly dependencyName: string;
- Type: string
Use to ignore updates for dependencies with matching names, optionally using *
to match zero or more characters.
For Java dependencies, the format of the dependency-name attribute is:
groupId:artifactId
, for example: org.kohsuke:github-api
.
versions
Optional
public readonly versions: string[];
- Type: string[]
Use to ignore specific versions or ranges of versions.
If you want to
define a range, use the standard pattern for the package manager (for
example: ^1.0.0
for npm, or ~> 2.0
for Bundler).
DependabotOptions
Initializer
import { github } from 'projen'
const dependabotOptions: github.DependabotOptions = { ... }
Properties
Name | Type | Description |
---|---|---|
|
| https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#allow. |
| string[] | Specify individual assignees or teams of assignees for all pull requests raised for a package manager. |
|
| https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#groups. |
|
| You can use the ignore option to customize which dependencies are updated. |
| boolean | Ignores updates to projen . |
| string[] | List of labels to apply to the created PR's. |
| number | Sets the maximum of pull requests Dependabot opens for version updates. |
|
| Map of package registries to use. |
| string[] | Specify individual reviewers or teams of reviewers for all pull requests raised for a package manager. |
|
| How often to check for new versions and raise pull requests. |
| string | https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#target-branch You can configure the target branch for raising pull requests for version updates against. |
|
| The strategy to use when edits manifest and lock files. |
allow
Optional
public readonly allow: DependabotAllow[];
- Type: DependabotAllow[]
- Default: []
Use the allow option to customize which dependencies are updated. This applies to both version and security updates.
assignees
Optional
public readonly assignees: string[];
- Type: string[]
- Default: []
Specify individual assignees or teams of assignees for all pull requests raised for a package manager.
groups
Optional
public readonly groups: {[ key: string ]: DependabotGroup};
- Type: {[ key: string ]: DependabotGroup}
- Default: []
You can create groups to package dependency updates together into a single PR.
ignore
Optional
public readonly ignore: DependabotIgnore[];
- Type: DependabotIgnore[]
- Default: []
You can use the ignore
option to customize which dependencies are updated.
The ignore option supports the following options.
ignoreProjen
Optional
public readonly ignoreProjen: boolean;
- Type: boolean
- Default: true
Ignores updates to projen
.
This is required since projen updates may cause changes in committed files and anti-tamper checks will fail.
Projen upgrades are covered through the ProjenUpgrade
class.
labels
Optional
public readonly labels: string[];
- Type: string[]
List of labels to apply to the created PR's.
openPullRequestsLimit
Optional
public readonly openPullRequestsLimit: number;
- Type: number
- Default: 5
Sets the maximum of pull requests Dependabot opens for version updates.
Dependabot will not open any new requests until some of those open requests are merged or closed.
registries
Optional
public readonly registries: {[ key: string ]: DependabotRegistry};
- Type: {[ key: string ]: DependabotRegistry}
- Default: use public registries
Map of package registries to use.
reviewers
Optional
public readonly reviewers: string[];
- Type: string[]
- Default: []
Specify individual reviewers or teams of reviewers for all pull requests raised for a package manager.
scheduleInterval
Optional
public readonly scheduleInterval: DependabotScheduleInterval;
- Type: DependabotScheduleInterval
- Default: ScheduleInterval.DAILY
How often to check for new versions and raise pull requests.
targetBranch
Optional
public readonly targetBranch: string;
- Type: string
https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#target-branch You can configure the target branch for raising pull requests for version updates against.
versioningStrategy
Optional
public readonly versioningStrategy: VersioningStrategy;
- Type: VersioningStrategy
- Default: VersioningStrategy.LOCKFILE_ONLY The default is to only update the lock file because package.json is controlled by projen and any outside updates will fail the build.
The strategy to use when edits manifest and lock files.
DependabotRegistry
Use to add private registry support for dependabot.
Initializer
import { github } from 'projen'
const dependabotRegistry: github.DependabotRegistry = { ... }
Properties
Name | Type | Description |
---|---|---|
|
| Registry type e.g. 'npm-registry' or 'docker-registry'. |
| string | Url for the registry e.g. 'https://npm.pkg.github.com' or 'registry.hub.docker.com'. |
| string | A reference to a Dependabot secret containing an access key for this registry. |
| string | Used with the hex-organization registry type. |
| string | A reference to a Dependabot secret containing the password for the specified user. |
| boolean | For registries with type: python-index, if the boolean value is true, pip esolves dependencies by using the specified URL rather than the base URL of the Python Package Index (by default https://pypi.org/simple). |
| string | Secret token for dependabot access e.g. '${{ secrets.DEPENDABOT_PACKAGE_TOKEN }}'. |
| string | The username that Dependabot uses to access the registry. |
type
Required
public readonly type: DependabotRegistryType;
- Type: DependabotRegistryType
Registry type e.g. 'npm-registry' or 'docker-registry'.
url
Required
public readonly url: string;
- Type: string
Url for the registry e.g. 'https://npm.pkg.github.com' or 'registry.hub.docker.com'.
key
Optional
public readonly key: string;
- Type: string
- Default: undefined
A reference to a Dependabot secret containing an access key for this registry.
organization
Optional
public readonly organization: string;
- Type: string
- Default: undefined
Used with the hex-organization registry type.
password
Optional
public readonly password: string;
- Type: string
- Default: undefined
A reference to a Dependabot secret containing the password for the specified user.
replacesBase
Optional
public readonly replacesBase: boolean;
- Type: boolean
- Default: undefined
For registries with type: python-index, if the boolean value is true, pip esolves dependencies by using the specified URL rather than the base URL of the Python Package Index (by default https://pypi.org/simple).
token
Optional
public readonly token: string;
- Type: string
- Default: undefined
Secret token for dependabot access e.g. '${{ secrets.DEPENDABOT_PACKAGE_TOKEN }}'.
username
Optional
public readonly username: string;
- Type: string
- Default: do not authenticate
The username that Dependabot uses to access the registry.
DownloadArtifactOptions
Initializer
import { github } from 'projen'
const downloadArtifactOptions: github.DownloadArtifactOptions = { ... }
Properties
Name | Type | Description |
---|---|---|
| {[ key: string ]: string} | Sets environment variables for steps to use in the runner environment. |
| string | A unique identifier for the step. |
| string | You can use the if conditional to prevent a job from running unless a condition is met. |
| string | A name for your step to display on GitHub. |
| string | Specifies a working directory for a step. |
| boolean | Prevents a job from failing when a step fails. |
| number | The maximum number of minutes to run the step before killing the process. |
|
| Options for download-artifact . |
env
Optional
public readonly env: {[ key: string ]: string};
- Type: {[ key: string ]: string}
Sets environment variables for steps to use in the runner environment.
You can also set environment variables for the entire workflow or a job.
id
Optional
public readonly id: string;
- Type: string
A unique identifier for the step.
You can use the id to reference the step in contexts.
if
Optional
public readonly if: string;
- Type: string
You can use the if conditional to prevent a job from running unless a condition is met.
You can use any supported context and expression to create a conditional.
name
Optional
public readonly name: string;
- Type: string
A name for your step to display on GitHub.
workingDirectory
Optional
public readonly workingDirectory: string;
- Type: string
Specifies a working directory for a step.
Overrides a job's working directory.
continueOnError
Optional
public readonly continueOnError: boolean;
- Type: boolean
Prevents a job from failing when a step fails.
Set to true to allow a job to pass when this step fails.
timeoutMinutes
Optional
public readonly timeoutMinutes: number;
- Type: number
The maximum number of minutes to run the step before killing the process.
with
Required
public readonly with: DownloadArtifactWith;
- Type: DownloadArtifactWith
Options for download-artifact
.
DownloadArtifactWith
Initializer
import { github } from 'projen'
const downloadArtifactWith: github.DownloadArtifactWith = { ... }
Properties
Name | Type | Description |
---|---|---|
| boolean | When multiple artifacts are matched, this changes the behavior of the destination directories If true, the downloaded artifacts will be in the same directory specified by path If false, the downloaded artifacts will be extracted into individual named directories within the specified path. |
| string | Name of the artifact to download. |
| string | A file, directory or wildcard pattern that describes what to download. |
| string | A glob pattern to the artifacts that should be downloaded This is ignored if name is specified. |
| string | The repository owner and the repository name joined together by "/" If github-token is specified, this is the repository that artifacts will be downloaded from. |
| string | The id of the workflow run where the desired download artifact was uploaded from If github-token is specified, this is the run that artifacts will be downloaded from. |
| string | The GitHub token used to authenticate with the GitHub API to download artifacts from a different repository or from a different workflow run. |
mergeMultiple
Optional
public readonly mergeMultiple: boolean;
- Type: boolean
- Default: false
When multiple artifacts are matched, this changes the behavior of the destination directories If true, the downloaded artifacts will be in the same directory specified by path If false, the downloaded artifacts will be extracted into individual named directories within the specified path.
name
Optional
public readonly name: string;
- Type: string
- Default: If unspecified, all artifacts for the run are downloaded
Name of the artifact to download.
path
Optional
public readonly path: string;
- Type: string
- Default: $GITHUB_WORKSPACE
A file, directory or wildcard pattern that describes what to download.
Supports basic tilde expansion.
pattern
Optional
public readonly pattern: string;
- Type: string
A glob pattern to the artifacts that should be downloaded This is ignored if name is specified.
repository
Optional
public readonly repository: string;
- Type: string
- Default: ${{ github.repository }}
The repository owner and the repository name joined together by "/" If github-token is specified, this is the repository that artifacts will be downloaded from.
runId
Optional
public readonly runId: string;
- Type: string
- Default: ${{ github.run_id }}
The id of the workflow run where the desired download artifact was uploaded from If github-token is specified, this is the run that artifacts will be downloaded from.
token
Optional
public readonly token: string;
- Type: string
- Default: If unspecified, the action will download artifacts from the current repo and the current workflow run
The GitHub token used to authenticate with the GitHub API to download artifacts from a different repository or from a different workflow run.
GithubCredentialsAppOptions
Options for GithubCredentials.fromApp
.
Initializer
import { github } from 'projen'
const githubCredentialsAppOptions: github.GithubCredentialsAppOptions = { ... }
Properties
Name | Type | Description |
---|---|---|
| string | The secret containing the GitHub App ID. |
| string | The owner of the GitHub App installation. |
|
| The permissions granted to the token. |
| string | The secret containing the GitHub App private key. |
| string[] | List of repositories to grant access to. |
appIdSecret
Optional
public readonly appIdSecret: string;
- Type: string
- Default: "PROJEN_APP_ID"
The secret containing the GitHub App ID.
owner
Optional
public readonly owner: string;
- Type: string
- Default: if empty, defaults to the current repository owner
The owner of the GitHub App installation.
permissions
Optional
public readonly permissions: AppPermissions;
- Type: AppPermissions
- Default: all permissions granted to the app
The permissions granted to the token.
privateKeySecret
Optional
public readonly privateKeySecret: string;
- Type: string
- Default: "PROJEN_APP_PRIVATE_KEY"
The secret containing the GitHub App private key.
Escaped newlines (\n) will be automatically replaced with actual newlines.
repositories
Optional
public readonly repositories: string[];
- Type: string[]
- Default: if owner is set and repositories is empty, access will be scoped to all repositories in the provided repository owner's installation. If owner and repositories are empty, access will be scoped to only the current repository.
List of repositories to grant access to.
GithubCredentialsPersonalAccessTokenOptions
Options for GithubCredentials.fromPersonalAccessToken
.
Initializer
import { github } from 'projen'
const githubCredentialsPersonalAccessTokenOptions: github.GithubCredentialsPersonalAccessTokenOptions = { ... }
Properties
Name | Type | Description |
---|---|---|
| string | No description. |
secret
Optional
public readonly secret: string;
- Type: string
GitHubOptions
Initializer
import { github } from 'projen'
const gitHubOptions: github.GitHubOptions = { ... }
Properties
Name | Type | Description |
---|---|---|
| boolean | Download files in LFS in workflows. |
| boolean | Whether a merge queue should be used on this repository to merge pull requests. |
|
| Options for MergeQueue. |
| boolean | Whether mergify should be enabled on this repository or not. |
|
| Options for Mergify. |
|
| Choose a method of providing GitHub API access for projen workflows. |
| string | The name of a secret which includes a GitHub Personal Access Token to be used by projen workflows. |
| boolean | Add a workflow that allows backport of PRs to other branches using labels. |
|
| Options for configuring pull request backport. |
| boolean | Add a workflow that performs basic checks for pull requests, like validating that PRs follow Conventional Commits. |
|
| Options for configuring a pull request linter. |
| boolean | Enables GitHub workflows. |
downloadLfs
Optional
public readonly downloadLfs: boolean;
- Type: boolean
- Default: true if the associated project has
lfsPatterns
,false
otherwise
Download files in LFS in workflows.
mergeQueue
Optional
public readonly mergeQueue: boolean;
- Type: boolean
- Default: false
Whether a merge queue should be used on this repository to merge pull requests.
Requires additional configuration of the repositories branch protection rules.
mergeQueueOptions
Optional
public readonly mergeQueueOptions: MergeQueueOptions;
- Type: MergeQueueOptions
- Default: default options
Options for MergeQueue.
mergify
Optional
public readonly mergify: boolean;
- Type: boolean
- Default: true
Whether mergify should be enabled on this repository or not.
mergifyOptions
Optional
public readonly mergifyOptions: MergifyOptions;
- Type: MergifyOptions
- Default: default options
Options for Mergify.
projenCredentials
Optional
public readonly projenCredentials: GithubCredentials;
- Type: GithubCredentials
- Default: use a personal access token named PROJEN_GITHUB_TOKEN
Choose a method of providing GitHub API access for projen workflows.
projenTokenSecret
Optional
projenTokenSecret
- 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.
pullRequestBackport
Optional
public readonly pullRequestBackport: boolean;
- Type: boolean
- Default: false
Add a workflow that allows backport of PRs to other branches using labels.
When opening a new PR add a backport label to it, and the PR will be backported to the target branches once the PR is merged.
Should not be used together with mergify.
pullRequestBackportOptions
Optional
public readonly pullRequestBackportOptions: PullRequestBackportOptions;
- Type: PullRequestBackportOptions
- Default: see defaults in
PullRequestBackportOptions
Options for configuring pull request backport.
pullRequestLint
Optional
public readonly pullRequestLint: boolean;
- Type: boolean
- Default: true
Add a workflow that performs basic checks for pull requests, like validating that PRs follow Conventional Commits.
pullRequestLintOptions
Optional
public readonly pullRequestLintOptions: PullRequestLintOptions;
- Type: PullRequestLintOptions
- Default: see defaults in
PullRequestLintOptions
Options for configuring a pull request linter.
workflows
Optional
public readonly workflows: boolean;
- Type: boolean
- Default: true
Enables GitHub workflows.
If this is set to false
, workflows will not be created.
GitHubProjectOptions
Options for GitHubProject
.
Initializer
import { github } from 'projen'
const gitHubProjectOptions: github.GitHubProjectOptions = { ... }
Properties
Name | Type | Description |
---|---|---|
| string | This is the name of your project. |
| boolean | Whether to commit the managed files by default. |
| projen.IgnoreFileOptions | Configuration options for .gitignore file. |
| projen.GitOptions | Configuration options for git. |
| projen.LoggerOptions | Configure logging options such as verbosity. |
| string | The root directory of the project. |
| projen.Project | The parent project, if this project is part of a bigger project. |
| string | The shell command to use in order to run the projen CLI. |
| boolean | Generate (once) .projenrc.json (in JSON). Set to false in order to disable .projenrc.json generation. |
| projen.ProjenrcJsonOptions | Options for .projenrc.json. |
| boolean | Use renovatebot to handle dependency upgrades. |
| projen.RenovatebotOptions | Options for renovatebot. |
|
| Enable and configure the 'auto approve' workflow. |
| boolean | Enable automatic merging on GitHub. |
|
| Configure options for automatic merging on GitHub. |
| boolean | Add a clobber task which resets the repo to origin. |
| boolean | Add a VSCode development environment (used for GitHub Codespaces). |
| boolean | Enable GitHub integration. |
|
| Options for GitHub integration. |
| boolean | Add a Gitpod development environment. |
| boolean | Whether mergify should be enabled on this repository or not. |
|
| Options for mergify. |
| projen.ProjectType | Which type of project this is (library/app). |
|
| Choose a method of providing GitHub API access for projen workflows. |
| string | The name of a secret which includes a GitHub Personal Access Token to be used by projen workflows. |
| projen.SampleReadmeProps | The README setup. |
| boolean | Auto-close of stale issues and pull request. |
|
| Auto-close stale issues and pull requests. |
| boolean | Enable VSCode integration. |
name
Required
public readonly name: string;
- Type: string
- Default: $BASEDIR
This is the name of your project.
commitGenerated
Optional
public readonly commitGenerated: boolean;
- Type: boolean
- Default: true
Whether to commit the managed files by default.
gitIgnoreOptions
Optional
public readonly gitIgnoreOptions: IgnoreFileOptions;
- Type: projen.IgnoreFileOptions
Configuration options for .gitignore file.
gitOptions
Optional
public readonly gitOptions: GitOptions;
- Type: projen.GitOptions
Configuration options for git.
logging
Optional
public readonly logging: LoggerOptions;
- Type: projen.LoggerOptions
- Default: {}
Configure logging options such as verbosity.
outdir
Optional
public readonly outdir: string;
- Type: string
- Default: "."
The root directory of the project.
Relative to this directory, all files are synthesized.
If this project has a parent, this directory is relative to the parent directory and it cannot be the same as the parent or any of it's other subprojects.
parent
Optional
public readonly parent: Project;
- Type: projen.Project
The parent project, if this project is part of a bigger project.
projenCommand
Optional
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.
projenrcJson
Optional
public readonly projenrcJson: boolean;
- Type: boolean
- Default: false
Generate (once) .projenrc.json (in JSON). Set to false
in order to disable .projenrc.json generation.
projenrcJsonOptions
Optional
public readonly projenrcJsonOptions: ProjenrcJsonOptions;
- Type: projen.ProjenrcJsonOptions
- Default: default options
Options for .projenrc.json.
renovatebot
Optional
public readonly renovatebot: boolean;
- Type: boolean
- Default: false
Use renovatebot to handle dependency upgrades.
renovatebotOptions
Optional
public readonly renovatebotOptions: RenovatebotOptions;
- Type: projen.RenovatebotOptions
- Default: default options
Options for renovatebot.
autoApproveOptions
Optional
public readonly autoApproveOptions: AutoApproveOptions;
- Type: AutoApproveOptions
- Default: auto approve is disabled
Enable and configure the 'auto approve' workflow.
autoMerge
Optional
public readonly autoMerge: boolean;
- Type: boolean
- Default: true
Enable automatic merging on GitHub.
Has no effect if github.mergify
is set to false.
autoMergeOptions
Optional
public readonly autoMergeOptions: AutoMergeOptions;
- Type: AutoMergeOptions
- Default: see defaults in
AutoMergeOptions
Configure options for automatic merging on GitHub.
Has no effect if
github.mergify
or autoMerge
is set to false.
clobber
Optional
public readonly clobber: boolean;
- Type: boolean
- Default: true, but false for subprojects
Add a clobber
task which resets the repo to origin.
devContainer
Optional
public readonly devContainer: boolean;
- Type: boolean
- Default: false
Add a VSCode development environment (used for GitHub Codespaces).
github
Optional
public readonly github: boolean;
- Type: boolean
- Default: true
Enable GitHub integration.
Enabled by default for root projects. Disabled for non-root projects.
githubOptions
Optional
public readonly githubOptions: GitHubOptions;
- Type: GitHubOptions
- Default: see GitHubOptions
Options for GitHub integration.
gitpod
Optional
public readonly gitpod: boolean;
- Type: boolean
- Default: false
Add a Gitpod development environment.
mergify
Optional
mergify
- Deprecated: use
githubOptions.mergify
instead
public readonly mergify: boolean;
- Type: boolean
- Default: true
Whether mergify should be enabled on this repository or not.
mergifyOptions
Optional
mergifyOptions
- Deprecated: use
githubOptions.mergifyOptions
instead
public readonly mergifyOptions: MergifyOptions;
- Type: MergifyOptions
- Default: default options
Options for mergify.
projectType
Optional
projectType
- 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).
projenCredentials
Optional
public readonly projenCredentials: GithubCredentials;
- Type: GithubCredentials
- Default: use a personal access token named PROJEN_GITHUB_TOKEN
Choose a method of providing GitHub API access for projen workflows.
projenTokenSecret
Optional
projenTokenSecret
- 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.
readme
Optional
public readonly readme: SampleReadmeProps;
- Type: projen.SampleReadmeProps
- Default: { filename: 'README.md', contents: '# replace this' }
The README setup.
Example
"{ filename: 'readme.md', contents: '# title' }"
stale
Optional
public readonly stale: boolean;
- Type: boolean
- Default: false
Auto-close of stale issues and pull request.
See staleOptions
for options.
staleOptions
Optional
public readonly staleOptions: StaleOptions;
- Type: StaleOptions
- Default: see defaults in
StaleOptions
Auto-close stale issues and pull requests.
To disable set stale
to false
.
vscode
Optional
public readonly vscode: boolean;
- Type: boolean
- Default: true
Enable VSCode integration.
Enabled by default for root projects. Disabled for non-root projects.
GithubWorkflowOptions
Options for GithubWorkflow
.
Initializer
import { github } from 'projen'
const githubWorkflowOptions: github.GithubWorkflowOptions = { ... }
Properties
Name | Type | Description |
---|---|---|
|
| Concurrency ensures that only a single job or workflow using the same concurrency group will run at a time. |
| {[ key: string ]: string} | Additional environment variables to set for the workflow. |
| string | Set a custom file name for the workflow definition file. Must include either a .yml or .yaml file extension. |
| boolean | Force the creation of the workflow even if workflows is disabled in GitHub . |
| boolean | Enable concurrency limitations. |
concurrencyOptions
Optional
public readonly concurrencyOptions: ConcurrencyOptions;
- Type: ConcurrencyOptions
- Default: { group: ${{ github.workflow }}, cancelInProgress: false }
Concurrency ensures that only a single job or workflow using the same concurrency group will run at a time.
Currently in beta.
env
Optional
public readonly env: {[ key: string ]: string};
- Type: {[ key: string ]: string}
- Default: no additional environment variables
Additional environment variables to set for the workflow.
fileName
Optional
public readonly fileName: string;
- Type: string
- Default: a path-safe version of the workflow name plus the .yml file ending, e.g. build.yml
Set a custom file name for the workflow definition file. Must include either a .yml or .yaml file extension.
Use this option to set a file name for the workflow file, that is different than the display name.
Example
"my-workflow.yaml"
force
Optional
public readonly force: boolean;
- Type: boolean
- Default: false
Force the creation of the workflow even if workflows
is disabled in GitHub
.
limitConcurrency
Optional
public readonly limitConcurrency: boolean;
- Type: boolean
- Default: false
Enable concurrency limitations.
Use concurrencyOptions
to configure specific non default values.
GitIdentity
Represents the git identity.
Initializer
import { github } from 'projen'
const gitIdentity: github.GitIdentity = { ... }
Properties
Name | Type | Description |
---|---|---|
| string | The email address of the git user. |
| string | The name of the user. |
email
Required
public readonly email: string;
- Type: string
The email address of the git user.
name
Required
public readonly name: string;
- Type: string
The name of the user.
MergeQueueOptions
Options for 'MergeQueue'.
Initializer
import { github } from 'projen'
const mergeQueueOptions: github.MergeQueueOptions = { ... }
Properties
Name | Type | Description |
---|---|---|
| boolean | Should pull requests be queued automatically to be merged once they pass required checks. |
|
| Configure auto-queue pull requests. |
| string[] | The branches that can be merged into using MergeQueue. |
autoQueue
Optional
public readonly autoQueue: boolean;
- Type: boolean
- Default: true
Should pull requests be queued automatically to be merged once they pass required checks.
autoQueueOptions
Optional
public readonly autoQueueOptions: AutoQueueOptions;
- Type: AutoQueueOptions
- Default: see AutoQueueOptions
Configure auto-queue pull requests.
targetBranches
Optional
public readonly targetBranches: string[];
- Type: string[]
- Default: all branches
The branches that can be merged into using MergeQueue.
MergifyConditionalOperator
The Mergify conditional operators that can be used are: or
and and
.
Note: The number of nested conditions is limited to 3.
https://docs.mergify.io/conditions/#combining-conditions-with-operators
Initializer
import { github } from 'projen'
const mergifyConditionalOperator: github.MergifyConditionalOperator = { ... }
Properties
Name | Type | Description |
---|---|---|
|
| No description. |
|
| No description. |
and
Optional
public readonly and: string | MergifyConditionalOperator[];
- Type: string | MergifyConditionalOperator[]
or
Optional
public readonly or: string | MergifyConditionalOperator[];
- Type: string | MergifyConditionalOperator[]
MergifyOptions
Initializer
import { github } from 'projen'
const mergifyOptions: github.MergifyOptions = { ... }
Properties
Name | Type | Description |
---|---|---|
|
| No description. |
|
| No description. |
queues
Optional
public readonly queues: MergifyQueue[];
- Type: MergifyQueue[]
rules
Optional
public readonly rules: MergifyRule[];
- Type: MergifyRule[]
MergifyQueue
Initializer
import { github } from 'projen'
const mergifyQueue: github.MergifyQueue = { ... }
Properties
Name | Type | Description |
---|---|---|
| string | Template to use as the commit message when using the merge or squash merge method. |
|
| A list of Conditions string that must match against the pull request for the pull request to be added to the queue. |
| string | The name of the queue. |
| string | Merge method to use. |
| string | Method to use to update the pull request with its base branch when the speculative check is done in-place. |
commitMessageTemplate
Required
public readonly commitMessageTemplate: string;
- Type: string
Template to use as the commit message when using the merge or squash merge method.
conditions
Required
public readonly conditions: string | MergifyConditionalOperator[];
- Type: string | MergifyConditionalOperator[]
A list of Conditions string that must match against the pull request for the pull request to be added to the queue.
name
Required
public readonly name: string;
- Type: string
The name of the queue.
mergeMethod
Optional
public readonly mergeMethod: string;
- Type: string
- Default: "merge"
Merge method to use.
Possible values are merge
, squash
, rebase
or fast-forward
.
fast-forward
is not supported on queues with speculative_checks
> 1, batch_size
> 1, or with allow_inplace_checks
set to false.
updateMethod
Optional
public readonly updateMethod: string;
- Type: string
- Default:
merge
for all merge methods exceptfast-forward
whererebase
is used
Method to use to update the pull request with its base branch when the speculative check is done in-place.
Possible values:
merge
to merge the base branch into the pull request.rebase
to rebase the pull request against its base branch.
Note that the rebase
method has some drawbacks, see Mergify docs for details.
MergifyRule
Initializer
import { github } from 'projen'
const mergifyRule: github.MergifyRule = { ... }
Properties
Name | Type | Description |
---|---|---|
| {[ key: string ]: any} | A dictionary made of Actions that will be executed on the matching pull requests. |
|
| A list of Conditions string that must match against the pull request for the rule to be applied. |
| string | The name of the rule. |
actions
Required
public readonly actions: {[ key: string ]: any};
- Type: {[ key: string ]: any}
A dictionary made of Actions that will be executed on the matching pull requests.
conditions
Required
public readonly conditions: string | MergifyConditionalOperator[];
- Type: string | MergifyConditionalOperator[]
A list of Conditions string that must match against the pull request for the rule to be applied.
name
Required
public readonly name: string;
- Type: string
The name of the rule.
This is not used by the engine directly, but is used when reporting information about a rule.
PullRequestBackportOptions
Initializer
import { github } from 'projen'
const pullRequestBackportOptions: github.PullRequestBackportOptions = { ... }
Properties
Name | Type | Description |
---|---|---|
| boolean | Automatically approve backport PRs if the 'auto approve' workflow is available. |
| string | The prefix used to name backport branches. |
| string[] | The labels added to the created backport PR. |
| string[] | List of branches that can be a target for backports. |
| boolean | Should this created Backport PRs with conflicts. |
| string | The prefix used to detect PRs that should be backported. |
| string | The name of the workflow. |
autoApproveBackport
Optional
public readonly autoApproveBackport: boolean;
- Type: boolean
- Default: true
Automatically approve backport PRs if the 'auto approve' workflow is available.
backportBranchNamePrefix
Optional
public readonly backportBranchNamePrefix: string;
- Type: string
- Default: "backport/"
The prefix used to name backport branches.
Make sure to include a separator at the end like /
or _
.
backportPRLabels
Optional
public readonly backportPRLabels: string[];
- Type: string[]
- Default: ["backport"]
The labels added to the created backport PR.
branches
Optional
public readonly branches: string[];
- Type: string[]
- Default: allow backports to all release branches
List of branches that can be a target for backports.
createWithConflicts
Optional
public readonly createWithConflicts: boolean;
- Type: boolean
- Default: true
Should this created Backport PRs with conflicts.
Conflicts will have to be resolved manually, but a PR is always created.
Set to false
to prevent the backport PR from being created if there are conflicts.
labelPrefix
Optional
public readonly labelPrefix: string;
- Type: string
- Default: "backport-to-"
The prefix used to detect PRs that should be backported.
workflowName
Optional
public readonly workflowName: string;
- Type: string
- Default: "backport"
The name of the workflow.
PullRequestFromPatchOptions
Initializer
import { github } from 'projen'
const pullRequestFromPatchOptions: github.PullRequestFromPatchOptions = { ... }
Properties
Name | Type | Description |
---|---|---|
| string | Description added to the pull request. |
| string | The full title used to create the pull request. |
| string | The name of the workflow that will create the PR. |
| string[] | Assignees to add on the PR. |
| string | Sets the pull request base branch. |
| string | The pull request branch name. |
|
| The job credentials used to create the pull request. |
|
| The git identity used to create the commit. |
| string[] | Labels to apply on the PR. |
| boolean | Add Signed-off-by line by the committer at the end of the commit log message. |
| string | The step ID which produces the output which indicates if a patch was created. |
| string | The name of the step displayed on GitHub. |
|
| Information about the patch that is used to create the pull request. |
| string | The name of the job displayed on GitHub. |
| string[] | Github Runner selection labels. |
| projen.GroupRunnerOptions | Github Runner Group selection options. |
pullRequestDescription
Required
public readonly pullRequestDescription: string;
- Type: string
Description added to the pull request.
Providence information are automatically added.
pullRequestTitle
Required
public readonly pullRequestTitle: string;
- Type: string
The full title used to create the pull request.
If PR titles are validated in this repo, the title should comply with the respective rules.
workflowName
Required
public readonly workflowName: string;
- Type: string
The name of the workflow that will create the PR.
assignees
Optional
public readonly assignees: string[];
- Type: string[]
- Default: no assignees
Assignees to add on the PR.
baseBranch
Optional
public readonly baseBranch: string;
- Type: string
- Default: The branch checked out in the workflow.
Sets the pull request base branch.
branchName
Optional
public readonly branchName: string;
- Type: string
- Default:
github-actions/${options.workflowName}
The pull request branch name.
credentials
Optional
public readonly credentials: GithubCredentials;
- Type: GithubCredentials
The job credentials used to create the pull request.
Provided credentials must have permissions to create a pull request on the repository.
gitIdentity
Optional
public readonly gitIdentity: GitIdentity;
- Type: GitIdentity
- Default: the default github-actions user
The git identity used to create the commit.
labels
Optional
public readonly labels: string[];
- Type: string[]
- Default: no labels.
Labels to apply on the PR.
signoff
Optional
public readonly signoff: boolean;
- Type: boolean
- Default: true
Add Signed-off-by line by the committer at the end of the commit log message.
stepId
Optional
public readonly stepId: string;
- Type: string
- Default: "create_pr"
The step ID which produces the output which indicates if a patch was created.
stepName
Optional
public readonly stepName: string;
- Type: string
- Default: "Create Pull Request"
The name of the step displayed on GitHub.
patch
Required
public readonly patch: PullRequestPatchSource;
- Type: PullRequestPatchSource
Information about the patch that is used to create the pull request.
jobName
Optional
public readonly jobName: string;
- Type: string
- Default: "Create Pull Request"
The name of the job displayed on GitHub.
runsOn
Optional
public readonly runsOn: string[];
- Type: string[]
- Default: ["ubuntu-latest"]
Github Runner selection labels.
runsOnGroup
Optional
public readonly runsOnGroup: GroupRunnerOptions;
- Type: projen.GroupRunnerOptions
Github Runner Group selection options.
PullRequestLintOptions
Options for PullRequestLint.
Initializer
import { github } from 'projen'
const pullRequestLintOptions: github.PullRequestLintOptions = { ... }
Properties
Name | Type | Description |
---|---|---|
| string | Require a contributor statement to be included in the PR description. |
|
| Options for requiring a contributor statement on Pull Requests. |
| string[] | Github Runner selection labels. |
| projen.GroupRunnerOptions | Github Runner Group selection options. |
| boolean | Validate that pull request titles follow Conventional Commits. |
|
| Options for validating the conventional commit title linter. |
contributorStatement
Optional
public readonly contributorStatement: string;
- Type: string
- Default: no contributor statement is required
Require a contributor statement to be included in the PR description.
For example confirming that the contribution has been made by the contributor and complies with the project's license.
Appends the statement to the end of the Pull Request template.
contributorStatementOptions
Optional
public readonly contributorStatementOptions: ContributorStatementOptions;
- Type: ContributorStatementOptions
- Default: none
Options for requiring a contributor statement on Pull Requests.
runsOn
Optional
public readonly runsOn: string[];
- Type: string[]
- Default: ["ubuntu-latest"]
Github Runner selection labels.
runsOnGroup
Optional
public readonly runsOnGroup: GroupRunnerOptions;
- Type: projen.GroupRunnerOptions
Github Runner Group selection options.
semanticTitle
Optional
public readonly semanticTitle: boolean;
- Type: boolean
- Default: true
Validate that pull request titles follow Conventional Commits.
semanticTitleOptions
Optional
public readonly semanticTitleOptions: SemanticTitleOptions;
- Type: SemanticTitleOptions
- Default: title must start with "feat", "fix", or "chore"
Options for validating the conventional commit title linter.
PullRequestPatchSource
Initializer
import { github } from 'projen'
const pullRequestPatchSource: github.PullRequestPatchSource = { ... }
Properties
Name | Type | Description |
---|---|---|
| number | Number of commits to fetch. |
| boolean | Whether LFS is enabled for the GitHub repository. |
| string | Relative path under $GITHUB_WORKSPACE to place the repository. |
| string | Branch or tag name. |
| string | The repository (owner/repo) to use. |
| string | A GitHub token to use when checking out the repository. |
| string | The name of the artifact the patch is stored as. |
| string | The id of the job that created the patch file. |
| string | The name of the output that indicates if a patch has been created. |
fetchDepth
Optional
public readonly fetchDepth: number;
- Type: number
- Default: 1
Number of commits to fetch.
0 indicates all history for all branches and tags.
lfs
Optional
public readonly lfs: boolean;
- Type: boolean
- Default: false
Whether LFS is enabled for the GitHub repository.
path
Optional
public readonly path: string;
- Type: string
- Default: $GITHUB_WORKSPACE
Relative path under $GITHUB_WORKSPACE to place the repository.
ref
Optional
public readonly ref: string;
- Type: string
- Default: the default branch is implicitly used
Branch or tag name.
repository
Optional
public readonly repository: string;
- Type: string
- Default: the default repository is implicitly used
The repository (owner/repo) to use.
token
Optional
public readonly token: string;
- Type: string
- Default: the default GITHUB_TOKEN is implicitly used
A GitHub token to use when checking out the repository.
If the intent is to push changes back to the branch, then you must use a
PAT with repo
(and possibly workflows
) permissions.
patchFile
Optional
public readonly patchFile: string;
- Type: string
- Default: ".repo.patch"
The name of the artifact the patch is stored as.
jobId
Required
public readonly jobId: string;
- Type: string
The id of the job that created the patch file.
outputName
Required
public readonly outputName: string;
- Type: string
The name of the output that indicates if a patch has been created.
PullRequestTemplateOptions
Options for PullRequestTemplate
.
Initializer
import { github } from 'projen'
const pullRequestTemplateOptions: github.PullRequestTemplateOptions = { ... }
Properties
Name | Type | Description |
---|---|---|
| string[] | The contents of the template. |
lines
Optional
public readonly lines: string[];
- Type: string[]
- Default: a standard default template will be created.
The contents of the template.
You can use addLine()
to add additional lines.
SemanticTitleOptions
Options for linting that PR titles follow Conventional Commits.
Initializer
import { github } from 'projen'
const semanticTitleOptions: github.SemanticTitleOptions = { ... }
Properties
Name | Type | Description |
---|---|---|
| boolean | Configure that a scope must always be provided. |
| string[] | Configure a list of commit types that are allowed. |
requireScope
Optional
public readonly requireScope: boolean;
- Type: boolean
- Default: false
Configure that a scope must always be provided.
e.g. feat(ui), fix(core)
types
Optional
public readonly types: string[];
- Type: string[]
- Default: ["feat", "fix", "chore"]
Configure a list of commit types that are allowed.
SetupGitIdentityOptions
Initializer
import { github } from 'projen'
const setupGitIdentityOptions: github.SetupGitIdentityOptions = { ... }
Properties
Name | Type | Description |
---|---|---|
| {[ key: string ]: string} | Sets environment variables for steps to use in the runner environment. |
| string | A unique identifier for the step. |
| string | You can use the if conditional to prevent a job from running unless a condition is met. |
| string | A name for your step to display on GitHub. |
| string | Specifies a working directory for a step. |
| boolean | Prevents a job from failing when a step fails. |
| number | The maximum number of minutes to run the step before killing the process. |
|
| The identity to use. |
env
Optional
public readonly env: {[ key: string ]: string};
- Type: {[ key: string ]: string}
Sets environment variables for steps to use in the runner environment.
You can also set environment variables for the entire workflow or a job.
id
Optional
public readonly id: string;
- Type: string
A unique identifier for the step.
You can use the id to reference the step in contexts.
if
Optional
public readonly if: string;
- Type: string
You can use the if conditional to prevent a job from running unless a condition is met.
You can use any supported context and expression to create a conditional.
name
Optional
public readonly name: string;
- Type: string
A name for your step to display on GitHub.
workingDirectory
Optional
public readonly workingDirectory: string;
- Type: string
Specifies a working directory for a step.
Overrides a job's working directory.
continueOnError
Optional
public readonly continueOnError: boolean;
- Type: boolean
Prevents a job from failing when a step fails.
Set to true to allow a job to pass when this step fails.
timeoutMinutes
Optional
public readonly timeoutMinutes: number;
- Type: number
The maximum number of minutes to run the step before killing the process.
gitIdentity
Required
public readonly gitIdentity: GitIdentity;
- Type: GitIdentity
The identity to use.
StaleBehavior
Stale behavior.
Initializer
import { github } from 'projen'
const staleBehavior: github.StaleBehavior = { ... }
Properties
Name | Type | Description |
---|---|---|
| string | The comment to add to the issue/PR when it's closed. |
| number | Days until the issue/PR is closed after it is marked as "Stale". |
| number | How many days until the issue or pull request is marked as "Stale". |
| boolean | Determines if this behavior is enabled. |
| string[] | Label which exempt an issue/PR from becoming stale. |
| string | The label to apply to the issue/PR when it becomes stale. |
| string | The comment to add to the issue/PR when it becomes stale. |
closeMessage
Optional
public readonly closeMessage: string;
- Type: string
- Default: "Closing this pull request as it hasn't seen activity for a while. Please add a comment
The comment to add to the issue/PR when it's closed.
daysBeforeClose
Optional
public readonly daysBeforeClose: number;
- Type: number
- Default:
Days until the issue/PR is closed after it is marked as "Stale".
Set to -1 to disable.
daysBeforeStale
Optional
public readonly daysBeforeStale: number;
- Type: number
- Default:
How many days until the issue or pull request is marked as "Stale".
Set to -1 to disable.
enabled
Optional
public readonly enabled: boolean;
- Type: boolean
- Default: true
Determines if this behavior is enabled.
Same as setting daysBeforeStale
and daysBeforeClose
to -1
.
exemptLabels
Optional
public readonly exemptLabels: string[];
- Type: string[]
- Default: ["backlog"]
Label which exempt an issue/PR from becoming stale.
Set to []
to disable.
staleLabel
Optional
public readonly staleLabel: string;
- Type: string
- Default: "stale"
The label to apply to the issue/PR when it becomes stale.
staleMessage
Optional
public readonly staleMessage: string;
- Type: string
- Default: "This pull request is now marked as stale because hasn't seen activity for a while. Add a comment or it will be closed soon."
The comment to add to the issue/PR when it becomes stale.
StaleOptions
Options for Stale
.
Initializer
import { github } from 'projen'
const staleOptions: github.StaleOptions = { ... }
Properties
Name | Type | Description |
---|---|---|
|
| How to handle stale issues. |
|
| How to handle stale pull requests. |
| string[] | Github Runner selection labels. |
| projen.GroupRunnerOptions | Github Runner Group selection options. |
issues
Optional
public readonly issues: StaleBehavior;
- Type: StaleBehavior
- Default: By default, stale issues with no activity will be marked as stale after 60 days and closed within 7 days.
How to handle stale issues.
pullRequest
Optional
public readonly pullRequest: StaleBehavior;
- Type: StaleBehavior
- Default: By default, pull requests with no activity will be marked as stale after 14 days and closed within 2 days with relevant comments.
How to handle stale pull requests.
runsOn
Optional
public readonly runsOn: string[];
- Type: string[]
- Default: ["ubuntu-latest"]
Github Runner selection labels.
runsOnGroup
Optional
public readonly runsOnGroup: GroupRunnerOptions;
- Type: projen.GroupRunnerOptions
Github Runner Group selection options.
TaskWorkflowJobOptions
Options to create the Job associated with a TaskWorkflow.
Initializer
import { github } from 'projen'
const taskWorkflowJobOptions: github.TaskWorkflowJobOptions = { ... }
Properties
Name | Type | Description |
---|---|---|
|
| Permissions for the build job. |
| string | A directory name which contains artifacts to be uploaded (e.g. dist ). If this is set, the contents of this directory will be uploaded as an artifact at the end of the workflow run, even if other steps fail. |
|
| Override for the with property of the source code checkout step. |
| string | Adds an 'if' condition to the workflow. |
|
| No description. |
| boolean | Whether to download files from Git LFS for this workflow. |
| {[ key: string ]: string} | Workflow environment variables. |
|
| The git identity to use in this workflow. |
|
| Default settings for all steps in the TaskWorkflow Job. |
|
| Mapping of job output names to values/expressions. |
|
| Actions to run after the main build step. |
|
| Steps to run before the main build step. |
|
| Initial steps to run before the source code checkout. |
| string[] | Github Runner selection labels. |
| projen.GroupRunnerOptions | Github Runner Group selection options. |
permissions
Required
public readonly permissions: JobPermissions;
- Type: JobPermissions
Permissions for the build job.
artifactsDirectory
Optional
public readonly artifactsDirectory: string;
- Type: string
- Default: not set
A directory name which contains artifacts to be uploaded (e.g. dist
). If this is set, the contents of this directory will be uploaded as an artifact at the end of the workflow run, even if other steps fail.
checkoutWith
Optional
public readonly checkoutWith: CheckoutWith;
- Type: CheckoutWith
- Default: not set
Override for the with
property of the source code checkout step.
condition
Optional
public readonly condition: string;
- Type: string
Adds an 'if' condition to the workflow.
container
Optional
public readonly container: ContainerOptions;
- Type: ContainerOptions
- Default: default image
downloadLfs
Optional
public readonly downloadLfs: boolean;
- Type: boolean
- Default: Use the setting on the corresponding GitHub project
Whether to download files from Git LFS for this workflow.
env
Optional
public readonly env: {[ key: string ]: string};
- Type: {[ key: string ]: string}
- Default: {}
Workflow environment variables.
gitIdentity
Optional
public readonly gitIdentity: GitIdentity;
- Type: GitIdentity
The git identity to use in this workflow.
jobDefaults
Optional
public readonly jobDefaults: JobDefaults;
- Type: JobDefaults
Default settings for all steps in the TaskWorkflow Job.
outputs
Optional
public readonly outputs: {[ key: string ]: JobStepOutput};
- Type: {[ key: string ]: JobStepOutput}
- Default: {}
Mapping of job output names to values/expressions.
postBuildSteps
Optional
public readonly postBuildSteps: JobStep[];
- Type: JobStep[]
- Default: not set
Actions to run after the main build step.
preBuildSteps
Optional
public readonly preBuildSteps: JobStep[];
- Type: JobStep[]
- Default: not set
Steps to run before the main build step.
preCheckoutSteps
Optional
public readonly preCheckoutSteps: JobStep[];
- Type: JobStep[]
- Default: not set
Initial steps to run before the source code checkout.
runsOn
Optional
public readonly runsOn: string[];
- Type: string[]
- Default: ["ubuntu-latest"]
Github Runner selection labels.
runsOnGroup
Optional
public readonly runsOnGroup: GroupRunnerOptions;
- Type: projen.GroupRunnerOptions
Github Runner Group selection options.
TaskWorkflowOptions
Options to create a TaskWorkflow.
Initializer
import { github } from 'projen'
const taskWorkflowOptions: github.TaskWorkflowOptions = { ... }
Properties
Name | Type | Description |
---|---|---|
|
| Permissions for the build job. |
| string | A directory name which contains artifacts to be uploaded (e.g. dist ). If this is set, the contents of this directory will be uploaded as an artifact at the end of the workflow run, even if other steps fail. |
|
| Override for the with property of the source code checkout step. |
| string | Adds an 'if' condition to the workflow. |
|
| No description. |
| boolean | Whether to download files from Git LFS for this workflow. |
| {[ key: string ]: string} | Workflow environment variables. |
|
| The git identity to use in this workflow. |
|
| Default settings for all steps in the TaskWorkflow Job. |
|
| Mapping of job output names to values/expressions. |
|
| Actions to run after the main build step. |
|
| Steps to run before the main build step. |
|
| Initial steps to run before the source code checkout. |
| string[] | Github Runner selection labels. |
| projen.GroupRunnerOptions | Github Runner Group selection options. |
| string | The workflow name. |
| projen.Task | The main task to be executed. |
| string | The primary job id. |
|
| The triggers for the workflow. |
permissions
Required
public readonly permissions: JobPermissions;
- Type: JobPermissions
Permissions for the build job.
artifactsDirectory
Optional
public readonly artifactsDirectory: string;
- Type: string
- Default: not set
A directory name which contains artifacts to be uploaded (e.g. dist
). If this is set, the contents of this directory will be uploaded as an artifact at the end of the workflow run, even if other steps fail.
checkoutWith
Optional
public readonly checkoutWith: CheckoutWith;
- Type: CheckoutWith
- Default: not set
Override for the with
property of the source code checkout step.
condition
Optional
public readonly condition: string;
- Type: string
Adds an 'if' condition to the workflow.
container
Optional
public readonly container: ContainerOptions;
- Type: ContainerOptions
- Default: default image
downloadLfs
Optional
public readonly downloadLfs: boolean;
- Type: boolean
- Default: Use the setting on the corresponding GitHub project
Whether to download files from Git LFS for this workflow.
env
Optional
public readonly env: {[ key: string ]: string};
- Type: {[ key: string ]: string}
- Default: {}
Workflow environment variables.
gitIdentity
Optional
public readonly gitIdentity: GitIdentity;
- Type: GitIdentity
The git identity to use in this workflow.
jobDefaults
Optional
public readonly jobDefaults: JobDefaults;
- Type: JobDefaults
Default settings for all steps in the TaskWorkflow Job.
outputs
Optional
public readonly outputs: {[ key: string ]: JobStepOutput};
- Type: {[ key: string ]: JobStepOutput}
- Default: {}
Mapping of job output names to values/expressions.
postBuildSteps
Optional
public readonly postBuildSteps: JobStep[];
- Type: JobStep[]
- Default: not set
Actions to run after the main build step.
preBuildSteps
Optional
public readonly preBuildSteps: JobStep[];
- Type: JobStep[]
- Default: not set
Steps to run before the main build step.
preCheckoutSteps
Optional
public readonly preCheckoutSteps: JobStep[];
- Type: JobStep[]
- Default: not set
Initial steps to run before the source code checkout.
runsOn
Optional
public readonly runsOn: string[];
- Type: string[]
- Default: ["ubuntu-latest"]
Github Runner selection labels.
runsOnGroup
Optional
public readonly runsOnGroup: GroupRunnerOptions;
- Type: projen.GroupRunnerOptions
Github Runner Group selection options.
name
Required
public readonly name: string;
- Type: string
The workflow name.
task
Required
public readonly task: Task;
- Type: projen.Task
The main task to be executed.
jobId
Optional
public readonly jobId: string;
- Type: string
- Default: "build"
The primary job id.
triggers
Optional
public readonly triggers: Triggers;
- Type: Triggers
- Default: by default workflows can only be triggered by manually.
The triggers for the workflow.
UploadArtifactOptions
Initializer
import { github } from 'projen'
const uploadArtifactOptions: github.UploadArtifactOptions = { ... }
Properties
Name | Type | Description |
---|---|---|
| {[ key: string ]: string} | Sets environment variables for steps to use in the runner environment. |
| string | A unique identifier for the step. |
| string | You can use the if conditional to prevent a job from running unless a condition is met. |
| string | A name for your step to display on GitHub. |
| string | Specifies a working directory for a step. |
| boolean | Prevents a job from failing when a step fails. |
| number | The maximum number of minutes to run the step before killing the process. |
|
| Options for upload-artifact . |
env
Optional
public readonly env: {[ key: string ]: string};
- Type: {[ key: string ]: string}
Sets environment variables for steps to use in the runner environment.
You can also set environment variables for the entire workflow or a job.
id
Optional
public readonly id: string;
- Type: string
A unique identifier for the step.
You can use the id to reference the step in contexts.
if
Optional
public readonly if: string;
- Type: string
You can use the if conditional to prevent a job from running unless a condition is met.
You can use any supported context and expression to create a conditional.
name
Optional
public readonly name: string;
- Type: string
A name for your step to display on GitHub.
workingDirectory
Optional
public readonly workingDirectory: string;
- Type: string
Specifies a working directory for a step.
Overrides a job's working directory.
continueOnError
Optional
public readonly continueOnError: boolean;
- Type: boolean
Prevents a job from failing when a step fails.
Set to true to allow a job to pass when this step fails.
timeoutMinutes
Optional
public readonly timeoutMinutes: number;
- Type: number
The maximum number of minutes to run the step before killing the process.
with
Required
public readonly with: UploadArtifactWith;
- Type: UploadArtifactWith
Options for upload-artifact
.
UploadArtifactWith
Initializer
import { github } from 'projen'
const uploadArtifactWith: github.UploadArtifactWith = { ... }
Properties
Name | Type | Description |
---|---|---|
| string | A file, directory or wildcard pattern that describes what to upload. |
| number | The level of compression for Zlib to be applied to the artifact archive. |
| string | The desired behavior if no files are found using the provided path. |
| boolean | Whether to include hidden files in the provided path in the artifact. |
| string | Name of the artifact to upload. |
| boolean | Whether action should overwrite an existing artifact with the same name (should one exist). |
| number | Duration after which artifact will expire in days. 0 means using default repository retention. |
path
Required
public readonly path: string;
- Type: string
A file, directory or wildcard pattern that describes what to upload.
compressionLevel
Optional
public readonly compressionLevel: number;
- Type: number
- Default: 6
The level of compression for Zlib to be applied to the artifact archive.
The value can range from 0 to 9. For large files that are not easily compressed, a value of 0 is recommended for significantly faster uploads.
ifNoFilesFound
Optional
public readonly ifNoFilesFound: string;
- Type: string
- Default: "warn"
The desired behavior if no files are found using the provided path.
Available Options: warn: Output a warning but do not fail the action error: Fail the action with an error message ignore: Do not output any warnings or errors, the action does not fail
includeHiddenFiles
Optional
public readonly includeHiddenFiles: boolean;
- Type: boolean
- Default: false
Whether to include hidden files in the provided path in the artifact.
The file contents of any hidden files in the path should be validated before enabled this to avoid uploading sensitive information.
name
Optional
public readonly name: string;
- Type: string
- Default: "artifact"
Name of the artifact to upload.
overwrite
Optional
public readonly overwrite: boolean;
- Type: boolean
- Default: true
Whether action should overwrite an existing artifact with the same name (should one exist).
Introduced in v4 and represents a breaking change from the behavior of the v3 action.
To maintain backwards compatibility with existing, this should be set the true
(the default).
retentionDays
Optional
public readonly retentionDays: number;
- Type: number
- Default: The default repository retention
Duration after which artifact will expire in days. 0 means using default repository retention.
Minimum 1 day. Maximum 90 days unless changed from the repository settings page.
UploadGitPatchOptions
Options for uploadGitPatch
.
Initializer
import { github } from 'projen'
const uploadGitPatchOptions: github.UploadGitPatchOptions = { ... }
Properties
Name | Type | Description |
---|---|---|
| string | The name of the output to emit. |
| string | The step ID which produces the output which indicates if a patch was created. |
| string | Fail if a mutation was found and print this error message. |
| string | The name of the artifact the patch is stored as. |
| string | The name of the step. |
outputName
Required
public readonly outputName: string;
- Type: string
The name of the output to emit.
It will be set to true
if there was a diff.
stepId
Required
public readonly stepId: string;
- Type: string
The step ID which produces the output which indicates if a patch was created.
mutationError
Optional
public readonly mutationError: string;
- Type: string
- Default: do not fail upon mutation
Fail if a mutation was found and print this error message.
patchFile
Optional
public readonly patchFile: string;
- Type: string
- Default: ".repo.patch"
The name of the artifact the patch is stored as.
stepName
Optional
public readonly stepName: string;
- Type: string
- Default: "Find mutations"
The name of the step.
Classes
GitHubActionsProvider
Manage the versions used for GitHub Actions used in steps.
Initializers
import { github } from 'projen'
new github.GitHubActionsProvider()
Name | Type | Description |
---|
Methods
Name | Description |
---|---|
| Resolve an action name to the version that should be used, taking into account any overrides. |
| Define an override for a given action. |
get
public get(action: string): string
Resolve an action name to the version that should be used, taking into account any overrides.
action
Required
- Type: string
set
public set(action: string, override: string): void
Define an override for a given action.
Specify the action name without a version to override all usages of the action. You can also override a specific action version, by providing the version string. Specific overrides take precedence over overrides without a version.
If an override for the same action name is set multiple times, the last override is used.
Example
// Force any use of `actions/checkout` to use a pin a specific commit
project.github.actions.set("actions/checkout", "actions/checkout@aaaaaa");
// But pin usage of `v4` to a different commit
project.github.actions.set("actions/checkout@v4", "actions/checkout@ffffff");
action
Required
- Type: string
override
Required
- Type: string
GithubCredentials
Represents a method of providing GitHub API access for projen workflows.
Static Functions
Name | Description |
---|---|
| Provide API access through a GitHub App. |
| Provide API access through a GitHub personal access token. |
fromApp
import { github } from 'projen'
github.GithubCredentials.fromApp(options?: GithubCredentialsAppOptions)
Provide API access through a GitHub App.
The GitHub App must be installed on the GitHub repo, its App ID and a private key must be added as secrets to the repo. The name of the secrets can be specified here.
options
Optional
fromPersonalAccessToken
import { github } from 'projen'
github.GithubCredentials.fromPersonalAccessToken(options?: GithubCredentialsPersonalAccessTokenOptions)
Provide API access through a GitHub personal access token.
The token must be added as a secret to the GitHub repo, and the name of the secret can be specified here.
options
Optional
Properties
Name | Type | Description |
---|---|---|
|
| Setup steps to obtain GitHub credentials. |
| string | The value to use in a workflow when a GitHub token is expected. |
setupSteps
Required
public readonly setupSteps: JobStep[];
- Type: JobStep[]
Setup steps to obtain GitHub credentials.
tokenRef
Required
public readonly tokenRef: string;
- Type: string
The value to use in a workflow when a GitHub token is expected.
This typically looks like "${{ some.path.to.a.value }}".
WorkflowActions
A set of utility functions for creating GitHub actions in workflows.
Initializers
import { github } from 'projen'
new github.WorkflowActions()
Name | Type | Description |
---|
Static Functions
Name | Description |
---|---|
| Checks out a repository and applies a git patch that was created using uploadGitPatch . |
| A step that creates a pull request based on the current repo state. |
| Configures the git identity (user name and email). |
| Creates a .patch file from the current git diff and uploads it as an artifact. Use checkoutWithPatch to download and apply in another job. |
checkoutWithPatch
import { github } from 'projen'
github.WorkflowActions.checkoutWithPatch(options?: CheckoutWithPatchOptions)
Checks out a repository and applies a git patch that was created using uploadGitPatch
.
options
Optional
- Type: CheckoutWithPatchOptions
Options.
createPullRequest
import { github } from 'projen'
github.WorkflowActions.createPullRequest(options: CreatePullRequestOptions)
A step that creates a pull request based on the current repo state.
options
Required
- Type: CreatePullRequestOptions
Options.
setupGitIdentity
setupGitIdentity
import { github } from 'projen'
github.WorkflowActions.setupGitIdentity(id: GitIdentity)
Configures the git identity (user name and email).
id
Required
- Type: GitIdentity
The identity to use.
uploadGitPatch
import { github } from 'projen'
github.WorkflowActions.uploadGitPatch(options: UploadGitPatchOptions)
Creates a .patch file from the current git diff and uploads it as an artifact. Use checkoutWithPatch
to download and apply in another job.
If a patch was uploaded, the action can optionally fail the job.
options
Required
- Type: UploadGitPatchOptions
Options.
WorkflowJobs
A set of utility functions for creating jobs in GitHub Workflows.
Initializers
import { github } from 'projen'
new github.WorkflowJobs()
Name | Type | Description |
---|
Static Functions
Name | Description |
---|---|
| Creates a pull request with the changes of a patch file. |
pullRequestFromPatch
import { github } from 'projen'
github.WorkflowJobs.pullRequestFromPatch(options: PullRequestFromPatchOptions)
Creates a pull request with the changes of a patch file.
options
Required
WorkflowSteps
A collection of very commonly used, individual, GitHub Workflow Job steps.
Initializers
import { github } from 'projen'
new github.WorkflowSteps()
Name | Type | Description |
---|
Static Functions
Name | Description |
---|---|
| Checks out a repository. |
| Downloads an artifact. |
| Configures the git identity (user name and email). |
| Checks if a tag exists. |
| Uploads an artifact. |
checkout
import { github } from 'projen'
github.WorkflowSteps.checkout(options?: CheckoutOptions)
Checks out a repository.
options
Optional
- Type: CheckoutOptions
Options to configure the checkout
JobStep.
downloadArtifact
import { github } from 'projen'
github.WorkflowSteps.downloadArtifact(options?: DownloadArtifactOptions)
Downloads an artifact.
options
Optional
- Type: DownloadArtifactOptions
Options to configure the download-artifact
JobStep.
setupGitIdentity
import { github } from 'projen'
github.WorkflowSteps.setupGitIdentity(options: SetupGitIdentityOptions)
Configures the git identity (user name and email).
options
Required
- Type: SetupGitIdentityOptions
Options to configure the git identity JobStep.
tagExists
import { github } from 'projen'
github.WorkflowSteps.tagExists(tag: string, options: JobStepConfiguration)
Checks if a tag exists.
Requires a checkout step to have been run before this step with "fetch-depth" set to "0".
Outputs:
exists
: A string value of 'true' or 'false' indicating if the tag exists.
tag
Required
- Type: string
The tag to check.
You may use valid bash code instead of a literal string in this field.
options
Required
- Type: JobStepConfiguration
Options to configure the tag-exists
JobStep.
uploadArtifact
import { github } from 'projen'
github.WorkflowSteps.uploadArtifact(options: UploadArtifactOptions)
Uploads an artifact.
options
Required
- Type: UploadArtifactOptions
Options to configure the upload-artifact
JobStep.
Protocols
IAddConditionsLater
- Implemented By: IAddConditionsLater
Methods
Name | Description |
---|---|
| No description. |
render
public render(): string[]
Enums
DependabotRegistryType
Each configuration type requires you to provide particular settings.
Some types allow more than one way to connect
Members
Name | Description |
---|---|
| The composer-repository type supports username and password. |
| The docker-registry type supports username and password. |
| The git type supports username and password. |
| The hex-organization type supports organization and key. |
| The maven-repository type supports username and password, or token. |
| The npm-registry type supports username and password, or token. |
| The nuget-feed type supports username and password, or token. |
| The python-index type supports username and password, or token. |
| The rubygems-server type supports username and password, or token. |
| The terraform-registry type supports a token. |
COMPOSER_REGISTRY
The composer-repository type supports username and password.
DOCKER_REGISTRY
The docker-registry type supports username and password.
The docker-registry type can also be used to pull from Amazon ECR using static AWS credentials
GIT
The git type supports username and password.
HEX_ORGANIZATION
The hex-organization type supports organization and key.
MAVEN_REPOSITORY
The maven-repository type supports username and password, or token.
NPM_REGISTRY
The npm-registry type supports username and password, or token.
NUGET_FEED
The nuget-feed type supports username and password, or token.
PYTHON_INDEX
The python-index type supports username and password, or token.
RUBYGEMS_SERVER
The rubygems-server type supports username and password, or token.
TERRAFORM_REGISTRY
The terraform-registry type supports a token.
DependabotScheduleInterval
How often to check for new versions and raise pull requests for version updates.
Members
Name | Description |
---|---|
| Runs on every weekday, Monday to Friday. |
| Runs once each week. |
| Runs once each month. |
DAILY
Runs on every weekday, Monday to Friday.
WEEKLY
Runs once each week.
By default, this is on Monday.
MONTHLY
Runs once each month.
This is on the first day of the month.
MergeMethod
The merge method used to add the PR to the merge queue.
Behavior can be further configured in repository settings.
Members
Name | Description |
---|---|
| No description. |
| No description. |
| No description. |
SQUASH
MERGE
REBASE
VersioningStrategy
The strategy to use when edits manifest and lock files.
Members
Name | Description |
---|---|
| Only create pull requests to update lockfiles updates. |
| - For apps, the version requirements are increased. |
| Relax the version requirement to include both the new and old version, when possible. |
| Always increase the version requirement to match the new version. |
| Increase the version requirement only when required by the new version. |
LOCKFILE_ONLY
Only create pull requests to update lockfiles updates.
Ignore any new versions that would require package manifest changes.
AUTO
For apps, the version requirements are increased.
For libraries, the range of versions is widened.
WIDEN
Relax the version requirement to include both the new and old version, when possible.
INCREASE
Always increase the version requirement to match the new version.
INCREASE_IF_NECESSARY
Increase the version requirement only when required by the new version.