Add documentation for custom deployment protection rules (#36385)

Co-authored-by: SiaraMist <siaramist@github.com>
Co-authored-by: Usha N <n-usha@github.com>
Co-authored-by: Siara <108543037+SiaraMist@users.noreply.github.com>
Co-authored-by: Dylan Smith <dylanatsmith@github.com>
Co-authored-by: Alexis Abril <alexisabril@github.com>
Co-authored-by: Dylan Geraci <67774922+heavymachinery@users.noreply.github.com>

content/actions/deployment/about-deployments/deploying-with-github-actions.md

@@ -11,6 +11,7 @@ redirect_from:
   - /actions/deployment/deploying-with-github-actions
 topics:
   - CD
+  - Deployment
 shortTitle: Deploy with GitHub Actions
 ---
 
@@ -114,7 +115,7 @@ You can also use `cancel-in-progress` to cancel any currently running job or wor
 ```yaml
 name: Deployment
 
-concurrency: 
+concurrency:
   group: production
   cancel-in-progress: true
 

content/actions/deployment/index.md

@@ -12,6 +12,7 @@ children:
   - /deploying-to-your-cloud-provider
   - /security-hardening-your-deployments
   - /targeting-different-environments
+  - /protecting-deployments
   - /managing-your-deployments
   - /deploying-xcode-applications
 ---

content/actions/deployment/protecting-deployments/configuring-custom-deployment-protection-rules.md

@@ -0,0 +1,55 @@
+---
+title: Configuring custom deployment protection rules
+shortTitle: Configure custom protection rules
+intro: Use {% data variables.product.prodname_github_apps %} to automate protecting deployments with third-party systems.
+versions:
+  fpt: '*'
+  ghec: '*'
+  ghes: '>=3.10'
+topics:
+  - Actions
+  - CD
+  - Deployment
+---
+
+{% data reusables.actions.custom-deployment-protection-rules-beta-note %}
+
+## About custom deployment protection rules
+
+Custom deployment protection rules are powered by {% data variables.product.prodname_github_apps %}. Once a deployment protection rule is configured and installed in a repository, it can be enabled for any environments in the repository.
+
+After you enable a custom deployment protection rule on an environment, every time a workflow step targets that environment, the deployment protection rule will run automatically. For more information about targeting an environment for deployments, see "[AUTOTITLE](/actions/deployment/targeting-different-environments/using-environments-for-deployment)."
+
+For more information about creating your own custom deployment protection rules, see "[AUTOTITLE](/actions/deployment/protecting-deployments/creating-custom-deployment-protection-rules)."
+
+{% data reusables.actions.custom-deployment-protection-rules-limits %}
+
+## Using existing custom deployment protection rules
+
+You can choose to create your own custom deployment protection rules or you may use any existing custom deployment protection rules.
+
+The following is a list of official partner implementations for deployment protection rules.
+
+- Datadog: you can enforce protection rules on your {% data variables.product.prodname_actions %} deployment workflows using Datadog monitors. For more information, see [Gating your {% data variables.product.prodname_actions %} Deployments with Datadog Monitors](https://docs.datadoghq.com/continuous_integration/guides/github_gating/) in the Datadog documentation.
+- Honeycomb: you can define thresholds to reject or approve deployments based on data you are sending to Honeycomb. For more information, see [the Honeycomb app](https://github.com/apps/honeycomb-io) in the {% data variables.product.prodname_marketplace %}.
+- New Relic: for more information, see [the New Relic app](https://github.com/apps/new-relic-gate) in the {% data variables.product.prodname_marketplace %}.
+- NCM NodeSource: for more information, see [the NCM NodeSource app](https://github.com/apps/ncm-nodesource) in the {% data variables.product.prodname_marketplace %}.
+- Sentry: for more information see [the Sentry Deployment Gate app](https://github.com/apps/sentry-deployment-gate) in the {% data variables.product.prodname_marketplace %}.
+- ServiceNow: for more information see [DevOps](https://www.servicenow.com/products/devops.html) in the ServiceNow documentation.
+
+## Prerequisites
+
+In order for a custom deployment protection rule to be available to all environments in a repository, you must first install the custom deployment protection rule on the repository. For more information, see "[AUTOTITLE](/apps/maintaining-github-apps/installing-github-apps)."
+
+After a custom deployment protection rule has been installed in a repository, it must be enabled for each environment where you want the rule to apply.
+
+## Enabling custom deployment protection rules for the environment
+
+{% data reusables.repositories.navigate-to-repo %}
+{% data reusables.repositories.sidebar-settings %}
+{% data reusables.actions.sidebar-environment %}
+1. Select the environment you want to configure.
+1. Under "Deployment protection rules," check the box next to each custom deployment protection rule you want to enable for the environment.
+1. Click **Save protection rules**.
+
+Once a custom deployment protection rule has been enabled for an environment, it will automatically run whenever a workflow reaches a job that references the environment. You can see the results of an approval or rejection for your deployment by reviewing the details of the deployment. For more information, see "[AUTOTITLE](/actions/managing-workflow-runs/reviewing-deployments)."

content/actions/deployment/protecting-deployments/creating-custom-deployment-protection-rules.md

@@ -0,0 +1,80 @@
+---
+title: Creating custom deployment protection rules
+shortTitle: Create custom protection rules
+intro: Use {% data variables.product.prodname_github_apps %} to automate protecting deployments with third-party systems.
+versions:
+  fpt: '*'
+  ghec: '*'
+  ghes: '>=3.10'
+topics:
+  - Actions
+  - CD
+  - Deployment
+---
+
+{% data reusables.actions.custom-deployment-protection-rules-beta-note %}
+
+## About custom deployment protection rules
+
+{% data reusables.actions.about-custom-deployment-protection-rules %}
+
+Custom deployment protection rules are powered by {% data variables.product.prodname_github_apps %} and run based on webhooks and callbacks. Approval or rejection of a workflow job is based on consumption of the `deployment_protection_rule` webhook. For more information, see "[AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads#deployment_protection_rule)" and "[Approving or rejecting deployments](#approving-or-rejecting-deployments)."
+
+Once you have created a custom deployment protection rule and installed it on your repository, the custom deployment protection rule will automatically be available for all environments in the repository.
+
+## Using custom deployment protection rules to approve or reject deployments
+
+Deployments to an environment can be approved or rejected based on the conditions defined in any external service like an approved ticket in an IT Service Management (ITSM) system, vulnerable scan result on dependencies, or stable health metrics of a cloud resource. The decision to approve or reject deployments is at the discretion of the integrating third-party application and the gating conditions you define in them. The following are a few use cases for which you can create a deployment protection rule.
+
+- ITSM & Security Operations: you can check for service readiness by validating quality, security, and compliance processes that verify deployment readiness.
+- Observability systems: you can consult monitoring or observability systems (Asset Performance Management Systems and logging aggregators, cloud resource health verification systems, etc.) for verifying the safety and deployment readiness.
+- Code quality & testing tools: you can check for automated tests on CI builds which need to be deployed to an environment.
+
+Alternatively, you can write your own protection rules for any of the above use cases or you can define any custom logic to safely approve or reject deployments from pre-production to production environments.
+
+## Creating a custom deployment protection rule with {% data variables.product.prodname_github_apps %}
+1. Create a {% data variables.product.prodname_github_app %}. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/creating-a-github-app)." Configure the {% data variables.product.prodname_github_app %} as follows.
+   1. Optionally, in the **Callback URL** text field under "Identifying and authorizing users," enter the callback URL. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/about-the-user-authorization-callback-url)."
+   1. Under "Permissions," select **Repository permissions**.
+   1. To the right of "Actions," click the drop down menu and select **Access: Read-only**.
+   ![A screenshot of the "Repository permissions" section when creating a new GitHub App. The button to configure permissions, with the "read-only" permission selected, for Actions is highlighted by a dark orange rectangle.](/assets/images/help/actions/actions-repo-permissions-read-only.png)
+   1. To the right of "Deployments," click the drop down menu and select **Access: Read and write**.
+   ![A screenshot of the "Deployments" permission settings in the "Repository permissions" section while creating a new GitHub App. The button to configure permissions, with the "read-only" permission selected, for Deployments is highlighted by a dark orange rectangle.](/assets/images/help/actions/actions-deployments-repo-permissions-read-and-write.png)
+   1. Under "Subscribe to events,"f select **Deployment protection rule**.
+   ![A screenshot of the "Subscribe to events section" section while creating a new GitHub App. The checkbox to subscribe to the deployment protection rule event is highlighted by a dark orange rectangle.](/assets/images/help/actions/actions-subscribe-to-events-deployment-protection-rules.png)
+
+1. Install the custom deployment protection rule in your repositories and enable it for use. For more information, see "[AUTOTITLE](/actions/deployment/protecting-deployments/configuring-custom-deployment-protection-rules)."
+
+## Approving or rejecting deployments
+
+Once a workflow reaches a job that references an environment that has the custom deployment protection rule enabled, {% data variables.product.company_short %} sends a `POST` request to a URL you configure containing the `deployment_protection_rule` payload. You can write your deployment protection rule to automatically send REST API requests that approve or reject the deployment based on the `deployment_protection_rule` payload. Configure your REST API requests as follows.
+
+1. Validate the incoming `POST` request. For more information, see "[AUTOTITLE](/webhooks-and-events/webhooks/securing-your-webhooks#validating-payloads-from-github)."
+1. Use a JSON Web Token to authenticate as a {% data variables.product.prodname_github_app %}. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app#about-authentication-as-a-github-app)."
+1. Using the installation ID from the `deployment_protection_rule` webhook payload, generate an install token. For more information, see "[AUTOTITLE](/developers/apps/building-github-apps/authenticating-with-github-apps#authenticating-as-a-github-app)."
+
+   ```shell
+   curl --request POST \
+   --url "{% data variables.product.api_url_code %}/app/installations/INSTALLATION_ID/ACCESS_TOKENS" \
+   --header "Accept: application/vnd.github+json" \
+   --header "Authorization: Bearer {jwt}" \
+   --header "Content-Type: application/json" \
+   --data \
+   '{ \
+      "repository_ids": [321], \
+      "permissions": { \
+         "deployments": "write" \
+      } \
+   }'
+   ```
+1. Optionally, to add a status report without taking any other action to {% data variables.product.prodname_dotcom_the_website %}, send a `POST` request to `/repos/OWNER/REPO/actions/runs/RUN_ID/deployment_protection_rule`. In the request body, omit the `state`. For more information, see "[AUTOTITLE](/rest/actions/workflow-runs#review-custom-deployment-protection-rules-for-a-workflow-run)." You can post a status report on the same deployment up to 10 times. Status reports support Markdown formatting and can be up to 1024 characters long.
+
+1. To approve or reject a request, send a `POST` request to `/repos/OWNER/REPO/actions/runs/RUN_ID/deployment_protection_rule`. In the request body, set the `state` property to either `approved` or `rejected`. For more information, see "[AUTOTITLE](/rest/actions/workflow-runs#review-custom-deployment-protection-rules-for-a-workflow-run)."
+
+1. Optionally, request the status of an approval for a workflow run by sending a `GET` request to `/repositories/REPOSITORY_ID/actions/runs/RUN_ID/approvals`. For more information, see "[AUTOTITLE](/rest/actions/workflow-runs#get-the-review-history-for-a-workflow-run)."
+
+1. Optionally, review the deployment on {% data variables.product.prodname_dotcom_the_website %}. For more information, see "[AUTOTITLE](/actions/managing-workflow-runs/reviewing-deployments)."
+
+## Publishing custom deployment protection rules in the {% data variables.product.prodname_marketplace %}
+
+You can publish your {% data variables.product.prodname_github_app %} to the {% data variables.product.prodname_marketplace %} to allow developers to discover suitable protection rules and install it across their {% data variables.product.company_short %} repositories. Or you can browse existing custom deployment protection rules to suit your needs. For more information, see "[AUTOTITLE](/apps/publishing-apps-to-github-marketplace/github-marketplace-overview/about-github-marketplace)" and "[AUTOTITLE](/apps/publishing-apps-to-github-marketplace/listing-an-app-on-github-marketplace)."

content/actions/deployment/protecting-deployments/index.md

@@ -0,0 +1,13 @@
+---
+title: Protecting your deployments with custom deployment protection rules
+shortTitle: Protect deployments
+intro: You can create and configure custom deployment protection rules to approve or reject deployments across environments with more control and confidence.
+versions:
+  fpt: '*'
+  ghec: '*'
+  ghes: '>=3.10'
+children:
+  - /creating-custom-deployment-protection-rules
+  - /configuring-custom-deployment-protection-rules
+---
+

content/actions/deployment/targeting-different-environments/using-environments-for-deployment.md

@@ -7,6 +7,9 @@ redirect_from:
   - /actions/reference/environments
   - /actions/deployment/environments
   - /actions/deployment/using-environments-for-deployment
+topics:
+  - CD
+  - Deployment
 versions:
   fpt: '*'
   ghes: '*'
@@ -33,9 +36,15 @@ Organizations with {% data variables.product.prodname_team %} and users with {%
 {% endnote %}
 {% endif %}
 
-## Environment protection rules
+## Deployment protection rules
 
-Environment protection rules require specific conditions to pass before a job referencing the environment can proceed. You can use environment protection rules to require a manual approval, delay a job, or restrict the environment to certain branches.
+Deployment protection rules require specific conditions to pass before a job referencing the environment can proceed. You can use deployment protection rules to require a manual approval, delay a job, or restrict the environment to certain branches.{% ifversion actions-custom-deployment-protection-rules-beta %} You can also create and implement custom protection rules powered by {% data variables.product.prodname_github_apps %} to use third-party systems to control deployments referencing environments configured on {% data variables.location.product_location %}.
+
+Third-party systems can be observability systems, change management systems, code quality systems, or other manual configurations that you use to assess readiness before deployments are safely rolled out to environments.
+
+{% data reusables.actions.custom-deployment-protection-rules-limits %}
+
+{% endif %}
 
 ### Required reviewers
 
@@ -47,12 +56,6 @@ For more information on reviewing jobs that reference an environment with requir
 
 Use a wait timer to delay a job for a specific amount of time after the job is initially triggered. The time (in minutes) must be an integer between 0 and 43,200 (30 days).
 
-{% ifversion actions-break-glass %}
-### Do not let admins bypass protection rules
-
-Prevent admins from being able to bypass the configured environment protection rules.
-{% endif %}
-
 ### Deployment branches
 
 Use deployment branches to restrict which branches can deploy to the environment. Below are the options for deployment branches for an environment:
@@ -62,6 +65,27 @@ Use deployment branches to restrict which branches can deploy to the environment
 * **Selected branches**: Only branches that match your specified name patterns can deploy to the environment.
 
   For example, if you specify `releases/*` as a deployment branch rule, only branches whose name begins with `releases/` can deploy to the environment. (Wildcard characters will not match `/`. To match branches that begin with `release/` and contain an additional single slash, use `release/*/*`.) If you add `main` as a deployment branch rule, a branch named `main` can also deploy to the environment. For more information about syntax options for deployment branches, see the [Ruby File.fnmatch documentation](https://ruby-doc.org/core-2.5.1/File.html#method-c-fnmatch).
+
+{% ifversion actions-break-glass %}
+### Allow administrators to bypass configured protection rules
+
+By default, administrators can bypass the protection rules and force deployments to specific environments. For more information, see "[AUTOTITLE](/actions/managing-workflow-runs/reviewing-deployments#bypassing-environment-protection-rules)."
+
+Alternatively, you can configure environments to disallow bypassing the protection rules for all deployments to the environment.
+{% endif %}
+
+{% ifversion actions-custom-deployment-protection-rules-beta %}
+
+### Custom deployment protection rules
+
+{% data reusables.actions.custom-deployment-protection-rules-beta-note %}
+
+{% data reusables.actions.about-custom-deployment-protection-rules %} For more information, see "[AUTOTITLE](/actions/deployment/protecting-deployments/creating-custom-deployment-protection-rules)".
+
+Once custom deployment protection rules have been created and installed on a repository, you can enable the custom deployment protection rule for any environment in the repository. For more information about configuring and enabling custom deployment protection rules, see "[AUTOTITLE](/actions/deployment/protecting-deployments/configuring-custom-deployment-protection-rules)."
+
+{% endif %}
+
 ## Environment secrets
 
 Secrets stored in an environment are only available to workflow jobs that reference the environment. If the environment requires approval, a job cannot access environment secrets until one of the required reviewers approves it. For more information about secrets, see "[AUTOTITLE](/actions/security-guides/encrypted-secrets)."
@@ -99,19 +123,24 @@ Variables stored in an environment are only available to workflow jobs that refe
    1. Select **Required reviewers**.
    1. Enter up to 6 people or teams. Only one of the required reviewers needs to approve the job for it to proceed.
    1. Click **Save protection rules**.
-2. Optionally, specify the amount of time to wait before allowing workflow jobs that use this environment to proceed.
+1. Optionally, specify the amount of time to wait before allowing workflow jobs that use this environment to proceed.
    1. Select **Wait timer**.
    1. Enter the number of minutes to wait.
    1. Click **Save protection rules**.
 {%- ifversion actions-break-glass %}
-3. Optionally, prevent admins from bypassing environment protection rules. For more information about bypassing environment protection rules, see "[AUTOTITLE](/actions/managing-workflow-runs/reviewing-deployments)."
-   1. Select **Do not let admins bypass protection rules**.
+1. Optionally, disallow bypassing configured protection rules. For more information about bypassing configured protection rules, see "[AUTOTITLE](/actions/managing-workflow-runs/reviewing-deployments)."
+   1. Deselect **Allow administrators to bypass configured protection rules**.
    1. Click **Save protection rules**.
 {%- endif %}
-4. Optionally, specify what branches can deploy to this environment. For more information about the possible values, see "[Deployment branches](#deployment-branches)."
+{%- ifversion actions-custom-deployment-protection-rules-beta %}
+1. Optionally, enable any custom deployment protection rules that have been created with {% data variables.product.prodname_github_apps %}. For more information about configuring custom deployment protection rules with {% data variables.product.prodname_github_apps %}, see "[AUTOTITLE](/actions/deployment/protecting-deployments/configuring-custom-deployment-protection-rules)."
+   1. Select the custom protection rule you want to enable.
+   1. Click **Save protection rules**.
+{%- endif %}
+1. Optionally, specify what branches can deploy to this environment. For more information about the possible values, see "[Deployment branches](#deployment-branches)."
    1. Select the desired option in the **Deployment branches** dropdown.
    1. If you chose **Selected branches**, enter the branch name patterns that you want to allow.
-5. Optionally, add environment secrets. These secrets are only available to workflow jobs that use the environment. Additionally, workflow jobs that use this environment can only access these secrets after any configured rules (for example, required reviewers) pass. For more information about secrets, see "[AUTOTITLE](/actions/security-guides/encrypted-secrets)."
+1. Optionally, add environment secrets. These secrets are only available to workflow jobs that use the environment. Additionally, workflow jobs that use this environment can only access these secrets after any configured rules (for example, required reviewers) pass. For more information about secrets, see "[AUTOTITLE](/actions/security-guides/encrypted-secrets)."
    1. Under **Environment secrets**, click **Add Secret**.
    1. Enter the secret name.
    1. Enter the secret value.

data/allowed-topics.js

@@ -53,6 +53,7 @@ export default [
   'Dependencies',
   'Dependency graph',
   'Dependency review',
+  'Deployment',
   'Desktop',
   'Developer',
   'Device verification',

data/features/actions-custom-deployment-protection-rules-beta.yml

@@ -0,0 +1,6 @@
+# Reference: 9242
+# (Actions) Beta launch for custom deployment protection rules
+versions:
+  fpt: '*'
+  ghec: '*'
+  ghes: '>=3.10'

data/reusables/actions/about-custom-deployment-protection-rules.md

@@ -0,0 +1 @@
+You can enable your own custom protection rules to gate deployments with third-party services. For example, you can use services such as Datadog, Honeycomb, and ServiceNow to provide automated approvals for deployments to {% data variables.location.product_location %}.

data/reusables/actions/about-environments.md

@@ -1 +1 @@
-Environments are used to describe a general deployment target like `production`, `staging`, or `development`. When a {% data variables.product.prodname_actions %} workflow deploys to an environment, the environment is displayed on the main page of the repository. You can use environments to require approval for a job to proceed, restrict which branches can trigger a workflow, or limit access to secrets. For more information about creating environments, see "[AUTOTITLE](/actions/deployment/targeting-different-environments/using-environments-for-deployment)."
+Environments are used to describe a general deployment target like `production`, `staging`, or `development`. When a {% data variables.product.prodname_actions %} workflow deploys to an environment, the environment is displayed on the main page of the repository. You can use environments to require approval for a job to proceed, restrict which branches can trigger a workflow{% ifversion actions-custom-deployment-protection-rules-beta %}, gate deployments with custom deployment protection rules{% endif %}, or limit access to secrets. For more information about creating environments, see "[AUTOTITLE](/actions/deployment/targeting-different-environments/using-environments-for-deployment)."

data/reusables/actions/custom-deployment-protection-rules-beta-note.md

@@ -0,0 +1,5 @@
+{% note %}
+
+**Note:** Custom deployment protection rules are currently in public beta and subject to change.
+
+{% endnote %}

data/reusables/actions/custom-deployment-protection-rules-limits.md

@@ -0,0 +1,5 @@
+{% note %}
+
+**Note:** Any number of {% data variables.product.prodname_github_apps %}-based deployment protection rules can be installed on a repository. However, a maximum of 6 deployment protection rules can be enabled on any environment at the same time.
+
+{% endnote %}