Merge pull request #23078 from github/repo-sync

repo sync

content/actions/security-guides/security-hardening-for-github-actions.md

@@ -193,6 +193,14 @@ You can help mitigate this risk by following these good practices:
 The same principles described above for using third-party actions also apply to using third-party workflows. You can help mitigate the risks associated with reusing workflows by following the same good practices outlined above. For more information, see "[Reusing workflows](/actions/learn-github-actions/reusing-workflows)."
 {% endif %}
 
+{% ifversion required-workflows %}
+
+## Required workflows
+
+Required workflows allow you to specify workflows to run on selected repositories or all repositories in your organization, providing the ability to enforce organization-wide security policies while only maintaining a single workflow. Required workflows appear as required status checks on pull requests and the checks must succeed before the pull request can be merged. For more information, see "[Required workflows](/actions/using-workflows/required-workflows)."
+
+{% endif %}
+
 {% ifversion internal-actions %}
 ## Allowing workflows to access internal {% ifversion private-actions %}and private {% endif %}repositories
 

content/actions/using-workflows/index.md

@@ -27,6 +27,7 @@ children:
   - /workflow-syntax-for-github-actions
   - /workflow-commands-for-github-actions
   - /reusing-workflows
+  - /required-workflows
   - /caching-dependencies-to-speed-up-workflows
   - /storing-workflow-data-as-artifacts
   - /creating-starter-workflows-for-your-organization

content/actions/using-workflows/required-workflows.md

@@ -0,0 +1,55 @@
+---
+title: Required workflows
+shortTitle: Required workflows
+intro: "You can specify which workflows will run as required status checks in all repositories or selected repositories in your organization."
+miniTocMaxHeadingLevel: 3
+versions:
+  feature: 'required-workflows'
+type: how_to
+topics:
+  - Workflows
+---
+
+{% data reusables.actions.workflows.required-workflow-beta %}
+
+## 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](/assets/images/help/settings/example-required-workflow.png)
+
+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:
+
+{% data reusables.actions.workflows.required-workflow-prerequisites %}
+
+## Restrictions and behaviors for the source repository
+
+Note the following restrictions and behaviors for the source repository and workflow:
+
+{% data reusables.actions.workflows.required-workflow-source-notes %}
+
+## Restrictions and behaviors for the target repository
+
+Note the following restrictions and behaviors for the target repositories:
+
+{% data reusables.actions.workflows.required-workflow-target-notes %}
+
+## 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.
+
+{% data reusables.repositories.navigate-to-repo %}
+{% data reusables.repositories.actions-tab %}
+1. In the left sidebar, you can view workflow runs for required workflows under "Required workflows."
+
+   ![Screenshot showing required workflows](/assets/images/help/settings/view-required-workflows.png)
+
+
+
+## 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](/organizations/managing-organization-settings/disabling-or-limiting-github-actions-for-your-organization#adding-a-required-workflow-to-an-organization)."

content/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization.md

@@ -499,6 +499,11 @@ For more information, see "[Managing the publication of {% data variables.produc
 | `remove_self_hosted_runner` | Triggered when a self-hosted runner is removed. For more information, see "[Removing a runner from an organization](/actions/hosting-your-own-runners/removing-self-hosted-runners#removing-a-runner-from-an-organization)." {% ifversion ghec %}
 | `revoke_external_identity` | Triggered when an organization owner revokes a member's linked identity. For more information, see "[Viewing and managing a member's SAML access to your organization](/organizations/granting-access-to-your-organization-with-saml-single-sign-on/viewing-and-managing-a-members-saml-access-to-your-organization#viewing-and-revoking-a-linked-identity)."
 | `revoke_sso_session` | Triggered when an organization owner revokes a member's SAML session. For more information, see "[Viewing and managing a member's SAML access to your organization](/organizations/granting-access-to-your-organization-with-saml-single-sign-on/viewing-and-managing-a-members-saml-access-to-your-organization#viewing-and-revoking-a-linked-identity)." {% endif %}
+{%- ifversion required-workflows %}
+| `required_workflow_create` | Triggered when a required workflow is created. For more information, see "[Required workflows](/actions/using-workflows/required-workflows)."
+| `required_workflow_update` | Triggered when a required workflow is updated. For more information, see "[Required workflows](/actions/using-workflows/required-workflows)."
+| `required_workflow_delete` | Triggered when a required workflow is deleted. For more information, see "[Required workflows](/actions/using-workflows/required-workflows)."
+{%- endif %}
 | `runner_group_created` | Triggered when a self-hosted runner group is created. For more information, see "[Creating a self-hosted runner group for an organization](/actions/hosting-your-own-runners/managing-access-to-self-hosted-runners-using-groups#creating-a-self-hosted-runner-group-for-an-organization)."
 | `runner_group_removed` | Triggered when a self-hosted runner group is removed. For more information, see "[Removing a self-hosted runner group](/actions/hosting-your-own-runners/managing-access-to-self-hosted-runners-using-groups#removing-a-self-hosted-runner-group)."
 | `runner_group_updated` | Triggered when the configuration of a self-hosted runner group is changed. For more information, see "[Changing the access policy of a self-hosted runner group](/actions/hosting-your-own-runners/managing-access-to-self-hosted-runners-using-groups#changing-the-access-policy-of-a-self-hosted-runner-group)."

content/organizations/managing-organization-settings/disabling-or-limiting-github-actions-for-your-organization.md

@@ -81,6 +81,57 @@ You can configure this behavior for an organization using the procedure below. M
 {% data reusables.actions.workflow-run-approve-link %}
 {% endif %}
 
+{% ifversion required-workflows %}
+
+## Adding a required workflow to an organization
+
+{% data reusables.actions.workflows.required-workflow-beta %}
+
+You can configure required workflows to run in all or selected repositories in an organization where you are an owner. Required workflows are triggered by pull requests and must pass before a pull request can be merged. For more information, see "[Required workflows](/actions/using-workflows/required-workflows)."
+
+#### Prerequisites
+
+Before configuring a required workflow, note the following prerequisites:
+
+{% data reusables.actions.workflows.required-workflow-prerequisites %}
+
+#### Restrictions and behaviors for the source repository
+
+Note the following restrictions and behaviors for the source repository and workflow:
+
+{% data reusables.actions.workflows.required-workflow-source-notes %}
+
+#### Restrictions and behaviors for the target repository
+
+Note the following restrictions and behaviors for the target repositories:
+
+{% data reusables.actions.workflows.required-workflow-target-notes %}
+
+#### Configuring a required workflow for your organization
+
+{% data reusables.profile.access_org %}
+{% data reusables.profile.org_settings %}
+{% data reusables.organizations.settings-sidebar-actions-general %}
+1. Next to "Required Workflows", click **Add workflow**.
+
+   ![Screenshot showing the 'Add workflow' button](/assets/images/help/settings/actions-required-workflows-add.png)
+
+1. Select the repository that contains the workflow and enter the path to the workflow.
+
+   ![Screenshot showing the controls for locating the required workflow](/assets/images/help/settings/actions-required-workflow-locate.png)
+
+1. Under "Apply to repositories...", select **All repositories** to apply the required workflow to all repositories in your organization, or **Selected repositories** to choose which repositories it will apply to.
+
+   ![Screenshot showing the controls for locating the required workflow](/assets/images/help/settings/actions-required-workflows-repos.png)
+
+1. Optionally, if you chose "Selected repositories", click {% octicon "gear" aria-label="The Gear icon" %} to open the repository selection modal, then select the repositories, and click **Apply selection**. You can use filters to narrow down your search.
+
+   ![Screenshot showing the controls for locating the required workflow](/assets/images/help/settings/actions-required-workflows-select-repos.png)
+
+1. To add the required workflow, click **Add workflow**.
+
+{% endif %}
+
 {% ifversion fpt or ghes or ghec %}
 ## Enabling workflows for private repository forks
 

data/features/required-workflows.yml

@@ -0,0 +1,6 @@
+# Issue 8526
+# Required workflows
+versions:
+  fpt: '*'
+  ghec: '*'
+  ghes: '>=3.8'

data/reusables/actions/workflows/required-workflow-beta.md

@@ -0,0 +1,5 @@
+{% note %}
+
+**Note:** Required workflows are currently in beta and subject to change.
+
+{% endnote %}

data/reusables/actions/workflows/required-workflow-prerequisites.md

@@ -0,0 +1,6 @@
+* {% data variables.product.prodname_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 {% data variables.product.prodname_actions %} is disabled in the repository's settings. For more information on managing {% data variables.product.prodname_actions %} in your organization's repositories, see "[Managing GitHub Actions permissions for your organization](/organizations/managing-organization-settings/disabling-or-limiting-github-actions-for-your-organization#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](/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/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](/organizations/managing-organization-settings/managing-the-default-branch-name-for-repositories-in-your-organization)" and "[Changing the default branch](/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/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. {% data variables.product.product_name %} 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.

data/reusables/actions/workflows/required-workflow-source-notes.md

@@ -0,0 +1,4 @@
+* 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 {% ifversion ghes or ghec or ghae %}or internal {% endif %}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](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#managing-access-for-a-private-repository){% ifversion ghes or ghec or ghae %}" and "[Allowing access to components in an internal repository](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#allowing-access-to-components-in-an-internal-repository){% endif %}."
+* 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. {% ifversion ghes or ghec or ghae %} Workflows stored in internal repositories can be configured as required workflows for internal and private repositories in your organization.{% endif %}
+* CodeQL is not supported in required workflows because CodeQL requires configuration at the repository level. For information on configuring code scanning, see "[Setting up code scanning for a repository](/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/setting-up-code-scanning-for-a-repository)."

data/reusables/actions/workflows/required-workflow-target-notes.md

@@ -0,0 +1,3 @@
+* 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. {% ifversion ghes or ghec or ghae %} Required workflows stored in internal repositories will run on internal and private repositories.{% endif %}
+* 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.