Skip to main content

Required workflows

You can specify which workflows will run as required status checks in all repositories or selected repositories in your organization.

Note: Required workflows are currently in beta and subject to change.

Overview

You can configure a workflow that must run in repositories in an organization for all pull requests opened against the default branch. Required workflows allow you to implement organization-wide CI/CD policies that apply to current and future repositories. A required workflow is triggered by pull request events and appears as a required status check, which blocks the ability to merge the pull request until the required workflow succeeds.

Screenshot showing the controls for locating the required workflow

Required workflows are not the same as reusable workflows. Reusable workflows can be called by another workflow. Required workflows are enforced on repositories by an organization owner.

Prerequisites

Before configuring a required workflow, note the following prerequisites:

  • GitHub Actions must be enabled for a repository in the organization's settings in order for required workflows to run. Once enabled at an organization-level, required workflows will run even when GitHub Actions is disabled in the repository's settings. For more information on managing GitHub Actions in your organization's repositories, see "Managing GitHub Actions permissions for your organization."
  • Required workflows are available for organizations and only in repositories where the organization's plan supports required status checks. If required status checks are not supported, the workflow will still run, but it will not be a required check and will not block merging. For more information about support for required status checks, see "About protected branches."
  • The repository's default branch must match the organization's default branch setting in order for required workflows to run as required status checks. If the default branch names do not match, the workflow will still run, but it will not be a required check. For more information about managing default branch names, see "Managing the default branch name for repositories in your organization" and "Changing the default branch."
  • For required workflows to run, the pull request's source repository must be in the same organization as the target repository. GitHub will source the required workflow from the HEAD commit of the default branch from the repository containing the workflow.
  • Secrets used in a required workflow should be created at either the organization level or in the target repositories.
  • Secrets in the source repository will not be fetched when a workflow runs in the target repository.

Restrictions and behaviors for the source repository

Note the following restrictions and behaviors for the source repository and workflow:

  • Required workflows can be stored in any repository folder and are not restricted to the .github/workflows folder like normal workflows. If a required workflow calls a reusable workflow, the reusable workflow must be stored in the .github/workflows folder. When calling a reusable workflow, a required workflow must use the full path and ref to the reusable workflow. For example, {owner}/{repo}/.github/workflows/{filename}@{ref}.
  • If the required workflow is contained in a private repository, you must ensure that workflows within the repository are accessible by other repositories in your organization. For more information, see "Allowing access to components in a private repository."
  • Workflows stored in a public repository can be configured as required workflows for any repository in your organization. Workflows stored in a private repository can only be configured as required workflows for other private repositories in your organization.
  • CodeQL is not supported in required workflows because CodeQL requires configuration at the repository level. For information on configuring code scanning, see "Configuring code scanning for a repository."

Restrictions and behaviors for the target repository

Note the following restrictions and behaviors for the target repositories:

  • When configuring a required workflow to run on all or selected repositories, the visibility of the repository containing the required workflow will affect which repositories in your organization the workflow runs on. Required workflows stored in public repositories will run on all repositories. Required workflows stored in private repositories will only run on other private repositories.
  • Required workflows cannot be configured to run in the repository the workflow is created in. You should consider creating a separate repository to store your required workflows.
  • When configuring a required workflow to run on all or selected repositories, required workflows will not run in repositories where actions is disabled in the organization settings.

Viewing workflow runs for required workflows

After a required workflow has run at least once in a repository, you can view its workflow runs in that repository's "Actions" tab. To make changes to what workflows are configured as required in an organization, you must contact an organization owner. To make changes to a required workflow itself, anyone with write permissions for the repository that contains the required workflow can make changes to it.

  1. On GitHub.com, navigate to the main page of the repository.

  2. Under your repository name, click Actions. Actions tab in the main repository navigation

  3. In the left sidebar, you can view workflow runs for required workflows under "Required workflows."

    Screenshot showing required workflows

Adding a required workflow to an organization

Organization owners can configure required workflows in their organization. For more information, see "Disabling or limiting GitHub Actions for your organization."