Documentation for GitHub Actions required workflow deprecation (#48981)

Author: jc-clark

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

@@ -3,8 +3,8 @@ 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.
 versions:
-  feature: required-workflows
-permissions: Because this feature is being deprecated, this article is only relevant if you are already using required workflows for {% data variables.product.prodname_actions %}.
+  feature: required-workflows-deprecation
+permissions: Because {% data variables.product.company_short %} no longer supports this feature, this article is only relevant if you are already using required workflows for {% data variables.product.prodname_actions %}.
 type: how_to
 topics:
   - Workflows

content/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review.md

@@ -85,7 +85,7 @@ The best practices you should take will depend on whether you use {% data variab
 
 If you use {% data variables.product.prodname_actions %} to access the {% data variables.dependency-submission-api.name %} or the dependency review API:
    - Make sure you run all of your dependency submission actions in the same {% data variables.product.prodname_actions %} workflow as your {% data variables.dependency-review.action_name %}. This will give you control over the order of execution, and it will ensure that dependency review will always work.
-   - If you do choose to run the {% data variables.dependency-review.action_name %} separately, for instance, as a required workflow, you should:
+   - If you do choose to run the {% data variables.dependency-review.action_name %} separately, you should:
      - Set `retry-on-snapshot-warnings` to `true`.
      - Set `retry-on-snapshot-warnings-timeout` to slightly exceed the typical run time (in seconds) of your longest-running dependency submission action.
 

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

@@ -101,7 +101,7 @@ You can configure this behavior for an organization using the procedure below. M
 {% data reusables.actions.workflow-run-approve-link %}
 {% endif %}
 
-{% ifversion required-workflows %}
+{% ifversion required-workflows-deprecation %}
 
 ## Adding a required workflow to an organization
 

content/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/troubleshooting-required-status-checks.md

@@ -55,7 +55,7 @@ If there is a conflict between the test merge commit and head commit, the checks
 
 **Warning:** If a workflow is skipped due to [path filtering](/actions/using-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore), [branch filtering](/actions/using-workflows/workflow-syntax-for-github-actions#onpull_requestpull_request_targetbranchesbranches-ignore) or a [commit message](/actions/managing-workflow-runs/skipping-workflow-runs), then checks associated with that workflow will remain in a "Pending" state. A pull request that requires those checks to be successful will be blocked from merging.
 
-For this reason you should not use path or branch filtering to skip workflow runs if the workflow is required. For more information, see "[AUTOTITLE](/actions/managing-workflow-runs/skipping-workflow-runs){% ifversion required-workflows %}" and "[AUTOTITLE](/actions/using-workflows/required-workflows){% endif %}."
+{% data reusables.pull_requests.path-filtering-required-workflows %}
 
 If, however, a job within a workflow is skipped due to a conditional, it will report its status as "Success". For more information, see "[AUTOTITLE](/actions/using-jobs/using-conditions-to-control-job-execution)."
 
@@ -91,7 +91,7 @@ jobs:
 
 Due to [path filtering](/actions/using-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore), a pull request that only changes a file in the root of the repository will not trigger this workflow and is blocked from merging. On the pull request, you would see "Waiting for status to be reported."
 
-It is recommended that you do not use path filtering (as shown in the previous example), or branch filtering, in a workflow that has been configured to be required. {% ifversion required-workflows %}For more information, see "[AUTOTITLE](/actions/using-workflows/required-workflows)."{% endif %}
+{% data reusables.pull_requests.path-filtering-required-workflows %}
 
 ## Required status checks from unexpected sources
 

content/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets.md

@@ -148,12 +148,6 @@ If a site administrator has blocked force pushes to the default branch only, you
 
 ## Require workflows to pass before merging
 
-{% note %}
-
-**Note:** This rule is replacing required workflows for {% data variables.product.prodname_actions %}. You can read more about this change on the [{% data variables.product.company_short %} blog](https://github.blog/changelog/2023-08-02-github-actions-required-workflows-will-move-to-repository-rules/).
-
-{% endnote %}
-
 You can require all changes made to a targeted branch to pass specified workflows before they can be merged. This rule can only be configured at the organization level.
 
 To use this rule, you must first create a workflow file. The workflow file needs to be in a repository that matches the visibility of the repositories you want to run it in. Specifically, a public workflow can run on any repository in your organization, an internal workflow can only run on internal and private repositories, and a private workflow can only run on private repositories. For more information, see "[AUTOTITLE](/actions/using-workflows/about-workflows)."

data/features/required-workflows-deprecation.yml

@@ -0,0 +1,4 @@
+# Issue 10754
+# Versioning for deprecating the GitHub Actions required workflows docs
+versions:
+  ghes: '< 3.12'

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

@@ -1,10 +1,9 @@
 {% note %}
 
-**Note:** {% data variables.product.company_short %} is deprecating support for required workflows for {% data variables.product.prodname_actions %}.{% ifversion repo-rules-required-workflows %} Use repository rulesets instead.
+**Note:** {% data variables.product.company_short %} no longer supports required workflows for {% data variables.product.prodname_actions %}. To require workflows to pass before merging, upgrade {% data variables.location.product_location %} to the latest version and use repository rulesets instead.
 
-For more information about repository rulesets, see "[AUTOTITLE](/enterprise-cloud@latest/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#require-workflows-to-pass-before-merging)." You can read more about this change on the [{% data variables.product.company_short %} blog](https://github.blog/changelog/2023-08-02-github-actions-required-workflows-will-move-to-repository-rules/).{% endif %}{% ifversion fpt %} Upgrade to {% data variables.product.prodname_ghe_cloud %} and use repository rulesets instead. For more information, see "[AUTOTITLE](/billing/managing-the-plan-for-your-github-account/upgrading-your-accounts-plan)."
+For more information about upgrading {% data variables.location.product_location %}, see "[AUTOTITLE](/admin/overview/about-upgrades-to-new-releases)."
 
-For more information about repository rulesets, see "[AUTOTITLE](/enterprise-cloud@latest/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#require-workflows-to-pass-before-merging)." You can read more about this change on the [{% data variables.product.company_short %} blog](https://github.blog/changelog/2023-08-02-github-actions-required-workflows-will-move-to-repository-rules/).
-{% endif %}
+For more information about repository rulesets, see "[AUTOTITLE](/enterprise-server@latest/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#require-workflows-to-pass-before-merging)."
 
 {% endnote %}

data/reusables/actions/workflows/section-triggering-a-workflow-branches.md

@@ -18,19 +18,15 @@ The patterns defined in `branches` are evaluated against the Git ref's name. For
 on:
   pull_request:
     # Sequence of patterns matched against refs/heads
-    branches:    
+    branches:
       - main
       - 'mona/octocat'
       - 'releases/**'
 ```
 
-{% note %}
+{% data reusables.pull_requests.path-filtering-required-workflows %}
 
-**Note:** {% ifversion required-workflows %}You should not use branch filtering to skip workflow runs if the workflow has been configured to be required. For more information, see "[AUTOTITLE](/actions/using-workflows/required-workflows)."
-
-{% endif %}If a workflow is skipped due to branch filtering, [path filtering](/actions/using-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore), or a [commit message](/actions/managing-workflow-runs/skipping-workflow-runs), then checks associated with that workflow will remain in a "Pending" state. A pull request that requires those checks to be successful will be blocked from merging.
-
-{% endnote %}
+If a workflow is skipped due to branch filtering, [path filtering](/actions/using-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore), or a [commit message](/actions/managing-workflow-runs/skipping-workflow-runs), then checks associated with that workflow will remain in a "Pending" state. A pull request that requires those checks to be successful will be blocked from merging.
 
 #### Example: Excluding branches
 
@@ -43,7 +39,7 @@ When a pattern matches the `branches-ignore` pattern, the workflow will not run.
 on:
   pull_request:
     # Sequence of patterns matched against refs/heads
-    branches-ignore:    
+    branches-ignore:
       - 'mona/octocat'
       - 'releases/**-alpha'
 ```
@@ -64,7 +60,7 @@ The following workflow will run on `pull_request` events for pull requests that
 ```yaml
 on:
   pull_request:
-    branches:    
+    branches:
       - 'releases/**'
       - '!releases/**-alpha'
 ```

data/reusables/actions/workflows/section-triggering-a-workflow-paths.md

@@ -27,13 +27,9 @@ on:
       - '**.js'
 ```
 
-{% note %}
-
-**Note:** {% ifversion required-workflows %}You should not use path filtering to skip workflow runs if the workflow has been configured to be required. For more information, see "[AUTOTITLE](/actions/using-workflows/required-workflows)."
+{% data reusables.pull_requests.path-filtering-required-workflows %}
 
-{% endif %}If a workflow is skipped due to path filtering, [branch filtering](/actions/using-workflows/workflow-syntax-for-github-actions#onpull_requestpull_request_targetbranchesbranches-ignore), or a [commit message](/actions/managing-workflow-runs/skipping-workflow-runs), then checks associated with that workflow will remain in a "Pending" state. A pull request that requires those checks to be successful will be blocked from merging.
-
-{% endnote %}
+If a workflow is skipped due to path filtering, [branch filtering](/actions/using-workflows/workflow-syntax-for-github-actions#onpull_requestpull_request_targetbranchesbranches-ignore), or a [commit message](/actions/managing-workflow-runs/skipping-workflow-runs), then checks associated with that workflow will remain in a "Pending" state. A pull request that requires those checks to be successful will be blocked from merging.
 
 #### Example: Excluding paths
 

data/reusables/pull_requests/path-filtering-required-workflows.md

@@ -0,0 +1,11 @@
+{% ifversion required-workflows-deprecation %}
+
+You should not use path or branch filtering to skip workflow runs if the workflow is required. For more information, see "[AUTOTITLE](/actions/managing-workflow-runs/skipping-workflow-runs){% ifversion required-workflows %}" and "[AUTOTITLE](/actions/using-workflows/required-workflows){% endif %}."
+
+{% endif %}
+
+{% ifversion repo-rules-required-workflows %}
+
+You should not use path or branch filtering to skip workflow runs if the workflow is required to pass before merging. For more information, see "[AUTOTITLE](/actions/managing-workflow-runs/skipping-workflow-runs)" and "[AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#require-workflows-to-pass-before-merging)."
+
+{% endif %}