Merge pull request github#24372 from github/repo-sync

repo sync

Author: Octomerger

assets/images/help/organizations/settings-button.png

@@ -13,9 +13,7 @@ topics:
 
 ## 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)
+You can configure a workflow that must run in repositories in an organization for all pull requests opened against {% ifversion actions-required-workflow-improvements %}any target branch{% else %}the default branch{% endif %}. 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.
 
 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.
 

assets/images/help/settings/actions-required-workflow-locate.png

@@ -97,21 +97,15 @@ Note the following restrictions and behaviors for the target repositories:
 {% 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**.
+1. To the right of "Required Workflows", click **Add workflow**.
 
-   ![Screenshot showing the 'Add workflow' button](/assets/images/help/settings/actions-required-workflows-add.png)
+1. Under "Required workflow", use the drop-down menu to select the repository that contains the workflow. Then, enter the path to the workflow in the text field. {% ifversion actions-required-workflow-improvements %}You can reference any branch, tag, or commit SHA from the repository containing the workflow file using the `{path}@{ref}` syntax.
 
-1. Select the repository that contains the workflow and enter the path to the workflow.
+1. Optionally, to specify target branches on which to enforce the required workflow, enter the branch or multiple branches in the text field under "Target branches". If you do not enter a target branch, the required workflow will be enforced on the default branch for the repository.{% endif %}
 
-   ![Screenshot showing the controls for locating the required workflow](/assets/images/help/settings/actions-required-workflow-locate.png)
+1. Under "Apply to repositories...", use the drop-down menu to select which repositories the required workflow applies to. 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.
 
-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. Optionally, if you chose "Selected repositories", click {% octicon "gear" aria-label="The Gear icon" %} to open the repository selection modal, then use the checkboxes to select the repositories, and click **Apply selection**. You can use filters to narrow down your search.
 
 1. To add the required workflow, click **Add workflow**.
 

assets/images/help/settings/actions-required-workflows-add.png

@@ -0,0 +1,6 @@
+# Reference: #9704 #9701 #9663
+# Documentation improvements to the required workflow beta feature launch
+versions:
+  fpt: '*'
+  ghec: '*'
+  ghes: '>=3.9'

assets/images/help/settings/actions-required-workflows-repos.png

@@ -1,6 +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 "[AUTOTITLE](/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 "[AUTOTITLE](/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 "[AUTOTITLE](/organizations/managing-organization-settings/managing-the-default-branch-name-for-repositories-in-your-organization)" and "[AUTOTITLE](/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.
+* 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 {% ifversion actions-required-workflow-improvements %}a specified branch, tag, or commit SHA {% else %}the HEAD commit of the default branch {% endif %}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.