projen/lib/github/github.d.ts

CDK for software projects

import { GitHubActionsProvider } from "./actions-provider";
import type { DependabotOptions } from "./dependabot";
import { Dependabot } from "./dependabot";
import type { DependencyReviewOptions } from "./dependency-review";
import { GithubCredentials } from "./github-credentials";
import type { MergeQueueOptions } from "./merge-queue";
import { MergeQueue } from "./merge-queue";
import type { MergifyOptions } from "./mergify";
import { Mergify } from "./mergify";
import { PullRequestTemplate } from "./pr-template";
import type { PullRequestBackportOptions } from "./pull-request-backport";
import type { PullRequestLintOptions } from "./pull-request-lint";
import { CheckoutSubmodules } from "./workflow-steps";
import { GithubWorkflow } from "./workflows";
import { Component } from "../component";
import type { Project } from "../project";
import type { GroupRunnerOptions, RunsOnConfig, RunsOnOptions } from "../runner-options";
export interface GitHubOptions {
    /**
     * Whether mergify should be enabled on this repository or not.
     *
     * @default true
     */
    readonly mergify?: boolean;
    /**
     * Options for Mergify.
     *
     * @default - default options
     */
    readonly mergifyOptions?: MergifyOptions;
    /**
     * Whether a merge queue should be used on this repository to merge pull requests.
     * Requires additional configuration of the repositories branch protection rules.
     *
     * @default false
     */
    readonly mergeQueue?: boolean;
    /**
     * Options for MergeQueue.
     *
     * @default - default options
     */
    readonly mergeQueueOptions?: MergeQueueOptions;
    /**
     * Enables GitHub workflows. If this is set to `false`, workflows will not be created.
     *
     * @default true
     */
    readonly workflows?: boolean;
    /**
     * Add a workflow that allows backport of PRs to other branches using labels.
     * When opening a new PR add a backport label to it,
     * and the PR will be backported to the target branches once the PR is merged.
     *
     * Should not be used together with mergify.
     *
     * @default false
     */
    readonly pullRequestBackport?: boolean;
    /**
     * Options for configuring pull request backport.
     *
     * @default - see defaults in `PullRequestBackportOptions`
     */
    readonly pullRequestBackportOptions?: PullRequestBackportOptions;
    /**
     * Add a workflow that performs basic checks for pull requests, like
     * validating that PRs follow Conventional Commits.
     *
     * @default true
     */
    readonly pullRequestLint?: boolean;
    /**
     * Options for configuring a pull request linter.
     *
     * @default - see defaults in `PullRequestLintOptions`
     */
    readonly pullRequestLintOptions?: PullRequestLintOptions;
    /**
     * Choose a method of providing GitHub API access for projen workflows.
     *
     * @default - use a personal access token named PROJEN_GITHUB_TOKEN
     */
    readonly projenCredentials?: GithubCredentials;
    /**
     * Download files in LFS in workflows
     *
     * @default true if the associated project has `lfsPatterns`, `false` otherwise
     */
    readonly downloadLfs?: boolean;
    /**
     * Enable the dependency-review-action workflow on pull requests.
     *
     * Adds a separate workflow that runs `actions/dependency-review-action`
     * to scan pull requests for newly introduced vulnerable or non-compliant
     * dependencies.
     *
     * @default false
     */
    readonly dependencyReview?: boolean;
    /**
     * Options for the dependency review workflow.
     *
     * Only used when `dependencyReview` is `true`.
     *
     * @default - default options
     */
    readonly dependencyReviewOptions?: DependencyReviewOptions;
    /**
     * Whether to checkout Git submodules.
     *
     * @default CheckoutSubmodules.DISABLED
     */
    readonly checkoutSubmodules?: CheckoutSubmodules;
    /**
     * Github Runner selection labels
     * @default ["ubuntu-latest"]
     * @description Defines a target Runner by labels for all workflows.
     * Can be overridden on a per-component basis.
     * @throws {Error} if both `workflowRunsOn` and `workflowRunsOnGroup` are specified
     */
    readonly workflowRunsOn?: string[];
    /**
     * Github Runner Group selection options
     * @description Defines a target Runner Group by name and/or labels for all workflows.
     * Can be overridden on a per-component basis.
     * @throws {Error} if both `workflowRunsOn` and `workflowRunsOnGroup` are specified
     */
    readonly workflowRunsOnGroup?: GroupRunnerOptions;
}
export declare class GitHub extends Component {
    /**
     * Returns the `GitHub` component of a project or `undefined` if the project
     * does not have a GitHub component.
     */
    static of(project: Project): GitHub | undefined;
    /**
     * The `Mergify` component configured on this repository
     * This is `undefined` if Mergify is not enabled for this repository.
     */
    readonly mergify?: Mergify;
    /**
     * The `MergeQueue` component configured on this repository
     * This is `undefined` if merge queues are not enabled for this repository.
     */
    readonly mergeQueue?: MergeQueue;
    /**
     * Are workflows enabled?
     */
    readonly workflowsEnabled: boolean;
    /**
     * GitHub API authentication method used by projen workflows.
     */
    readonly projenCredentials: GithubCredentials;
    /**
     * The GitHub Actions provider used to manage the versions of actions used in steps
     */
    readonly actions: GitHubActionsProvider;
    private readonly _downloadLfs?;
    private readonly _checkoutSubmodules?;
    private readonly _workflowRunsOn?;
    private readonly _workflowRunsOnGroup?;
    constructor(project: Project, options?: GitHubOptions);
    /**
     * All workflows.
     */
    get workflows(): GithubWorkflow[];
    /**
     * Adds a workflow to the project.
     * @param name Name of the workflow
     * @returns a GithubWorkflow instance
     */
    addWorkflow(name: string): GithubWorkflow;
    addPullRequestTemplate(...content: string[]): PullRequestTemplate;
    addDependabot(options?: DependabotOptions): Dependabot;
    /**
     * Finds a GitHub workflow by name. Returns `undefined` if the workflow cannot be found.
     * @param name The name of the GitHub workflow
     */
    tryFindWorkflow(name: string): undefined | GithubWorkflow;
    /**
     * Whether downloading from LFS is enabled for this GitHub project
     */
    get downloadLfs(): boolean;
    /**
     * Whether checking out Git submodules is enabled for this GitHub project.
     */
    get checkoutSubmodules(): CheckoutSubmodules;
    /**
     * Resolves the `runsOn`/`runsOnGroup` config for a job, falling back to the
     * project's global runner selection (`workflowRunsOn`/`workflowRunsOnGroup`)
     * when `options` does not specify one.
     * @param options per-job runner selection that takes precedence over the
     * project's global default
     */
    runsOnConfig(options?: RunsOnOptions): RunsOnConfig;
}