{"meta":{"title":"Creating custom deployment protection rules","intro":"Use GitHub Apps to automate protecting deployments with third-party systems.","product":"GitHub Actions","breadcrumbs":[{"href":"/en/actions","title":"GitHub Actions"},{"href":"/en/actions/how-tos","title":"How-tos"},{"href":"/en/actions/how-tos/deploy","title":"Deploy"},{"href":"/en/actions/how-tos/deploy/configure-and-manage-deployments","title":"Configure and manage deployments"},{"href":"/en/actions/how-tos/deploy/configure-and-manage-deployments/create-custom-protection-rules","title":"Create custom protection rules"}],"documentType":"article"},"body":"# Creating custom deployment protection rules\n\nUse GitHub Apps to automate protecting deployments with third-party systems.\n\n## Prerequisites\n\n> \\[!NOTE]\n> Custom deployment protection rules are currently in public preview and subject to change.\n\nFor general information about deployment protection rules, see [Deploying with GitHub Actions](/en/actions/how-tos/deploy/configure-and-manage-deployments/control-deployments#using-custom-deployment-protection-rules).\n\n## Creating a custom deployment protection rule with GitHub Apps\n\n1. Create a GitHub App. For more information, see [Registering a GitHub App](/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app). Configure the GitHub App as follows.\n   1. Optionally, in the **Callback URL** text field under \"Identifying and authorizing users,\" enter the callback URL. For more information, see [About the user authorization callback URL](/en/apps/creating-github-apps/registering-a-github-app/about-the-user-authorization-callback-url).\n   2. Under \"Permissions,\" select **Repository permissions**.\n   3. To the right of \"Actions,\" click the drop down menu and select **Access: Read-only**.\n      ![Screenshot of the \"Repository permissions\" section for a new GitHub App. The Actions permission shows \"Read-only\" and is outlined in orange.](/assets/images/help/actions/actions-repo-permissions-read-only.png)\n   4. To the right of \"Deployments,\" click the drop down menu and select **Access: Read and write**.\n      ![Screenshot of the \"Repository permissions\" section for a new GitHub App. The Deployments permission shows \"Read and write\" and is outlined in orange.](/assets/images/help/actions/actions-deployments-repo-permissions-read-and-write.png)\n   5. Under \"Subscribe to events,\" select **Deployment protection rule**.\n      ![Screenshot of the \"Subscribe to events section\" section for a new GitHub App. The checkbox for the Deployment protection rule is outlined in orange.](/assets/images/help/actions/actions-subscribe-to-events-deployment-protection-rules.png)\n\n2. Install the custom deployment protection rule in your repositories and enable it for use. For more information, see [Configuring custom deployment protection rules](/en/actions/how-tos/deploy/configure-and-manage-deployments/configure-custom-protection-rules).\n\n## Approving or rejecting deployments\n\nOnce a workflow reaches a job that references an environment that has the custom deployment protection rule enabled, GitHub 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.\n\nCustom deployment protection rules are not compatible when a workflow job's environment is set to `deployment: false`. For more information, see [Deploying with GitHub Actions](/en/actions/how-tos/deploy/configure-and-manage-deployments/control-deployments#interaction-with-protection-rules).\n\n1. Validate the incoming `POST` request. For more information, see [Validating webhook deliveries](/en/webhooks/using-webhooks/validating-webhook-deliveries#validating-webhook-deliveries).\n\n2. Use a JSON Web Token to authenticate as a GitHub App. For more information, see [Authenticating as a GitHub App](/en/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app#about-authentication-as-a-github-app).\n\n3. Using the installation ID from the `deployment_protection_rule` webhook payload, generate an install token. For more information, see [About authentication with a GitHub App](/en/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app#authentication-as-a-github-app).\n\n   ```shell\n   curl --request POST \\\n   --url \"https://api.github.com/app/installations/INSTALLATION_ID/ACCESS_TOKENS\" \\\n   --header \"Accept: application/vnd.github+json\" \\\n   --header \"Authorization: Bearer {jwt}\" \\\n   --header \"Content-Type: application/json\" \\\n   --data \\\n   '{ \\\n      \"repository_ids\": [321], \\\n      \"permissions\": { \\\n         \"deployments\": \"write\" \\\n      } \\\n   }'\n   ```\n\n4. Optionally, to add a status report without taking any other action to GitHub, 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 [REST API endpoints for workflow runs](/en/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.\n\n5. 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 [REST API endpoints for workflow runs](/en/rest/actions/workflow-runs#review-custom-deployment-protection-rules-for-a-workflow-run).\n\n6. Optionally, request the status of an approval for a workflow run by sending a `GET` request to `/repos/OWNER/REPOSITORY_ID/actions/runs/RUN_ID/approvals`. For more information, see [REST API endpoints for workflow runs](/en/rest/actions/workflow-runs#get-the-review-history-for-a-workflow-run).\n\n7. Optionally, review the deployment on GitHub. For more information, see [Reviewing deployments](/en/actions/how-tos/deploy/configure-and-manage-deployments/review-deployments).\n\n## Publishing custom deployment protection rules in the GitHub Marketplace\n\nYou can publish your GitHub App to the GitHub Marketplace to allow developers to discover suitable protection rules and install it across their GitHub repositories. Or you can browse existing custom deployment protection rules to suit your needs. For more information, see [About GitHub Marketplace for apps](/en/apps/github-marketplace/github-marketplace-overview/about-github-marketplace-for-apps) and [Listing an app on GitHub Marketplace](/en/apps/github-marketplace/listing-an-app-on-github-marketplace)."}