From 8d369c0e6ae5927349e06d25f94886dedf342a14 Mon Sep 17 00:00:00 2001
From: Brad Abrams <brad.abrams@rbc.com>
Date: Mon, 24 Jun 2024 16:25:41 -0400
Subject: [PATCH] Update documentation: Environments permissions.

Addresses issue: [Environments do not get provisioned for repositories set to internal or private #623](https://github.com/github/safe-settings/issues/623)

Adds documentation for permissions required for safe-settings when Environments are used

[List Environments](https://docs.github.com/en/rest/deployments/environments?apiVersion=2022-11-28#list-environments) API requires:
```
The fine-grained token must have the following permission set:

"Actions" repository permissions (read)
```

[Create an environment variable](https://docs.github.com/en/rest/actions/variables?apiVersion=2022-11-28#create-an-environment-variable) API requires:
```
The fine-grained token must have the following permission set:

"Variables" repository permissions (write) and "Environments" repository permissions (write)
```

With permissions added, issue 623 was resolved.
---
 README.md      |  5 +++--
 app.yml        | 12 ++++++++++++
 docs/deploy.md |  3 +++
 3 files changed, 18 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 0c5f00bd..20a29bfe 100644
--- a/README.md
+++ b/README.md
@@ -266,9 +266,9 @@ And the `checkrun` page will look like this:
 <img width="860" alt="image" src="https://github.com/github/safe-settings/assets/57544838/893ff4e6-904c-4a07-924a-7c23dc068983">
 </p>
 
-### The Settings File
+### The Settings Files
 
-The settings file can be used to set the policies at the `org`, `suborg` or `repo` level.
+The settings files can be used to set the policies at the `org`, `suborg` or `repo` level.
 
 The following can be configured:
 
@@ -284,6 +284,7 @@ The following can be configured:
 - `Autolinks`
 - `Repository name validation` using regex pattern
 - `Rulesets`
+- `Environments` - wait timer, required reviewers, prevent self review, protected branches deployment branch policy, custom deployment branch policy, variables, deployment protection rules
 
 It is possible to provide an `include` or `exclude` settings to restrict the `collaborators`, `teams`, `labels` to a list of repos or exclude a set of repos for a collaborator.
 
diff --git a/app.yml b/app.yml
index 24c28282..44dd0bdc 100644
--- a/app.yml
+++ b/app.yml
@@ -34,6 +34,10 @@ default_permissions:
     repository_custom_properties: write
     organization_custom_properties: admin
 
+    # Workflows, workflow runs and artifacts. (needed to read environments when repo is private or internal)
+    # https://developer.github.com/v3/apps/permissions/#repository-permissions-for-actions
+    actions: read
+
     # Repository creation, deletion, settings, teams, and collaborators.
     # https://developer.github.com/v3/apps/permissions/#permission-on-administration
     administration: write
@@ -50,6 +54,10 @@ default_permissions:
     # https://developer.github.com/v3/apps/permissions/#permission-on-deployments
     # deployments: read
 
+    # Manage repository environments.
+    # https://developer.github.com/v3/apps/permissions/#repository-permissions-for-environments
+    environments: write
+
     # Issues and related comments, assignees, labels, and milestones.
     # https://developer.github.com/v3/apps/permissions/#permission-on-issues
     issues: write
@@ -106,6 +114,10 @@ default_permissions:
     # https://developer.github.com/v3/apps/permissions/
     organization_administration: write
 
+    # Manage Actions repository variables.
+    # https://developer.github.com/v3/apps/permissions/#repository-permissions-for-variables
+    variables: write
+
 
 # The name of the GitHub App. Defaults to the name specified in package.json
 name: Safe Settings
diff --git a/docs/deploy.md b/docs/deploy.md
index 7e016777..ba3dff7f 100644
--- a/docs/deploy.md
+++ b/docs/deploy.md
@@ -255,14 +255,17 @@ Every deployment will need an [App](https://developer.github.com/apps/).
 
 #### Repository Permissions
 
+- Actions: **Read-only**
 - Administration: **Read & Write**
 - Checks: **Read & Write**
 - Commit statuses: **Read & Write**
 - Contents: **Read & Write**
 - Custom properties: **Read & Write**
+- Environments: **Read & Write**
 - Issues: **Read & Write**
 - Metadata: **Read-only**
 - Pull requests: **Read & Write**
+- Variables: **Read & Write**
 
 #### Organization Permissions