`github.workflows` Submodule

Structs

AppPermissions

The permissions available to a GitHub App.

Typically a token for a GitHub App has all the available scopes/permissions available to the app itself; however, a more limited set of permissions can be specified. When permissions are provided, only the specified permissions are granted to the token.

https://github.com/actions/create-github-app-token/blob/main/action.yml#L28

Initializer

import { github } from 'projen'

const appPermissions: github.workflows.AppPermissions = { ... }

Properties

Name	Type	Description
`actions`	`projen.github.workflows.AppPermission`	No description.
`administration`	`projen.github.workflows.AppPermission`	No description.
`attestations`	`projen.github.workflows.AppPermission`	No description.
`checks`	`projen.github.workflows.AppPermission`	No description.
`codespaces`	`projen.github.workflows.AppPermission`	No description.
`contents`	`projen.github.workflows.AppPermission`	No description.
`dependabotSecrets`	`projen.github.workflows.AppPermission`	No description.
`deployments`	`projen.github.workflows.AppPermission`	No description.
`emailAddresses`	`projen.github.workflows.AppPermission`	No description.
`environments`	`projen.github.workflows.AppPermission`	No description.
`followers`	`projen.github.workflows.AppPermission`	No description.
`gitSshKeys`	`projen.github.workflows.AppPermission`	No description.
`gpgKeys`	`projen.github.workflows.AppPermission`	No description.
`interactionLimits`	`projen.github.workflows.AppPermission`	No description.
`issues`	`projen.github.workflows.AppPermission`	No description.
`members`	`projen.github.workflows.AppPermission`	No description.
`metadata`	`projen.github.workflows.AppPermission`	No description.
`organizationAdministration`	`projen.github.workflows.AppPermission`	No description.
`organizationAnnouncementBanners`	`projen.github.workflows.AppPermission`	No description.
`organizationCopilotSeatManagement`	`projen.github.workflows.AppPermission`	No description.
`organizationCustomOrgRoles`	`projen.github.workflows.AppPermission`	No description.
`organizationCustomProperties`	`projen.github.workflows.AppPermission`	No description.
`organizationCustomRoles`	`projen.github.workflows.AppPermission`	No description.
`organizationEvents`	`projen.github.workflows.AppPermission`	No description.
`organizationHooks`	`projen.github.workflows.AppPermission`	No description.
`organizationPackages`	`projen.github.workflows.AppPermission`	No description.
`organizationPersonalAccessTokenRequests`	`projen.github.workflows.AppPermission`	No description.
`organizationPersonalAccessTokens`	`projen.github.workflows.AppPermission`	No description.
`organizationPlan`	`projen.github.workflows.AppPermission`	No description.
`organizationProjects`	`projen.github.workflows.AppPermission`	No description.
`organizationSecrets`	`projen.github.workflows.AppPermission`	No description.
`organizationSelfHostedRunners`	`projen.github.workflows.AppPermission`	No description.
`orgnaizationUserBlocking`	`projen.github.workflows.AppPermission`	No description.
`packages`	`projen.github.workflows.AppPermission`	No description.
`pages`	`projen.github.workflows.AppPermission`	No description.
`profile`	`projen.github.workflows.AppPermission`	No description.
`pullRequests`	`projen.github.workflows.AppPermission`	No description.
`repositoryCustomProperties`	`projen.github.workflows.AppPermission`	No description.
`repositoryHooks`	`projen.github.workflows.AppPermission`	No description.
`repositoryProjects`	`projen.github.workflows.AppPermission`	No description.
`secrets`	`projen.github.workflows.AppPermission`	No description.
`secretScanningAlerts`	`projen.github.workflows.AppPermission`	No description.
`securityEvents`	`projen.github.workflows.AppPermission`	No description.
`singleFile`	`projen.github.workflows.AppPermission`	No description.
`starring`	`projen.github.workflows.AppPermission`	No description.
`statuses`	`projen.github.workflows.AppPermission`	No description.
`teamDiscussions`	`projen.github.workflows.AppPermission`	No description.
`vulnerabilityAlerts`	`projen.github.workflows.AppPermission`	No description.
`workflows`	`projen.github.workflows.AppPermission`	No description.

`actions`^Optional

public readonly actions: AppPermission;

Type: projen.github.workflows.AppPermission

`administration`^Optional

public readonly administration: AppPermission;

Type: projen.github.workflows.AppPermission

`attestations`^Optional

public readonly attestations: AppPermission;

Type: projen.github.workflows.AppPermission

`checks`^Optional

public readonly checks: AppPermission;

Type: projen.github.workflows.AppPermission

`codespaces`^Optional

public readonly codespaces: AppPermission;

Type: projen.github.workflows.AppPermission

`contents`^Optional

public readonly contents: AppPermission;

Type: projen.github.workflows.AppPermission

`dependabotSecrets`^Optional

public readonly dependabotSecrets: AppPermission;

Type: projen.github.workflows.AppPermission

`deployments`^Optional

public readonly deployments: AppPermission;

Type: projen.github.workflows.AppPermission

`emailAddresses`^Optional

public readonly emailAddresses: AppPermission;

Type: projen.github.workflows.AppPermission

`environments`^Optional

public readonly environments: AppPermission;

Type: projen.github.workflows.AppPermission

`followers`^Optional

public readonly followers: AppPermission;

Type: projen.github.workflows.AppPermission

`gitSshKeys`^Optional

public readonly gitSshKeys: AppPermission;

Type: projen.github.workflows.AppPermission

`gpgKeys`^Optional

public readonly gpgKeys: AppPermission;

Type: projen.github.workflows.AppPermission

`interactionLimits`^Optional

public readonly interactionLimits: AppPermission;

Type: projen.github.workflows.AppPermission

`issues`^Optional

public readonly issues: AppPermission;

Type: projen.github.workflows.AppPermission

`members`^Optional

public readonly members: AppPermission;

Type: projen.github.workflows.AppPermission

`metadata`^Optional

public readonly metadata: AppPermission;

Type: projen.github.workflows.AppPermission

`organizationAdministration`^Optional

public readonly organizationAdministration: AppPermission;

Type: projen.github.workflows.AppPermission

`organizationAnnouncementBanners`^Optional

public readonly organizationAnnouncementBanners: AppPermission;

Type: projen.github.workflows.AppPermission

`organizationCopilotSeatManagement`^Optional

public readonly organizationCopilotSeatManagement: AppPermission;

Type: projen.github.workflows.AppPermission

`organizationCustomOrgRoles`^Optional

public readonly organizationCustomOrgRoles: AppPermission;

Type: projen.github.workflows.AppPermission

`organizationCustomProperties`^Optional

public readonly organizationCustomProperties: AppPermission;

Type: projen.github.workflows.AppPermission

`organizationCustomRoles`^Optional

public readonly organizationCustomRoles: AppPermission;

Type: projen.github.workflows.AppPermission

`organizationEvents`^Optional

public readonly organizationEvents: AppPermission;

Type: projen.github.workflows.AppPermission

`organizationHooks`^Optional

public readonly organizationHooks: AppPermission;

Type: projen.github.workflows.AppPermission

`organizationPackages`^Optional

public readonly organizationPackages: AppPermission;

Type: projen.github.workflows.AppPermission

`organizationPersonalAccessTokenRequests`^Optional

public readonly organizationPersonalAccessTokenRequests: AppPermission;

Type: projen.github.workflows.AppPermission

`organizationPersonalAccessTokens`^Optional

public readonly organizationPersonalAccessTokens: AppPermission;

Type: projen.github.workflows.AppPermission

`organizationPlan`^Optional

public readonly organizationPlan: AppPermission;

Type: projen.github.workflows.AppPermission

`organizationProjects`^Optional

public readonly organizationProjects: AppPermission;

Type: projen.github.workflows.AppPermission

`organizationSecrets`^Optional

public readonly organizationSecrets: AppPermission;

Type: projen.github.workflows.AppPermission

`organizationSelfHostedRunners`^Optional

public readonly organizationSelfHostedRunners: AppPermission;

Type: projen.github.workflows.AppPermission

`orgnaizationUserBlocking`^Optional

public readonly orgnaizationUserBlocking: AppPermission;

Type: projen.github.workflows.AppPermission

`packages`^Optional

public readonly packages: AppPermission;

Type: projen.github.workflows.AppPermission

`pages`^Optional

public readonly pages: AppPermission;

Type: projen.github.workflows.AppPermission

`profile`^Optional

public readonly profile: AppPermission;

Type: projen.github.workflows.AppPermission

`pullRequests`^Optional

public readonly pullRequests: AppPermission;

Type: projen.github.workflows.AppPermission

`repositoryCustomProperties`^Optional

public readonly repositoryCustomProperties: AppPermission;

Type: projen.github.workflows.AppPermission

`repositoryHooks`^Optional

public readonly repositoryHooks: AppPermission;

Type: projen.github.workflows.AppPermission

`repositoryProjects`^Optional

public readonly repositoryProjects: AppPermission;

Type: projen.github.workflows.AppPermission

`secrets`^Optional

public readonly secrets: AppPermission;

Type: projen.github.workflows.AppPermission

`secretScanningAlerts`^Optional

public readonly secretScanningAlerts: AppPermission;

Type: projen.github.workflows.AppPermission

`securityEvents`^Optional

public readonly securityEvents: AppPermission;

Type: projen.github.workflows.AppPermission

`singleFile`^Optional

public readonly singleFile: AppPermission;

Type: projen.github.workflows.AppPermission

`starring`^Optional

public readonly starring: AppPermission;

Type: projen.github.workflows.AppPermission

`statuses`^Optional

public readonly statuses: AppPermission;

Type: projen.github.workflows.AppPermission

`teamDiscussions`^Optional

public readonly teamDiscussions: AppPermission;

Type: projen.github.workflows.AppPermission

`vulnerabilityAlerts`^Optional

public readonly vulnerabilityAlerts: AppPermission;

Type: projen.github.workflows.AppPermission

`workflows`^Optional

public readonly workflows: AppPermission;

Type: projen.github.workflows.AppPermission

BranchProtectionRuleOptions

Branch Protection Rule options.

Initializer

import { github } from 'projen'

const branchProtectionRuleOptions: github.workflows.BranchProtectionRuleOptions = { ... }

Properties

Name	Type	Description
`types`	`string[]`	Which activity types to trigger on.

`types`^Optional

public readonly types: string[];

Type: string[]

Which activity types to trigger on.

CheckRunOptions

Check run options.

Initializer

import { github } from 'projen'

const checkRunOptions: github.workflows.CheckRunOptions = { ... }

Properties

Name	Type	Description
`types`	`string[]`	Which activity types to trigger on.

`types`^Optional

public readonly types: string[];

Type: string[]

Which activity types to trigger on.

CheckSuiteOptions

Check suite options.

Initializer

import { github } from 'projen'

const checkSuiteOptions: github.workflows.CheckSuiteOptions = { ... }

Properties

Name	Type	Description
`types`	`string[]`	Which activity types to trigger on.

`types`^Optional

public readonly types: string[];

Type: string[]

Which activity types to trigger on.

CommonJobDefinition

Initializer

import { github } from 'projen'

const commonJobDefinition: github.workflows.CommonJobDefinition = { ... }

Properties

Name	Type	Description
`permissions`	`projen.github.workflows.JobPermissions`	You can modify the default permissions granted to the GITHUB_TOKEN, adding or removing access as required, so that you only allow the minimum required access.
`concurrency`	`any`	Concurrency ensures that only a single job or workflow using the same concurrency group will run at a time.
`if`	`string`	You can use the if conditional to prevent a job from running unless a condition is met.
`name`	`string`	The name of the job displayed on GitHub.
`needs`	`string[]`	Identifies any jobs that must complete successfully before this job will run.
`strategy`	`projen.github.workflows.JobStrategy`	A strategy creates a build matrix for your jobs.

`permissions`^Required

public readonly permissions: JobPermissions;

Type: projen.github.workflows.JobPermissions

You can modify the default permissions granted to the GITHUB_TOKEN, adding or removing access as required, so that you only allow the minimum required access.

Use { contents: READ } if your job only needs to clone code.

This is intentionally a required field since it is required in order to allow workflows to run in GitHub repositories with restricted default access.

https://docs.github.com/en/actions/reference/authentication-in-a-workflow#permissions-for-the-github_token

`concurrency`^Optional

public readonly concurrency: any;

Type: any

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

A concurrency group can be any string or expression. The expression can use any context except for the secrets context.

`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

The name of the job displayed on GitHub.

`needs`^Optional

public readonly needs: string[];

Type: string[]

Identifies any jobs that must complete successfully before this job will run.

It can be a string or array of strings. If a job fails, all jobs that need it are skipped unless the jobs use a conditional expression that causes the job to continue.

`strategy`^Optional

public readonly strategy: JobStrategy;

Type: projen.github.workflows.JobStrategy

A strategy creates a build matrix for your jobs.

You can define different variations to run each job in.

ContainerCredentials

Credentials to use to authenticate to Docker registries.

Initializer

import { github } from 'projen'

const containerCredentials: github.workflows.ContainerCredentials = { ... }

Properties

Name	Type	Description
`password`	`string`	The password.
`username`	`string`	The username.

`password`^Required

public readonly password: string;

Type: string

The password.

`username`^Required

public readonly username: string;

Type: string

The username.

ContainerOptions

Options pertaining to container environments.

Initializer

import { github } from 'projen'

const containerOptions: github.workflows.ContainerOptions = { ... }

Properties

Name	Type	Description
`image`	`string`	The Docker image to use as the container to run the action.
`credentials`	`projen.github.workflows.ContainerCredentials`	f the image's container registry requires authentication to pull the image, you can use credentials to set a map of the username and password.
`env`	`{[ key: string ]: string}`	Sets a map of environment variables in the container.
`options`	`string[]`	Additional Docker container resource options.
`ports`	`number[]`	Sets an array of ports to expose on the container.
`volumes`	`string[]`	Sets an array of volumes for the container to use.

`image`^Required

public readonly image: string;

Type: string

The Docker image to use as the container to run the action.

The value can be the Docker Hub image name or a registry name.

`credentials`^Optional

public readonly credentials: ContainerCredentials;

Type: projen.github.workflows.ContainerCredentials

f the image's container registry requires authentication to pull the image, you can use credentials to set a map of the username and password.

The credentials are the same values that you would provide to the docker login command.

`env`^Optional

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

Type: {[ key: string ]: string}

Sets a map of environment variables in the container.

`options`^Optional

public readonly options: string[];

Type: string[]

Additional Docker container resource options.

https://docs.docker.com/engine/reference/commandline/create/#options

`ports`^Optional

public readonly ports: number[];

Type: number[]

Sets an array of ports to expose on the container.

`volumes`^Optional

public readonly volumes: string[];

Type: string[]

Sets an array of volumes for the container to use.

You can use volumes to share data between services or other steps in a job. You can specify named Docker volumes, anonymous Docker volumes, or bind mounts on the host.

To specify a volume, you specify the source and destination path: <source>:<destinationPath>.

CreateOptions

The Create event accepts no options.

Initializer

import { github } from 'projen'

const createOptions: github.workflows.CreateOptions = { ... }

CronScheduleOptions

CRON schedule options.

Initializer

import { github } from 'projen'

const cronScheduleOptions: github.workflows.CronScheduleOptions = { ... }

Properties

Name	Type	Description
`cron`	`string`	No description.

`cron`^Required

public readonly cron: string;

Type: string

https://pubs.opengroup.org/onlinepubs/9699919799/utilities/crontab.html#tag_20_25_07

DeleteOptions

The Delete event accepts no options.

Initializer

import { github } from 'projen'

const deleteOptions: github.workflows.DeleteOptions = { ... }

DeploymentOptions

The Deployment event accepts no options.

Initializer

import { github } from 'projen'

const deploymentOptions: github.workflows.DeploymentOptions = { ... }

DeploymentStatusOptions

The Deployment status event accepts no options.

Initializer

import { github } from 'projen'

const deploymentStatusOptions: github.workflows.DeploymentStatusOptions = { ... }

DiscussionCommentOptions

Discussion comment options.

Initializer

import { github } from 'projen'

const discussionCommentOptions: github.workflows.DiscussionCommentOptions = { ... }

Properties

Name	Type	Description
`types`	`string[]`	Which activity types to trigger on.

`types`^Optional

public readonly types: string[];

Type: string[]

Which activity types to trigger on.

DiscussionOptions

Discussion options.

Initializer

import { github } from 'projen'

const discussionOptions: github.workflows.DiscussionOptions = { ... }

Properties

Name	Type	Description
`types`	`string[]`	Which activity types to trigger on.

`types`^Optional

public readonly types: string[];

Type: string[]

Which activity types to trigger on.

ForkOptions

The Fork event accepts no options.

Initializer

import { github } from 'projen'

const forkOptions: github.workflows.ForkOptions = { ... }

GollumOptions

The Gollum event accepts no options.

Initializer

import { github } from 'projen'

const gollumOptions: github.workflows.GollumOptions = { ... }

IssueCommentOptions

Issue comment options.

Initializer

import { github } from 'projen'

const issueCommentOptions: github.workflows.IssueCommentOptions = { ... }

Properties

Name	Type	Description
`types`	`string[]`	Which activity types to trigger on.

`types`^Optional

public readonly types: string[];

Type: string[]

Which activity types to trigger on.

IssuesOptions

Issues options.

Initializer

import { github } from 'projen'

const issuesOptions: github.workflows.IssuesOptions = { ... }

Properties

Name	Type	Description
`types`	`string[]`	Which activity types to trigger on.

`types`^Optional

public readonly types: string[];

Type: string[]

Which activity types to trigger on.

JavaToolRequirement

Version requirement for Java tools.

Initializer

import { github } from 'projen'

const javaToolRequirement: github.workflows.JavaToolRequirement = { ... }

Properties

Name	Type	Description
`version`	`string`	No description.
`cache`	`boolean`	Whether to enable automatic dependency caching.
`distribution`	`string`	The JDK distribution to use.
`packageManager`	`string`	The package manager to use for caching (e.g. "maven", "gradle", "sbt"). Required when `cache` is true.

`version`^Required

public readonly version: string;

Type: string

`cache`^Optional

public readonly cache: boolean;

Type: boolean
Default: false

Whether to enable automatic dependency caching.

`distribution`^Optional

public readonly distribution: string;

Type: string
Default: "corretto"

The JDK distribution to use.

`packageManager`^Optional

public readonly packageManager: string;

Type: string

The package manager to use for caching (e.g. "maven", "gradle", "sbt"). Required when cache is true.

Job

A GitHub Workflow job definition.

Initializer

import { github } from 'projen'

const job: github.workflows.Job = { ... }

Properties

Name	Type	Description
`permissions`	`projen.github.workflows.JobPermissions`	You can modify the default permissions granted to the GITHUB_TOKEN, adding or removing access as required, so that you only allow the minimum required access.
`concurrency`	`any`	Concurrency ensures that only a single job or workflow using the same concurrency group will run at a time.
`if`	`string`	You can use the if conditional to prevent a job from running unless a condition is met.
`name`	`string`	The name of the job displayed on GitHub.
`needs`	`string[]`	Identifies any jobs that must complete successfully before this job will run.
`strategy`	`projen.github.workflows.JobStrategy`	A strategy creates a build matrix for your jobs.
`steps`	`projen.github.workflows.JobStep[]`	A job contains a sequence of tasks called steps.
`container`	`projen.github.workflows.ContainerOptions`	A container to run any steps in a job that don't already specify a container.
`continueOnError`	`boolean`	Prevents a workflow run from failing when a job fails.
`defaults`	`projen.github.workflows.JobDefaults`	A map of default settings that will apply to all steps in the job.
`env`	`{[ key: string ]: string}`	A map of environment variables that are available to all steps in the job.
`environment`	`any`	The environment that the job references.
`outputs`	`{[ key: string ]: projen.github.workflows.JobStepOutput}`	A map of outputs for a job.
`runsOn`	`string[]`	The type of machine to run the job on.
`runsOnGroup`	`projen.GroupRunnerOptions`	Github Runner Group selection options.
`services`	`{[ key: string ]: projen.github.workflows.ContainerOptions}`	Used to host service containers for a job in a workflow.
`timeoutMinutes`	`number`	The maximum number of minutes to let a job run before GitHub automatically cancels it.
`tools`	`projen.github.workflows.Tools`	Tools required for this job.

`permissions`^Required

public readonly permissions: JobPermissions;

Type: projen.github.workflows.JobPermissions

You can modify the default permissions granted to the GITHUB_TOKEN, adding or removing access as required, so that you only allow the minimum required access.

Use { contents: READ } if your job only needs to clone code.

This is intentionally a required field since it is required in order to allow workflows to run in GitHub repositories with restricted default access.

https://docs.github.com/en/actions/reference/authentication-in-a-workflow#permissions-for-the-github_token

`concurrency`^Optional

public readonly concurrency: any;

Type: any

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

A concurrency group can be any string or expression. The expression can use any context except for the secrets context.

`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

The name of the job displayed on GitHub.

`needs`^Optional

public readonly needs: string[];

Type: string[]

Identifies any jobs that must complete successfully before this job will run.

It can be a string or array of strings. If a job fails, all jobs that need it are skipped unless the jobs use a conditional expression that causes the job to continue.

`strategy`^Optional

public readonly strategy: JobStrategy;

Type: projen.github.workflows.JobStrategy

A strategy creates a build matrix for your jobs.

You can define different variations to run each job in.

`steps`^Required

public readonly steps: JobStep[];

Type: projen.github.workflows.JobStep[]

A job contains a sequence of tasks called steps.

Steps can run commands, run setup tasks, or run an action in your repository, a public repository, or an action published in a Docker registry. Not all steps run actions, but all actions run as a step. Each step runs in its own process in the runner environment and has access to the workspace and filesystem. Because steps run in their own process, changes to environment variables are not preserved between steps. GitHub provides built-in steps to set up and complete a job.

`container`^Optional

public readonly container: ContainerOptions;

Type: projen.github.workflows.ContainerOptions

A container to run any steps in a job that don't already specify a container.

If you have steps that use both script and container actions, the container actions will run as sibling containers on the same network with the same volume mounts.

`continueOnError`^Optional

public readonly continueOnError: boolean;

Type: boolean

Prevents a workflow run from failing when a job fails.

Set to true to allow a workflow run to pass when this job fails.

`defaults`^Optional

public readonly defaults: JobDefaults;

Type: projen.github.workflows.JobDefaults

A map of default settings that will apply to all steps in the job.

You can also set default settings for the entire workflow.

`env`^Optional

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

Type: {[ key: string ]: string}

A map of environment variables that are available to all steps in the job.

You can also set environment variables for the entire workflow or an individual step.

`environment`^Optional

public readonly environment: any;

Type: any

The environment that the job references.

All environment protection rules must pass before a job referencing the environment is sent to a runner.

https://docs.github.com/en/actions/reference/environments

`outputs`^Optional

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

Type: {[ key: string ]: projen.github.workflows.JobStepOutput}

A map of outputs for a job.

Job outputs are available to all downstream jobs that depend on this job.

`runsOn`^Optional

public readonly runsOn: string[];

Type: string[]

The type of machine to run the job on.

The machine can be either a GitHub-hosted runner or a self-hosted runner.

Example

["ubuntu-latest"]

`runsOnGroup`^Optional

public readonly runsOnGroup: GroupRunnerOptions;

Type: projen.GroupRunnerOptions

Github Runner Group selection options.

`services`^Optional

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

Type: {[ key: string ]: projen.github.workflows.ContainerOptions}

Used to host service containers for a job in a workflow.

Service containers are useful for creating databases or cache services like Redis. The runner automatically creates a Docker network and manages the life cycle of the service containers.

`timeoutMinutes`^Optional

public readonly timeoutMinutes: number;

Type: number
Default: 360

The maximum number of minutes to let a job run before GitHub automatically cancels it.

`tools`^Optional

public readonly tools: Tools;

Type: projen.github.workflows.Tools

Tools required for this job.

Translates into actions/setup-xxx steps at the beginning of the job.

JobCallingReusableWorkflow

A GitHub Workflow Job calling a reusable workflow.

Initializer

import { github } from 'projen'

const jobCallingReusableWorkflow: github.workflows.JobCallingReusableWorkflow = { ... }

Properties

Name	Type	Description
`permissions`	`projen.github.workflows.JobPermissions`	You can modify the default permissions granted to the GITHUB_TOKEN, adding or removing access as required, so that you only allow the minimum required access.
`concurrency`	`any`	Concurrency ensures that only a single job or workflow using the same concurrency group will run at a time.
`if`	`string`	You can use the if conditional to prevent a job from running unless a condition is met.
`name`	`string`	The name of the job displayed on GitHub.
`needs`	`string[]`	Identifies any jobs that must complete successfully before this job will run.
`strategy`	`projen.github.workflows.JobStrategy`	A strategy creates a build matrix for your jobs.
`uses`	`string`	The location and version of a reusable workflow file to run as a job.
`secrets`	`string \| {[ key: string ]: string}`	When a job is used to call a reusable workflow, you can use secrets to provide a map of secrets that are passed to the called workflow.
`with`	`{[ key: string ]: string \| number \| boolean}`	When a job is used to call a reusable workflow, you can use with to provide a map of inputs that are passed to the called workflow.

`permissions`^Required

public readonly permissions: JobPermissions;

Type: projen.github.workflows.JobPermissions

You can modify the default permissions granted to the GITHUB_TOKEN, adding or removing access as required, so that you only allow the minimum required access.

Use { contents: READ } if your job only needs to clone code.

This is intentionally a required field since it is required in order to allow workflows to run in GitHub repositories with restricted default access.

https://docs.github.com/en/actions/reference/authentication-in-a-workflow#permissions-for-the-github_token

`concurrency`^Optional

public readonly concurrency: any;

Type: any

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

A concurrency group can be any string or expression. The expression can use any context except for the secrets context.

`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

The name of the job displayed on GitHub.

`needs`^Optional

public readonly needs: string[];

Type: string[]

Identifies any jobs that must complete successfully before this job will run.

It can be a string or array of strings. If a job fails, all jobs that need it are skipped unless the jobs use a conditional expression that causes the job to continue.

`strategy`^Optional

public readonly strategy: JobStrategy;

Type: projen.github.workflows.JobStrategy

A strategy creates a build matrix for your jobs.

You can define different variations to run each job in.

`uses`^Required

public readonly uses: string;

Type: string

The location and version of a reusable workflow file to run as a job.

`secrets`^Optional

public readonly secrets: string | {[ key: string ]: string};

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

When a job is used to call a reusable workflow, you can use secrets to provide a map of secrets that are passed to the called workflow.

Use the 'inherit' keyword to pass all the calling workflow's secrets to the called workflow

`with`^Optional

public readonly with: {[ key: string ]: string | number | boolean};

Type: {[ key: string ]: string | number | boolean}

When a job is used to call a reusable workflow, you can use with to provide a map of inputs that are passed to the called workflow.

Allowed expression contexts: github, and needs.

JobDefaults

Default settings for all steps in the job.

Initializer

import { github } from 'projen'

const jobDefaults: github.workflows.JobDefaults = { ... }

Properties

Name	Type	Description
`run`	`projen.github.workflows.RunSettings`	Default run settings.

`run`^Optional

public readonly run: RunSettings;

Type: projen.github.workflows.RunSettings

Default run settings.

JobMatrix

A job matrix.

Initializer

import { github } from 'projen'

const jobMatrix: github.workflows.JobMatrix = { ... }

Properties

Name	Type	Description
`domain`	`{[ key: string ]: string \| string \| number \| boolean[]}`	Each option you define in the matrix has a key and value.
`exclude`	`{[ key: string ]: string \| number \| boolean}[]`	You can remove a specific configurations defined in the build matrix using the exclude option.
`include`	`{[ key: string ]: string \| number \| boolean}[]`	You can add additional configuration options to a build matrix job that already exists.

`domain`^Optional

public readonly domain: {[ key: string ]: string | (string | number | boolean)[]};

Type: {[ key: string ]: string | string | number | boolean[]}

Each option you define in the matrix has a key and value.

The keys you define become properties in the matrix context and you can reference the property in other areas of your workflow file. For example, if you define the key os that contains an array of operating systems, you can use the matrix.os property as the value of the runs-on keyword to create a job for each operating system.

`exclude`^Optional

public readonly exclude: ({[ key: string ]: string | number | boolean})[];

Type: {[ key: string ]: string | number | boolean}[]

You can remove a specific configurations defined in the build matrix using the exclude option.

Using exclude removes a job defined by the build matrix.

`include`^Optional

public readonly include: ({[ key: string ]: string | number | boolean})[];

Type: {[ key: string ]: string | number | boolean}[]

You can add additional configuration options to a build matrix job that already exists.

For example, if you want to use a specific version of npm when the job that uses windows-latest and version 8 of node runs, you can use include to specify that additional option.

JobPermissions

The available scopes and access values for workflow permissions.

If you specify the access for any of these scopes, all those that are not specified are set to JobPermission.NONE, instead of the default behavior when none is specified.

https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/controlling-permissions-for-github_token#defining-access-for-the-github_token-permissions

Initializer

import { github } from 'projen'

const jobPermissions: github.workflows.JobPermissions = { ... }

Properties

Name	Type	Description
`actions`	`projen.github.workflows.JobPermission`	No description.
`attestations`	`projen.github.workflows.JobPermission`	No description.
`checks`	`projen.github.workflows.JobPermission`	No description.
`contents`	`projen.github.workflows.JobPermission`	No description.
`deployments`	`projen.github.workflows.JobPermission`	No description.
`discussions`	`projen.github.workflows.JobPermission`	No description.
`idToken`	`projen.github.workflows.JobPermission`	No description.
`issues`	`projen.github.workflows.JobPermission`	No description.
`models`	`projen.github.workflows.JobPermission`	No description.
`packages`	`projen.github.workflows.JobPermission`	No description.
`pages`	`projen.github.workflows.JobPermission`	No description.
`pullRequests`	`projen.github.workflows.JobPermission`	No description.
`securityEvents`	`projen.github.workflows.JobPermission`	No description.
`statuses`	`projen.github.workflows.JobPermission`	No description.

`actions`^Optional

public readonly actions: JobPermission;

Type: projen.github.workflows.JobPermission

`attestations`^Optional

public readonly attestations: JobPermission;

Type: projen.github.workflows.JobPermission

`checks`^Optional

public readonly checks: JobPermission;

Type: projen.github.workflows.JobPermission

`contents`^Optional

public readonly contents: JobPermission;

Type: projen.github.workflows.JobPermission

`deployments`^Optional

public readonly deployments: JobPermission;

Type: projen.github.workflows.JobPermission

`discussions`^Optional

public readonly discussions: JobPermission;

Type: projen.github.workflows.JobPermission

`idToken`^Optional

public readonly idToken: JobPermission;

Type: projen.github.workflows.JobPermission

`issues`^Optional

public readonly issues: JobPermission;

Type: projen.github.workflows.JobPermission

`models`^Optional

public readonly models: JobPermission;

Type: projen.github.workflows.JobPermission

`packages`^Optional

public readonly packages: JobPermission;

Type: projen.github.workflows.JobPermission

`pages`^Optional

public readonly pages: JobPermission;

Type: projen.github.workflows.JobPermission

`pullRequests`^Optional

public readonly pullRequests: JobPermission;

Type: projen.github.workflows.JobPermission

`securityEvents`^Optional

public readonly securityEvents: JobPermission;

Type: projen.github.workflows.JobPermission

`statuses`^Optional

public readonly statuses: JobPermission;

Type: projen.github.workflows.JobPermission

JobStep

JobSteps run as part of a GitHub Workflow Job.

https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idsteps

Initializer

import { github } from 'projen'

const jobStep: github.workflows.JobStep = { ... }

Properties

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

`env`^Optional

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

Type: {[ key: string ]: string}

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

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

`id`^Optional

public readonly id: string;

Type: string

A unique identifier for the step.

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

`if`^Optional

public readonly if: string;

Type: string

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

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

`name`^Optional

public readonly name: string;

Type: string

A name for your step to display on GitHub.

`shell`^Optional

public readonly shell: string;

Type: string

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

Refer to GitHub documentation for allowed values.

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

`workingDirectory`^Optional

public readonly workingDirectory: string;

Type: string

Specifies a working directory for a step.

Overrides a job's working directory.

`run`^Optional

public readonly run: string;

Type: string

Runs command-line programs using the operating system's shell.

If you do not provide a name, the step name will default to the text specified in the run command.

`uses`^Optional

public readonly uses: string;

Type: string

Selects an action to run as part of a step in your job.

An action is a reusable unit of code. You can use an action defined in the same repository as the workflow, a public repository, or in a published Docker container image.

`with`^Optional

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

Type: {[ key: string ]: any}

A map of the input parameters defined by the action.

Each input parameter is a key/value pair. Input parameters are set as environment variables. The variable is prefixed with INPUT_ and converted to upper case.

`background`^Optional

public readonly background: boolean;

Type: boolean

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

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

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

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

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

`cancel`^Optional

public readonly cancel: string;

Type: string

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

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

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

`continueOnError`^Optional

public readonly continueOnError: boolean;

Type: boolean

Prevents a job from failing when a step fails.

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

`parallel`^Optional

public readonly parallel: JobStep[];

Type: projen.github.workflows.JobStep[]

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

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

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

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

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

`timeoutMinutes`^Optional

public readonly timeoutMinutes: number;

Type: number

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

`wait`^Optional

public readonly wait: string[];

Type: string[]

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

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

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

`waitAll`^Optional

public readonly waitAll: boolean;

Type: boolean

Pauses the job until all active background steps complete.

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

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

JobStepConfiguration

These settings are unique to a JobStep from the fields contained within the metadata action.yaml file present in when creating a new GitHub Action. These fields are not present in action.yml, but are in JobStep, which are using when creating workflows.

Initializer

import { github } from 'projen'

const jobStepConfiguration: github.workflows.JobStepConfiguration = { ... }

Properties

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

`env`^Optional

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

Type: {[ key: string ]: string}

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

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

`id`^Optional

public readonly id: string;

Type: string

A unique identifier for the step.

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

`if`^Optional

public readonly if: string;

Type: string

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

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

`name`^Optional

public readonly name: string;

Type: string

A name for your step to display on GitHub.

`shell`^Optional

public readonly shell: string;

Type: string

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

Refer to GitHub documentation for allowed values.

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

`workingDirectory`^Optional

public readonly workingDirectory: string;

Type: string

Specifies a working directory for a step.

Overrides a job's working directory.

`background`^Optional

public readonly background: boolean;

Type: boolean

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

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

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

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

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

`cancel`^Optional

public readonly cancel: string;

Type: string

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

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

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

`continueOnError`^Optional

public readonly continueOnError: boolean;

Type: boolean

Prevents a job from failing when a step fails.

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

`parallel`^Optional

public readonly parallel: JobStep[];

Type: projen.github.workflows.JobStep[]

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

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

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

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

`timeoutMinutes`^Optional

public readonly timeoutMinutes: number;

Type: number

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

`wait`^Optional

public readonly wait: string[];

Type: string[]

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

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

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

`waitAll`^Optional

public readonly waitAll: boolean;

Type: boolean

Pauses the job until all active background steps complete.

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

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

JobStepOutput

An output binding for a job.

Initializer

import { github } from 'projen'

const jobStepOutput: github.workflows.JobStepOutput = { ... }

Properties

Name	Type	Description
`outputName`	`string`	The name of the job output that is being bound.
`stepId`	`string`	The ID of the step that exposes the output.

`outputName`^Required

public readonly outputName: string;

Type: string

The name of the job output that is being bound.

`stepId`^Required

public readonly stepId: string;

Type: string

The ID of the step that exposes the output.

JobStrategy

A strategy creates a build matrix for your jobs.

You can define different variations to run each job in.

Initializer

import { github } from 'projen'

const jobStrategy: github.workflows.JobStrategy = { ... }

Properties

Name	Type	Description
`failFast`	`boolean`	When set to true, GitHub cancels all in-progress jobs if any matrix job fails.
`matrix`	`projen.github.workflows.JobMatrix`	You can define a matrix of different job configurations.
`maxParallel`	`number`	The maximum number of jobs that can run simultaneously when using a matrix job strategy.

`failFast`^Optional

public readonly failFast: boolean;

Type: boolean

When set to true, GitHub cancels all in-progress jobs if any matrix job fails.

Default: true

`matrix`^Optional

public readonly matrix: JobMatrix;

Type: projen.github.workflows.JobMatrix

You can define a matrix of different job configurations.

A matrix allows you to create multiple jobs by performing variable substitution in a single job definition. For example, you can use a matrix to create jobs for more than one supported version of a programming language, operating system, or tool. A matrix reuses the job's configuration and creates a job for each matrix you configure.

A job matrix can generate a maximum of 256 jobs per workflow run. This limit also applies to self-hosted runners.

`maxParallel`^Optional

public readonly maxParallel: number;

Type: number

The maximum number of jobs that can run simultaneously when using a matrix job strategy.

By default, GitHub will maximize the number of jobs run in parallel depending on the available runners on GitHub-hosted virtual machines.

LabelOptions

Label options.

Initializer

import { github } from 'projen'

const labelOptions: github.workflows.LabelOptions = { ... }

Properties

Name	Type	Description
`types`	`string[]`	Which activity types to trigger on.

`types`^Optional

public readonly types: string[];

Type: string[]

Which activity types to trigger on.

MergeGroupOptions

Merge group options.

Initializer

import { github } from 'projen'

const mergeGroupOptions: github.workflows.MergeGroupOptions = { ... }

Properties

Name	Type	Description
`branches`	`string[]`	When using the merge_group events, you can configure a workflow to run on specific base branches.

`branches`^Optional

public readonly branches: string[];

Type: string[]

When using the merge_group events, you can configure a workflow to run on specific base branches.

If not specified, all branches will trigger the workflow.

MilestoneOptions

Milestone options.

Initializer

import { github } from 'projen'

const milestoneOptions: github.workflows.MilestoneOptions = { ... }

Properties

Name	Type	Description
`types`	`string[]`	Which activity types to trigger on.

`types`^Optional

public readonly types: string[];

Type: string[]

Which activity types to trigger on.

PageBuildOptions

The Page build event accepts no options.

Initializer

import { github } from 'projen'

const pageBuildOptions: github.workflows.PageBuildOptions = { ... }

ProjectCardOptions

Project card options.

Initializer

import { github } from 'projen'

const projectCardOptions: github.workflows.ProjectCardOptions = { ... }

Properties

Name	Type	Description
`types`	`string[]`	Which activity types to trigger on.

`types`^Optional

public readonly types: string[];

Type: string[]

Which activity types to trigger on.

ProjectColumnOptions

Probject column options.

Initializer

import { github } from 'projen'

const projectColumnOptions: github.workflows.ProjectColumnOptions = { ... }

Properties

Name	Type	Description
`types`	`string[]`	Which activity types to trigger on.

`types`^Optional

public readonly types: string[];

Type: string[]

Which activity types to trigger on.

ProjectOptions

Project options.

Initializer

import { github } from 'projen'

const projectOptions: github.workflows.ProjectOptions = { ... }

Properties

Name	Type	Description
`types`	`string[]`	Which activity types to trigger on.

`types`^Optional

public readonly types: string[];

Type: string[]

Which activity types to trigger on.

PublicOptions

The Public event accepts no options.

Initializer

import { github } from 'projen'

const publicOptions: github.workflows.PublicOptions = { ... }

PullRequestOptions

Pull request options.

Initializer

import { github } from 'projen'

const pullRequestOptions: github.workflows.PullRequestOptions = { ... }

Properties

Name	Type	Description
`branches`	`string[]`	When using the push, pull_request and pull_request_target events, you can configure a workflow to run on specific branches or tags.
`paths`	`string[]`	When using the push, pull_request and pull_request_target events, you can configure a workflow to run when at least one file does not match paths-ignore or at least one modified file matches the configured paths.
`tags`	`string[]`	When using the push, pull_request and pull_request_target events, you can configure a workflow to run on specific branches or tags.
`types`	`string[]`	Which activity types to trigger on.

`branches`^Optional

public readonly branches: string[];

Type: string[]

When using the push, pull_request and pull_request_target events, you can configure a workflow to run on specific branches or tags.

For a pull_request event, only branches and tags on the base are evaluated. If you define only tags or only branches, the workflow won't run for events affecting the undefined Git ref.

https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet

`paths`^Optional

public readonly paths: string[];

Type: string[]

When using the push, pull_request and pull_request_target events, you can configure a workflow to run when at least one file does not match paths-ignore or at least one modified file matches the configured paths.

Path filters are not evaluated for pushes to tags.

https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet

`tags`^Optional

public readonly tags: string[];

Type: string[]

When using the push, pull_request and pull_request_target events, you can configure a workflow to run on specific branches or tags.

For a pull_request event, only branches and tags on the base are evaluated. If you define only tags or only branches, the workflow won't run for events affecting the undefined Git ref.

https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet

`types`^Optional

public readonly types: string[];

Type: string[]

Which activity types to trigger on.

PullRequestReviewCommentOptions

Pull request review comment options.

Initializer

import { github } from 'projen'

const pullRequestReviewCommentOptions: github.workflows.PullRequestReviewCommentOptions = { ... }

Properties

Name	Type	Description
`types`	`string[]`	Which activity types to trigger on.

`types`^Optional

public readonly types: string[];

Type: string[]

Which activity types to trigger on.

PullRequestReviewOptions

Pull request review options.

Initializer

import { github } from 'projen'

const pullRequestReviewOptions: github.workflows.PullRequestReviewOptions = { ... }

Properties

Name	Type	Description
`types`	`string[]`	Which activity types to trigger on.

`types`^Optional

public readonly types: string[];

Type: string[]

Which activity types to trigger on.

PullRequestTargetOptions

Pull request target options.

Initializer

import { github } from 'projen'

const pullRequestTargetOptions: github.workflows.PullRequestTargetOptions = { ... }

Properties

Name	Type	Description
`branches`	`string[]`	When using the push, pull_request and pull_request_target events, you can configure a workflow to run on specific branches or tags.
`paths`	`string[]`	When using the push, pull_request and pull_request_target events, you can configure a workflow to run when at least one file does not match paths-ignore or at least one modified file matches the configured paths.
`tags`	`string[]`	When using the push, pull_request and pull_request_target events, you can configure a workflow to run on specific branches or tags.
`types`	`string[]`	Which activity types to trigger on.

`branches`^Optional

public readonly branches: string[];

Type: string[]

When using the push, pull_request and pull_request_target events, you can configure a workflow to run on specific branches or tags.

For a pull_request event, only branches and tags on the base are evaluated. If you define only tags or only branches, the workflow won't run for events affecting the undefined Git ref.

https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet

`paths`^Optional

public readonly paths: string[];

Type: string[]

Path filters are not evaluated for pushes to tags.

https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet

`tags`^Optional

public readonly tags: string[];

Type: string[]

When using the push, pull_request and pull_request_target events, you can configure a workflow to run on specific branches or tags.

For a pull_request event, only branches and tags on the base are evaluated. If you define only tags or only branches, the workflow won't run for events affecting the undefined Git ref.

https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet

`types`^Optional

public readonly types: string[];

Type: string[]

Which activity types to trigger on.

PushOptions

Options for push-like events.

Initializer

import { github } from 'projen'

const pushOptions: github.workflows.PushOptions = { ... }

Properties

Name	Type	Description
`branches`	`string[]`	When using the push, pull_request and pull_request_target events, you can configure a workflow to run on specific branches or tags.
`paths`	`string[]`	When using the push, pull_request and pull_request_target events, you can configure a workflow to run when at least one file does not match paths-ignore or at least one modified file matches the configured paths.
`tags`	`string[]`	When using the push, pull_request and pull_request_target events, you can configure a workflow to run on specific branches or tags.

`branches`^Optional

public readonly branches: string[];

Type: string[]

When using the push, pull_request and pull_request_target events, you can configure a workflow to run on specific branches or tags.

For a pull_request event, only branches and tags on the base are evaluated. If you define only tags or only branches, the workflow won't run for events affecting the undefined Git ref.

https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet

`paths`^Optional

public readonly paths: string[];

Type: string[]

Path filters are not evaluated for pushes to tags.

https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet

`tags`^Optional

public readonly tags: string[];

Type: string[]

When using the push, pull_request and pull_request_target events, you can configure a workflow to run on specific branches or tags.

For a pull_request event, only branches and tags on the base are evaluated. If you define only tags or only branches, the workflow won't run for events affecting the undefined Git ref.

https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet

PythonToolRequirement

Version requirement for Python tools.

Initializer

import { github } from 'projen'

const pythonToolRequirement: github.workflows.PythonToolRequirement = { ... }

Properties

Name	Type	Description
`version`	`string`	No description.
`cache`	`boolean`	Whether to enable automatic dependency caching.
`packageManager`	`string`	The package manager to use for caching (e.g. "pip", "pipenv", "poetry"). Required when `cache` is true.

`version`^Required

public readonly version: string;

Type: string

`cache`^Optional

public readonly cache: boolean;

Type: boolean
Default: false

Whether to enable automatic dependency caching.

`packageManager`^Optional

public readonly packageManager: string;

Type: string

The package manager to use for caching (e.g. "pip", "pipenv", "poetry"). Required when cache is true.

RegistryPackageOptions

Registry package options.

Initializer

import { github } from 'projen'

const registryPackageOptions: github.workflows.RegistryPackageOptions = { ... }

Properties

Name	Type	Description
`types`	`string[]`	Which activity types to trigger on.

`types`^Optional

public readonly types: string[];

Type: string[]

Which activity types to trigger on.

ReleaseOptions

Release options.

Initializer

import { github } from 'projen'

const releaseOptions: github.workflows.ReleaseOptions = { ... }

Properties

Name	Type	Description
`types`	`string[]`	Which activity types to trigger on.

`types`^Optional

public readonly types: string[];

Type: string[]

Which activity types to trigger on.

RepositoryDispatchOptions

Repository dispatch options.

Initializer

import { github } from 'projen'

const repositoryDispatchOptions: github.workflows.RepositoryDispatchOptions = { ... }

Properties

Name	Type	Description
`types`	`string[]`	Which activity types to trigger on.

`types`^Optional

public readonly types: string[];

Type: string[]

Which activity types to trigger on.

RunSettings

Run settings for a job.

Initializer

import { github } from 'projen'

const runSettings: github.workflows.RunSettings = { ... }

Properties

Name	Type	Description
`shell`	`string`	Which shell to use for running the step.
`workingDirectory`	`string`	Working directory to use when running the step.

`shell`^Optional

public readonly shell: string;

Type: string

Which shell to use for running the step.

Example

"bash"

`workingDirectory`^Optional

public readonly workingDirectory: string;

Type: string

Working directory to use when running the step.

StatusOptions

The Status event accepts no options.

Initializer

import { github } from 'projen'

const statusOptions: github.workflows.StatusOptions = { ... }

Step

This contains the fields that are common amongst both: - JobStep, which is a step that is part of a Job in Github Actions.

This is by far the most common use case.

The metadata file action.yaml that is used to define an Action when you are creating one. As in, if you were creating an Action to be used in a JobStep. There is some overlap between the two, and this captures that overlap.

https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions

Initializer

import { github } from 'projen'

const step: github.workflows.Step = { ... }

Properties

Name	Type	Description
`env`	`{[ key: string ]: string}`	Sets environment variables for steps to use in the runner environment.
`id`	`string`	A unique identifier for the step.
`if`	`string`	You can use the if conditional to prevent a job from running unless a condition is met.
`name`	`string`	A name for your step to display on GitHub.
`shell`	`string`	Overrides the default shell settings in the runner's operating system and the job's default.
`workingDirectory`	`string`	Specifies a working directory for a step.
`run`	`string`	Runs command-line programs using the operating system's shell.
`uses`	`string`	Selects an action to run as part of a step in your job.
`with`	`{[ key: string ]: any}`	A map of the input parameters defined by the action.

`env`^Optional

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

Type: {[ key: string ]: string}

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

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

`id`^Optional

public readonly id: string;

Type: string

A unique identifier for the step.

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

`if`^Optional

public readonly if: string;

Type: string

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

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

`name`^Optional

public readonly name: string;

Type: string

A name for your step to display on GitHub.

`shell`^Optional

public readonly shell: string;

Type: string

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

Refer to GitHub documentation for allowed values.

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

`workingDirectory`^Optional

public readonly workingDirectory: string;

Type: string

Specifies a working directory for a step.

Overrides a job's working directory.

`run`^Optional

public readonly run: string;

Type: string

Runs command-line programs using the operating system's shell.

If you do not provide a name, the step name will default to the text specified in the run command.

`uses`^Optional

public readonly uses: string;

Type: string

Selects an action to run as part of a step in your job.

An action is a reusable unit of code. You can use an action defined in the same repository as the workflow, a public repository, or in a published Docker container image.

`with`^Optional

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

Type: {[ key: string ]: any}

A map of the input parameters defined by the action.

Each input parameter is a key/value pair. Input parameters are set as environment variables. The variable is prefixed with INPUT_ and converted to upper case.

StepConfiguration

Fields that describe the How, Why, When, and Who of a Step.

These fields can have none present, but can be present on every Step, and have no effect on one another.

This stands in contrast to the Command (non-Configuration) fields, which are mutually exclusive, and describe the What.

Initializer

import { github } from 'projen'

const stepConfiguration: github.workflows.StepConfiguration = { ... }

Properties

Name	Type	Description
`env`	`{[ key: string ]: string}`	Sets environment variables for steps to use in the runner environment.
`id`	`string`	A unique identifier for the step.
`if`	`string`	You can use the if conditional to prevent a job from running unless a condition is met.
`name`	`string`	A name for your step to display on GitHub.
`shell`	`string`	Overrides the default shell settings in the runner's operating system and the job's default.
`workingDirectory`	`string`	Specifies a working directory for a step.

`env`^Optional

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

Type: {[ key: string ]: string}

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

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

`id`^Optional

public readonly id: string;

Type: string

A unique identifier for the step.

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

`if`^Optional

public readonly if: string;

Type: string

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

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

`name`^Optional

public readonly name: string;

Type: string

A name for your step to display on GitHub.

`shell`^Optional

public readonly shell: string;

Type: string

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

Refer to GitHub documentation for allowed values.

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

`workingDirectory`^Optional

public readonly workingDirectory: string;

Type: string

Specifies a working directory for a step.

Overrides a job's working directory.

ToolRequirement

Version requirement for tools.

Initializer

import { github } from 'projen'

const toolRequirement: github.workflows.ToolRequirement = { ... }

Properties

Name	Type	Description
`version`	`string`	No description.
`cache`	`boolean`	Whether to enable automatic dependency caching.

`version`^Required

public readonly version: string;

Type: string

`cache`^Optional

public readonly cache: boolean;

Type: boolean
Default: false

Whether to enable automatic dependency caching.

Tools

Supported tools.

Initializer

import { github } from 'projen'

const tools: github.workflows.Tools = { ... }

Properties

Name	Type	Description
`dotnet`	`projen.github.workflows.ToolRequirement`	Setup .NET Core.
`go`	`projen.github.workflows.ToolRequirement`	Setup golang.
`java`	`projen.github.workflows.JavaToolRequirement`	Setup java.
`node`	`projen.github.workflows.ToolRequirement`	Setup node.js.
`python`	`projen.github.workflows.PythonToolRequirement`	Setup python.

`dotnet`^Optional

public readonly dotnet: ToolRequirement;

Type: projen.github.workflows.ToolRequirement
Default: not installed

Setup .NET Core.

`go`^Optional

public readonly go: ToolRequirement;

Type: projen.github.workflows.ToolRequirement
Default: not installed

Setup golang.

`java`^Optional

public readonly java: JavaToolRequirement;

Type: projen.github.workflows.JavaToolRequirement
Default: not installed

Setup java.

`node`^Optional

public readonly node: ToolRequirement;

Type: projen.github.workflows.ToolRequirement
Default: not installed

Setup node.js.

`python`^Optional

public readonly python: PythonToolRequirement;

Type: projen.github.workflows.PythonToolRequirement
Default: not installed

Setup python.

Triggers

The set of available triggers for GitHub Workflows.

https://docs.github.com/en/actions/reference/events-that-trigger-workflows

Initializer

import { github } from 'projen'

const triggers: github.workflows.Triggers = { ... }

Properties

Name	Type	Description
`branchProtectionRule`	`projen.github.workflows.BranchProtectionRuleOptions`	Runs your workflow anytime the branch_protection_rule event occurs.
`checkRun`	`projen.github.workflows.CheckRunOptions`	Runs your workflow anytime the check_run event occurs.
`checkSuite`	`projen.github.workflows.CheckSuiteOptions`	Runs your workflow anytime the check_suite event occurs.
`create`	`projen.github.workflows.CreateOptions`	Runs your workflow anytime someone creates a branch or tag, which triggers the create event.
`delete`	`projen.github.workflows.DeleteOptions`	Runs your workflow anytime someone deletes a branch or tag, which triggers the delete event.
`deployment`	`projen.github.workflows.DeploymentOptions`	Runs your workflow anytime someone creates a deployment, which triggers the deployment event.
`deploymentStatus`	`projen.github.workflows.DeploymentStatusOptions`	Runs your workflow anytime a third party provides a deployment status, which triggers the deployment_status event.
`discussion`	`projen.github.workflows.DiscussionOptions`	Runs your workflow anytime the discussion event occurs.
`discussionComment`	`projen.github.workflows.DiscussionCommentOptions`	Runs your workflow anytime the discussion_comment event occurs.
`fork`	`projen.github.workflows.ForkOptions`	Runs your workflow anytime when someone forks a repository, which triggers the fork event.
`gollum`	`projen.github.workflows.GollumOptions`	Runs your workflow when someone creates or updates a Wiki page, which triggers the gollum event.
`issueComment`	`projen.github.workflows.IssueCommentOptions`	Runs your workflow anytime the issue_comment event occurs.
`issues`	`projen.github.workflows.IssuesOptions`	Runs your workflow anytime the issues event occurs.
`label`	`projen.github.workflows.LabelOptions`	Runs your workflow anytime the label event occurs.
`mergeGroup`	`projen.github.workflows.MergeGroupOptions`	Runs your workflow when a pull request is added to a merge queue, which adds the pull request to a merge group.
`milestone`	`projen.github.workflows.MilestoneOptions`	Runs your workflow anytime the milestone event occurs.
`pageBuild`	`projen.github.workflows.PageBuildOptions`	Runs your workflow anytime someone pushes to a GitHub Pages-enabled branch, which triggers the page_build event.
`project`	`projen.github.workflows.ProjectOptions`	Runs your workflow anytime the project event occurs.
`projectCard`	`projen.github.workflows.ProjectCardOptions`	Runs your workflow anytime the project_card event occurs.
`projectColumn`	`projen.github.workflows.ProjectColumnOptions`	Runs your workflow anytime the project_column event occurs.
`public`	`projen.github.workflows.PublicOptions`	Runs your workflow anytime someone makes a private repository public, which triggers the public event.
`pullRequest`	`projen.github.workflows.PullRequestOptions`	Runs your workflow anytime the pull_request event occurs.
`pullRequestReview`	`projen.github.workflows.PullRequestReviewOptions`	Runs your workflow anytime the pull_request_review event occurs.
`pullRequestReviewComment`	`projen.github.workflows.PullRequestReviewCommentOptions`	Runs your workflow anytime a comment on a pull request's unified diff is modified, which triggers the pull_request_review_comment event.
`pullRequestTarget`	`projen.github.workflows.PullRequestTargetOptions`	This event runs in the context of the base of the pull request, rather than in the merge commit as the pull_request event does.
`push`	`projen.github.workflows.PushOptions`	Runs your workflow when someone pushes to a repository branch, which triggers the push event.
`registryPackage`	`projen.github.workflows.RegistryPackageOptions`	Runs your workflow anytime a package is published or updated.
`release`	`projen.github.workflows.ReleaseOptions`	Runs your workflow anytime the release event occurs.
`repositoryDispatch`	`projen.github.workflows.RepositoryDispatchOptions`	You can use the GitHub API to trigger a webhook event called repository_dispatch when you want to trigger a workflow for activity that happens outside of GitHub.
`schedule`	`projen.github.workflows.CronScheduleOptions[]`	You can schedule a workflow to run at specific UTC times using POSIX cron syntax.
`status`	`projen.github.workflows.StatusOptions`	Runs your workflow anytime the status of a Git commit changes, which triggers the status event.
`watch`	`projen.github.workflows.WatchOptions`	Runs your workflow anytime the watch event occurs.
`workflowCall`	`projen.github.workflows.WorkflowCallOptions`	Can be called from another workflow.
`workflowDispatch`	`projen.github.workflows.WorkflowDispatchOptions`	You can configure custom-defined input properties, default input values, and required inputs for the event directly in your workflow.
`workflowRun`	`projen.github.workflows.WorkflowRunOptions`	This event occurs when a workflow run is requested or completed, and allows you to execute a workflow based on the finished result of another workflow.

`branchProtectionRule`^Optional

public readonly branchProtectionRule: BranchProtectionRuleOptions;

Type: projen.github.workflows.BranchProtectionRuleOptions

Runs your workflow anytime the branch_protection_rule event occurs.

`checkRun`^Optional

public readonly checkRun: CheckRunOptions;

Type: projen.github.workflows.CheckRunOptions

Runs your workflow anytime the check_run event occurs.

`checkSuite`^Optional

public readonly checkSuite: CheckSuiteOptions;

Type: projen.github.workflows.CheckSuiteOptions

Runs your workflow anytime the check_suite event occurs.

`create`^Optional

public readonly create: CreateOptions;

Type: projen.github.workflows.CreateOptions

Runs your workflow anytime someone creates a branch or tag, which triggers the create event.

`delete`^Optional

public readonly delete: DeleteOptions;

Type: projen.github.workflows.DeleteOptions

Runs your workflow anytime someone deletes a branch or tag, which triggers the delete event.

`deployment`^Optional

public readonly deployment: DeploymentOptions;

Type: projen.github.workflows.DeploymentOptions

Runs your workflow anytime someone creates a deployment, which triggers the deployment event.

Deployments created with a commit SHA may not have a Git ref.

`deploymentStatus`^Optional

public readonly deploymentStatus: DeploymentStatusOptions;

Type: projen.github.workflows.DeploymentStatusOptions

Runs your workflow anytime a third party provides a deployment status, which triggers the deployment_status event.

Deployments created with a commit SHA may not have a Git ref.

`discussion`^Optional

public readonly discussion: DiscussionOptions;

Type: projen.github.workflows.DiscussionOptions

Runs your workflow anytime the discussion event occurs.

More than one activity type triggers this event.

https://docs.github.com/en/graphql/guides/using-the-graphql-api-for-discussions

`discussionComment`^Optional

public readonly discussionComment: DiscussionCommentOptions;

Type: projen.github.workflows.DiscussionCommentOptions

Runs your workflow anytime the discussion_comment event occurs.

More than one activity type triggers this event.

https://docs.github.com/en/graphql/guides/using-the-graphql-api-for-discussions

`fork`^Optional

public readonly fork: ForkOptions;

Type: projen.github.workflows.ForkOptions

Runs your workflow anytime when someone forks a repository, which triggers the fork event.

`gollum`^Optional

public readonly gollum: GollumOptions;

Type: projen.github.workflows.GollumOptions

Runs your workflow when someone creates or updates a Wiki page, which triggers the gollum event.

`issueComment`^Optional

public readonly issueComment: IssueCommentOptions;

Type: projen.github.workflows.IssueCommentOptions

Runs your workflow anytime the issue_comment event occurs.

`issues`^Optional

public readonly issues: IssuesOptions;

Type: projen.github.workflows.IssuesOptions

Runs your workflow anytime the issues event occurs.

`label`^Optional

public readonly label: LabelOptions;

Type: projen.github.workflows.LabelOptions

Runs your workflow anytime the label event occurs.

`mergeGroup`^Optional

public readonly mergeGroup: MergeGroupOptions;

Type: projen.github.workflows.MergeGroupOptions

Runs your workflow when a pull request is added to a merge queue, which adds the pull request to a merge group.

`milestone`^Optional

public readonly milestone: MilestoneOptions;

Type: projen.github.workflows.MilestoneOptions

Runs your workflow anytime the milestone event occurs.

`pageBuild`^Optional

public readonly pageBuild: PageBuildOptions;

Type: projen.github.workflows.PageBuildOptions

Runs your workflow anytime someone pushes to a GitHub Pages-enabled branch, which triggers the page_build event.

`project`^Optional

public readonly project: ProjectOptions;

Type: projen.github.workflows.ProjectOptions

Runs your workflow anytime the project event occurs.

`projectCard`^Optional

public readonly projectCard: ProjectCardOptions;

Type: projen.github.workflows.ProjectCardOptions

Runs your workflow anytime the project_card event occurs.

`projectColumn`^Optional

public readonly projectColumn: ProjectColumnOptions;

Type: projen.github.workflows.ProjectColumnOptions

Runs your workflow anytime the project_column event occurs.

`public`^Optional

public readonly public: PublicOptions;

Type: projen.github.workflows.PublicOptions

Runs your workflow anytime someone makes a private repository public, which triggers the public event.

`pullRequest`^Optional

public readonly pullRequest: PullRequestOptions;

Type: projen.github.workflows.PullRequestOptions

Runs your workflow anytime the pull_request event occurs.

`pullRequestReview`^Optional

public readonly pullRequestReview: PullRequestReviewOptions;

Type: projen.github.workflows.PullRequestReviewOptions

Runs your workflow anytime the pull_request_review event occurs.

`pullRequestReviewComment`^Optional

public readonly pullRequestReviewComment: PullRequestReviewCommentOptions;

Type: projen.github.workflows.PullRequestReviewCommentOptions

Runs your workflow anytime a comment on a pull request's unified diff is modified, which triggers the pull_request_review_comment event.

`pullRequestTarget`^Optional

public readonly pullRequestTarget: PullRequestTargetOptions;

Type: projen.github.workflows.PullRequestTargetOptions

This event runs in the context of the base of the pull request, rather than in the merge commit as the pull_request event does.

This prevents executing unsafe workflow code from the head of the pull request that could alter your repository or steal any secrets you use in your workflow. This event allows you to do things like create workflows that label and comment on pull requests based on the contents of the event payload.

WARNING: The pull_request_target event is granted read/write repository token and can access secrets, even when it is triggered from a fork. Although the workflow runs in the context of the base of the pull request, you should make sure that you do not check out, build, or run untrusted code from the pull request with this event. Additionally, any caches share the same scope as the base branch, and to help prevent cache poisoning, you should not save the cache if there is a possibility that the cache contents were altered.

https://securitylab.github.com/research/github-actions-preventing-pwn-requests

`push`^Optional

public readonly push: PushOptions;

Type: projen.github.workflows.PushOptions

Runs your workflow when someone pushes to a repository branch, which triggers the push event.

`registryPackage`^Optional

public readonly registryPackage: RegistryPackageOptions;

Type: projen.github.workflows.RegistryPackageOptions

Runs your workflow anytime a package is published or updated.

`release`^Optional

public readonly release: ReleaseOptions;

Type: projen.github.workflows.ReleaseOptions

Runs your workflow anytime the release event occurs.

`repositoryDispatch`^Optional

public readonly repositoryDispatch: RepositoryDispatchOptions;

Type: projen.github.workflows.RepositoryDispatchOptions

You can use the GitHub API to trigger a webhook event called repository_dispatch when you want to trigger a workflow for activity that happens outside of GitHub.

`schedule`^Optional

public readonly schedule: CronScheduleOptions[];

Type: projen.github.workflows.CronScheduleOptions[]

You can schedule a workflow to run at specific UTC times using POSIX cron syntax.

Scheduled workflows run on the latest commit on the default or base branch. The shortest interval you can run scheduled workflows is once every 5 minutes.

https://pubs.opengroup.org/onlinepubs/9699919799/utilities/crontab.html#tag_20_25_07

`status`^Optional

public readonly status: StatusOptions;

Type: projen.github.workflows.StatusOptions

Runs your workflow anytime the status of a Git commit changes, which triggers the status event.

`watch`^Optional

public readonly watch: WatchOptions;

Type: projen.github.workflows.WatchOptions

Runs your workflow anytime the watch event occurs.

`workflowCall`^Optional

public readonly workflowCall: WorkflowCallOptions;

Type: projen.github.workflows.WorkflowCallOptions

Can be called from another workflow.

https://docs.github.com/en/actions/learn-github-actions/reusing-workflows

`workflowDispatch`^Optional

public readonly workflowDispatch: WorkflowDispatchOptions;

Type: projen.github.workflows.WorkflowDispatchOptions

You can configure custom-defined input properties, default input values, and required inputs for the event directly in your workflow.

When the workflow runs, you can access the input values in the github.event.inputs context.

`workflowRun`^Optional

public readonly workflowRun: WorkflowRunOptions;

Type: projen.github.workflows.WorkflowRunOptions

This event occurs when a workflow run is requested or completed, and allows you to execute a workflow based on the finished result of another workflow.

A workflow run is triggered regardless of the result of the previous workflow.

WatchOptions

Watch options.

Initializer

import { github } from 'projen'

const watchOptions: github.workflows.WatchOptions = { ... }

Properties

Name	Type	Description
`types`	`string[]`	Which activity types to trigger on.

`types`^Optional

public readonly types: string[];

Type: string[]

Which activity types to trigger on.

WorkflowCallInput

An input definition for a workflow_call trigger.

https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#onworkflow_callinputs

Initializer

import { github } from 'projen'

const workflowCallInput: github.workflows.WorkflowCallInput = { ... }

Properties

Name	Type	Description
`type`	`string`	The data type of the input.
`default`	`string \| number \| boolean`	The default value for the input when it is not provided by the caller.
`description`	`string`	A description of the input parameter.
`required`	`boolean`	Whether the input is required.

`type`^Required

public readonly type: string;

Type: string

The data type of the input.

`default`^Optional

public readonly default: string | number | boolean;

Type: string | number | boolean
Default: no default

The default value for the input when it is not provided by the caller.

`description`^Optional

public readonly description: string;

Type: string

A description of the input parameter.

`required`^Optional

public readonly required: boolean;

Type: boolean
Default: false

Whether the input is required.

If true, the caller must supply this input when calling the workflow.

WorkflowCallOptions

Options for the workflow_call trigger event, used to define a reusable workflow.

https://docs.github.com/en/actions/using-workflows/reusing-workflows

Initializer

import { github } from 'projen'

const workflowCallOptions: github.workflows.WorkflowCallOptions = { ... }

Properties

Name	Type	Description
`inputs`	`{[ key: string ]: projen.github.workflows.WorkflowCallInput}`	A map of inputs that are passed from the caller workflow.
`outputs`	`{[ key: string ]: projen.github.workflows.WorkflowCallOutput}`	A map of outputs that the called workflow can set.
`secrets`	`{[ key: string ]: projen.github.workflows.WorkflowCallSecret}`	A map of secrets that can be used in the called workflow.

`inputs`^Optional

public readonly inputs: {[ key: string ]: WorkflowCallInput};

Type: {[ key: string ]: projen.github.workflows.WorkflowCallInput}
Default: no inputs

A map of inputs that are passed from the caller workflow.

Inputs are available in the called workflow using the inputs context.

`outputs`^Optional

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

Type: {[ key: string ]: projen.github.workflows.WorkflowCallOutput}
Default: no outputs

A map of outputs that the called workflow can set.

Called workflow outputs are available to all downstream jobs in the caller workflow.

`secrets`^Optional

public readonly secrets: {[ key: string ]: WorkflowCallSecret};

Type: {[ key: string ]: projen.github.workflows.WorkflowCallSecret}
Default: no secrets

A map of secrets that can be used in the called workflow.

Secrets are available in the called workflow using the secrets context.

WorkflowCallOutput

An output definition for a workflow_call trigger.

https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#onworkflow_calloutputs

Initializer

import { github } from 'projen'

const workflowCallOutput: github.workflows.WorkflowCallOutput = { ... }

Properties

Name	Type	Description
`value`	`string`	The value of the output.
`description`	`string`	A description of the output parameter.

`value`^Required

public readonly value: string;

Type: string

The value of the output.

This must reference a job output from within the reusable workflow, e.g. ${{ jobs.<job_id>.outputs.<output_name> }}.

`description`^Optional

public readonly description: string;

Type: string

A description of the output parameter.

WorkflowCallSecret

A secret definition for a workflow_call trigger.

https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#onworkflow_callsecrets

Initializer

import { github } from 'projen'

const workflowCallSecret: github.workflows.WorkflowCallSecret = { ... }

Properties

Name	Type	Description
`description`	`string`	A description of the secret parameter.
`required`	`boolean`	Whether the secret is required.

`description`^Optional

public readonly description: string;

Type: string

A description of the secret parameter.

`required`^Optional

public readonly required: boolean;

Type: boolean
Default: false

Whether the secret is required.

If true, the caller must supply this secret when calling the workflow.

WorkflowDispatchInput

An input for a workflow_dispatch event.

Initializer

import { github } from 'projen'

const workflowDispatchInput: github.workflows.WorkflowDispatchInput = { ... }

Properties

Name	Type	Description
`description`	`string`	A description of the input.
`default`	`string`	The default value of the input.
`options`	`string[]`	Options for the input if type is 'choice'.
`required`	`boolean`	Whether the input is required.
`type`	`string`	The type of the input.

`description`^Required

public readonly description: string;

Type: string

A description of the input.

`default`^Optional

public readonly default: string;

Type: string
Default: no default

The default value of the input.

`options`^Optional

public readonly options: string[];

Type: string[]
Default: no options

Options for the input if type is 'choice'.

`required`^Optional

public readonly required: boolean;

Type: boolean
Default: false

Whether the input is required.

`type`^Optional

public readonly type: string;

Type: string
Default: "string"

The type of the input.

WorkflowDispatchOptions

The Workflow dispatch event options.

Initializer

import { github } from 'projen'

const workflowDispatchOptions: github.workflows.WorkflowDispatchOptions = { ... }

Properties

Name	Type	Description
`inputs`	`{[ key: string ]: projen.github.workflows.WorkflowDispatchInput}`	Inputs for the workflow_dispatch event.

`inputs`^Optional

public readonly inputs: {[ key: string ]: WorkflowDispatchInput};

Type: {[ key: string ]: projen.github.workflows.WorkflowDispatchInput}

Inputs for the workflow_dispatch event.

WorkflowRunOptions

Workflow run options.

Initializer

import { github } from 'projen'

const workflowRunOptions: github.workflows.WorkflowRunOptions = { ... }

Properties

Name	Type	Description
`branches`	`string[]`	Which branches or branch-ignore to limit the trigger to.
`types`	`string[]`	Which activity types to trigger on.
`workflows`	`string[]`	Which workflow to trigger on.

`branches`^Optional

public readonly branches: string[];

Type: string[]

Which branches or branch-ignore to limit the trigger to.

`types`^Optional

public readonly types: string[];

Type: string[]

Which activity types to trigger on.

`workflows`^Optional

public readonly workflows: string[];

Type: string[]

Which workflow to trigger on.

Enums

AppPermission

The permissions available for an access token for a GitHub App.

Members

Name	Description
`READ`	Read-only acccess.
`WRITE`	Read-write access.
`ADMIN`	Read-write and admin access.

`READ`

Read-only acccess.

`WRITE`

Read-write access.

`ADMIN`

Read-write and admin access.

Not all permissions support admin.

JobPermission

Access level for workflow permission scopes.

Members

Name	Description
`READ`	Read-only access.
`WRITE`	Read-write access.
`NONE`	No access at all.

`READ`

Read-only access.

`WRITE`

Read-write access.

`NONE`

No access at all.

Structs ​

AppPermissions ​

Initializer ​

Properties ​

actionsOptional ​

administrationOptional ​

attestationsOptional ​

checksOptional ​

codespacesOptional ​

contentsOptional ​

dependabotSecretsOptional ​

deploymentsOptional ​

emailAddressesOptional ​

environmentsOptional ​

followersOptional ​

gitSshKeysOptional ​

gpgKeysOptional ​

interactionLimitsOptional ​

issuesOptional ​

membersOptional ​

metadataOptional ​

organizationAdministrationOptional ​

organizationAnnouncementBannersOptional ​

organizationCopilotSeatManagementOptional ​

organizationCustomOrgRolesOptional ​

organizationCustomPropertiesOptional ​

organizationCustomRolesOptional ​

organizationEventsOptional ​

organizationHooksOptional ​

organizationPackagesOptional ​

organizationPersonalAccessTokenRequestsOptional ​

organizationPersonalAccessTokensOptional ​

organizationPlanOptional ​

organizationProjectsOptional ​

organizationSecretsOptional ​

organizationSelfHostedRunnersOptional ​

orgnaizationUserBlockingOptional ​

packagesOptional ​

pagesOptional ​

profileOptional ​

pullRequestsOptional ​

repositoryCustomPropertiesOptional ​

repositoryHooksOptional ​

repositoryProjectsOptional ​

secretsOptional ​

secretScanningAlertsOptional ​

securityEventsOptional ​

singleFileOptional ​

starringOptional ​

statusesOptional ​

teamDiscussionsOptional ​

vulnerabilityAlertsOptional ​

workflowsOptional ​

BranchProtectionRuleOptions ​

Initializer ​

Properties ​

typesOptional ​

CheckRunOptions ​

Initializer ​

Properties ​

typesOptional ​

CheckSuiteOptions ​

Initializer ​

Properties ​

typesOptional ​

CommonJobDefinition ​

Initializer ​

Properties ​

permissionsRequired ​

concurrencyOptional ​

ifOptional ​

nameOptional ​

needsOptional ​

strategyOptional ​

ContainerCredentials ​

Initializer ​

Properties ​

passwordRequired ​

usernameRequired ​

ContainerOptions ​

Structs

AppPermissions

Initializer

Properties

`actions`^Optional

`administration`^Optional

`attestations`^Optional

`checks`^Optional

`codespaces`^Optional

`contents`^Optional

`dependabotSecrets`^Optional

`deployments`^Optional

`emailAddresses`^Optional

`environments`^Optional

`followers`^Optional

`gitSshKeys`^Optional

`gpgKeys`^Optional

`interactionLimits`^Optional

`issues`^Optional

`members`^Optional

`metadata`^Optional

`organizationAdministration`^Optional

`organizationAnnouncementBanners`^Optional

`organizationCopilotSeatManagement`^Optional

`organizationCustomOrgRoles`^Optional

`organizationCustomProperties`^Optional

`organizationCustomRoles`^Optional

`organizationEvents`^Optional

`organizationHooks`^Optional

`organizationPackages`^Optional

`organizationPersonalAccessTokenRequests`^Optional

`organizationPersonalAccessTokens`^Optional

`organizationPlan`^Optional

`organizationProjects`^Optional

`organizationSecrets`^Optional

`organizationSelfHostedRunners`^Optional

`orgnaizationUserBlocking`^Optional

`packages`^Optional

`pages`^Optional

`profile`^Optional

`pullRequests`^Optional

`repositoryCustomProperties`^Optional

`repositoryHooks`^Optional

`repositoryProjects`^Optional

`secrets`^Optional

`secretScanningAlerts`^Optional

`securityEvents`^Optional

`singleFile`^Optional

`starring`^Optional

`statuses`^Optional

`teamDiscussions`^Optional

`vulnerabilityAlerts`^Optional

`workflows`^Optional

BranchProtectionRuleOptions

Initializer

Properties

`types`^Optional

CheckRunOptions

Initializer

Properties

`types`^Optional

CheckSuiteOptions

Initializer

Properties

`types`^Optional

CommonJobDefinition

Initializer

Properties

`permissions`^Required

`concurrency`^Optional

`if`^Optional

`name`^Optional

`needs`^Optional

`strategy`^Optional

ContainerCredentials

Initializer

Properties

`password`^Required

`username`^Required

ContainerOptions