fix: docs update, doc additional env vars (#31)

* fix: docs update, doc additional env vars

Signed-off-by: Jeffrey Sica <me@jeefy.dev>

* refactor: use the forOrg helpers from github-auth-app instead of forRepo

* docs: remove stray whitespace

* document required github app oauth scopes

Signed-off-by: Jeffrey Sica <me@jeefy.dev>

Signed-off-by: Jeffrey Sica <me@jeefy.dev>
Co-authored-by: Samuel Attard <samuel.r.attard@gmail.com>

README.md

@@ -45,6 +45,30 @@ You want to specify the following options:
 
 Finally, click "Add webhook".
 
+### The GitHub App
+
+To manage GitHub instances, Sheriff requires you to create a GitHub App that gets installed in the desired Org.
+
+The app needs the following OAuth scopes permitted:
+
+```
+Org:
+administration:write
+contents:read
+metadata:read
+
+Repo:
+members:write
+```
+
+Once created, you can generate and download a Private Key for the app, and supply it to Sheriff.
+
+Before setting it as `SHERIFF_GITHUB_APP_CREDS`, you must pass it through a utility to change the format to what Octokit is expecting:
+
+```
+npx @electron/github-app-auth --creds={path-to-downloaded-private-key} --app-id={id-from-created-github-app}
+```
+
 ### The Cron Job
 
 The actual permissions controller should be triggered every 10 minutes as a cron job. You can run this job with:
@@ -79,6 +103,8 @@ The following environment variables represent the configuration of the actual Sh
 | Name | Required | Value | For Plugin |
 |------|----------|-------|------------|
 | `PERMISSIONS_FILE_ORG` | ✔️ | The name of the GitHub org where you put the `.permissions` repository | |
+| `PERMISSIONS_FILE_REPO` | | Override the default repo to look for `config.yaml` | `.permissions` |
+| `PERMISSIONS_FILE_PATH` | | Override the default filepath to look for the Sheriff config | `config.yaml` |
 | `GITHUB_WEBHOOK_SECRET` | ✔️ | The secret for the org-wide webhook you configured earlier | |
 | `SLACK_TOKEN` | ✔️ | The token for your Slack App you created earlier | |
 | `SLACK_WEBHOOK_URL` | ✔️ | The webhook URL for your Slack App you created earlier | |

package.json

@@ -16,7 +16,7 @@
   },
   "author": "Samuel Attard",
   "dependencies": {
-    "@electron/github-app-auth": "^1.4.0",
+    "@electron/github-app-auth": "^1.5.0",
     "@octokit/graphql": "^4.8.0",
     "@octokit/rest": "^18.12.0",
     "@octokit/webhooks": "^9.23.0",

src/constants.ts

@@ -1,10 +1,7 @@
-export const ORGANIZATION_NAME = process.env.ORGANIZATION_NAME || 'electron';
-export const REPO_NAME = process.env.REPO_NAME || 'electron';
-
 export const SHERIFF_GITHUB_APP_CREDS = process.env.SHERIFF_GITHUB_APP_CREDS;
 export const GITHUB_WEBHOOK_SECRET = process.env.GITHUB_WEBHOOK_SECRET || 'development';
 
-export const PERMISSIONS_FILE_ORG = process.env.PERMISSIONS_FILE_ORG;
+export const PERMISSIONS_FILE_ORG = process.env.PERMISSIONS_FILE_ORG!;
 export const PERMISSIONS_FILE_REPO = process.env.PERMISSIONS_FILE_REPO || '.permissions';
 export const PERMISSIONS_FILE_PATH = process.env.PERMISSIONS_FILE_PATH || 'config.yaml';
 

src/octokit.ts

@@ -3,10 +3,10 @@ import { Octokit } from '@octokit/rest';
 import {
   appCredentialsFromString,
   AuthNarrowing,
-  getAuthOptionsForRepo,
-  getTokenForRepo,
+  getAuthOptionsForOrg,
+  getTokenForOrg,
 } from '@electron/github-app-auth';
-import { SHERIFF_GITHUB_APP_CREDS, ORGANIZATION_NAME, REPO_NAME } from './constants';
+import { SHERIFF_GITHUB_APP_CREDS, PERMISSIONS_FILE_ORG } from './constants';
 import { IS_DRY_RUN } from './helpers';
 
 require('dotenv-safe').config();
@@ -40,11 +40,8 @@ export async function getOctokit(forceReadOnly = false) {
   if (octokit) return octokit;
 
   const creds = appCredentialsFromString(SHERIFF_GITHUB_APP_CREDS!);
-  const authOpts = await getAuthOptionsForRepo(
-    {
-      owner: ORGANIZATION_NAME,
-      name: REPO_NAME,
-    },
+  const authOpts = await getAuthOptionsForOrg(
+    PERMISSIONS_FILE_ORG,
     creds,
     getAuthNarrowing(forceReadOnly),
   );
@@ -54,14 +51,7 @@ export async function getOctokit(forceReadOnly = false) {
 
 export async function graphyOctokit(forceReadOnly = false) {
   const creds = appCredentialsFromString(SHERIFF_GITHUB_APP_CREDS!);
-  const token = await getTokenForRepo(
-    {
-      owner: ORGANIZATION_NAME,
-      name: REPO_NAME,
-    },
-    creds,
-    getAuthNarrowing(forceReadOnly),
-  );
+  const token = await getTokenForOrg(PERMISSIONS_FILE_ORG, creds, getAuthNarrowing(forceReadOnly));
   return graphql.defaults({
     headers: {
       authorization: `token ${token}`,

yarn.lock

@@ -2,10 +2,10 @@
 # yarn lockfile v1
 
 
-"@electron/github-app-auth@^1.4.0":
-  version "1.4.0"
-  resolved "https://registry.yarnpkg.com/@electron/github-app-auth/-/github-app-auth-1.4.0.tgz#74a6247299237093d5558e0012b6ea0af4265744"
-  integrity sha512-fzGQmBohQIAreqorA0v1NcMlsaNxcLCZAGlFbwm9AR78xQi0ZHlTRAYYOaWh//Hfja3WIF/LI5i8c/SJ5JYyEQ==
+"@electron/github-app-auth@^1.5.0":
+  version "1.5.0"
+  resolved "https://registry.yarnpkg.com/@electron/github-app-auth/-/github-app-auth-1.5.0.tgz#426e64ba50143417d9b68f2795a1b119cb62108b"
+  integrity sha512-t6Za+3E7jdIf1CX06nNV/avZhqSXNEkCLJ1xeAt5FKU9HdGbjzwSfirM+UlHO7lMGyuf13BGCZOCB1kODhDLWQ==
   dependencies:
     "@octokit/auth-app" "^3.6.1"
     "@octokit/rest" "^18.12.0"