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

`repositoryAnnouncementBanners`^Optional

Deprecated: removed by GitHub

public readonly repositoryAnnouncementBanners: 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.

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 \| 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 | boolean};

Type: {[ key: string ]: string | 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.
`repositoryProjects`	`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

`repositoryProjects`^Optional

Deprecated: removed by GitHub

public readonly repositoryProjects: 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.
`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.
`continueOnError`	`boolean`	Prevents a job from failing when a step fails.
`timeoutMinutes`	`number`	The maximum number of minutes to run the step before killing the process.

`env`^Optional

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

Type: {[ key: string ]: string}

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

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

`id`^Optional

public readonly id: string;

Type: string

A unique identifier for the step.

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

`if`^Optional

public readonly if: string;

Type: string

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

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

`name`^Optional

public readonly name: string;

Type: string

A name for your step to display on GitHub.

`workingDirectory`^Optional

public readonly workingDirectory: string;

Type: string

Specifies a working directory for a step.

Overrides a job's working directory.

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

`continueOnError`^Optional

public readonly continueOnError: boolean;

Type: boolean

Prevents a job from failing when a step fails.

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

`timeoutMinutes`^Optional

public readonly timeoutMinutes: number;

Type: number

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

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.
`workingDirectory`	`string`	Specifies a working directory for a step.
`continueOnError`	`boolean`	Prevents a job from failing when a step fails.
`timeoutMinutes`	`number`	The maximum number of minutes to run the step before killing the process.

`env`^Optional

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

Type: {[ key: string ]: string}

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

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

`id`^Optional

public readonly id: string;

Type: string

A unique identifier for the step.

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

`if`^Optional

public readonly if: string;

Type: string

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

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

`name`^Optional

public readonly name: string;

Type: string

A name for your step to display on GitHub.

`workingDirectory`^Optional

public readonly workingDirectory: string;

Type: string

Specifies a working directory for a step.

Overrides a job's working directory.

`continueOnError`^Optional

public readonly continueOnError: boolean;

Type: boolean

Prevents a job from failing when a step fails.

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

`timeoutMinutes`^Optional

public readonly timeoutMinutes: number;

Type: number

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

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

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

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

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

`version`^Required

public readonly version: string;

Type: string

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.ToolRequirement`	Setup java (temurin distribution).
`node`	`projen.github.workflows.ToolRequirement`	Setup node.js.
`python`	`projen.github.workflows.ToolRequirement`	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: ToolRequirement;

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

Setup java (temurin distribution).

`node`^Optional

public readonly node: ToolRequirement;

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

Setup node.js.

`python`^Optional

public readonly python: ToolRequirement;

Type: projen.github.workflows.ToolRequirement
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.

WorkflowCallOptions

The Workflow Call event accepts no options.

Initializer

import { github } from 'projen'

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

WorkflowDispatchOptions

The Workflow dispatch event accepts no options.

Initializer

import { github } from 'projen'

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

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.

github.workflows Submodule

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 ​

repositoryAnnouncementBannersOptional ​

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 ​

`github.workflows` Submodule

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

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