Required workflows

Overview

You can configure a workflow that must run in repositories in an organization for all pull requests opened against any target 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 and pull_request_target default events and appears as a required status check, which blocks the ability to merge the pull request until the required workflow succeeds.

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 "Disabling or limiting GitHub Actions 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 Enterprise Server will source the required workflow from a specified branch, tag, or commit SHA 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.
• When a workflow is run as a required workflow it will ignore all the filters in the on: section, for example: branches, branches-ignore, paths, types etc. The required workflow will run only for the pull_request and pull_request_target default events. For more information on default activity types, see "Events that trigger workflows."
• Required workflows are not automatically triggered on already existing pull requests even though they automatically appear as expected checks. To trigger required workflows for an already existing pull request, push a new change to that pull request.

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 or internal repository, you must ensure that workflows within the repository are accessible by other repositories in your organization. For more information, see "Managing GitHub Actions settings for a repository" and "Managing GitHub Actions settings for a 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. Workflows stored in internal repositories can be configured as required workflows for internal and 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 advanced setup for code scanning."

• Required workflows can be referenced using any branch, tag, or commit SHA from the repository containing the workflow file.

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 stored in internal repositories will run on internal and 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 your GitHub Enterprise Server instance, navigate to the main page of the repository.

2. Under your repository name, click Actions.

   

3. In the left sidebar, you can view workflow runs for required workflows under "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."