From b926d39a960ac8dcc6ff90cdacd01d655ed70238 Mon Sep 17 00:00:00 2001 From: Eric Sorenson Date: Mon, 4 Mar 2024 17:30:20 -0800 Subject: [PATCH] Quick doc updates to reflect new auth improvements Made the example `.env` a bit more verbose and reordered the deployment section of the readme. Maybe needs more? --- .env.example | 3 ++- README.md | 8 +++++++- docs/using-the-app.md | 2 +- 3 files changed, 10 insertions(+), 3 deletions(-) diff --git a/.env.example b/.env.example index 0691136..6e70840 100644 --- a/.env.example +++ b/.env.example @@ -9,6 +9,7 @@ PRIVATE_KEY=-----BEGIN RSA PRIVATE KEY-----\nYOUR KEY HERE WITH \n INCLUDED=\n-- # Auth configs NEXTAUTH_SECRET=bad-secret NEXTAUTH_URL=http://localhost:3000 +# A comma-separated list of GitHub usernames that are allowed to access the app ALLOWED_HANDLES= # Go to https://smee.io/new set this to the URL that you are redirected to. @@ -21,6 +22,6 @@ LOG_LEVEL=debug # Used for settings various configuration in the app NODE_ENV=development -# Used for GHEC configs +# Used for GHEC configs, where private mirrors are kept in a different org PUBLIC_ORG= PRIVATE_ORG= diff --git a/README.md b/README.md index e76dc8a..6129818 100644 --- a/README.md +++ b/README.md @@ -72,7 +72,11 @@ You'll need to self-host the app. See the section on [Developing](#developing) f This app was created with the idea of self-hosting in mind and can be deployed to any hosting provider that supports Next.js/Docker. -You will still need to create a GitHub App and configure it to point to your deployment. See the [Developing — GitHub App](#github-app) section for more information. +Configuration is contained in a `.env` file which you'll need to customize for your environment. Use the `.env.example` in the root of this repository as a starting point. In particular, you'll need to set the following: + +- `PUBLIC_ORG` and `PRIVATE_ORG` environment variables if you want to keep your private mirrors in a different GitHub organization from the public forks +- `ALLOWED_HANDLES` variable to a comma-separated list of GitHub user handles which ought to be allowed to access the app to create mirrors. If unset, all users who are members of the organization will be allowed to use the app. +- use https://smee.io or your own infrastructure to make the docker service available to receive webhooks ```sh docker build -t internal-contribution-forks . @@ -84,6 +88,8 @@ docker compose up We recommend using Node 20.x or higher, though any Node LTS version >18 should work. +Once it's running, you'll need to create a GitHub App and configure it to point to your deployment. See the [Developing — GitHub App](#github-app) section for more information. + ## Integrating the App into GHEC The app can be integrated into GitHub Enterprise Cloud (GHEC) by following the same steps as GitHub.com. The app is designed to work with GHEC and GitHub Enterprise Managed Users (EMUs). diff --git a/docs/using-the-app.md b/docs/using-the-app.md index 64ca907..3a783ed 100644 --- a/docs/using-the-app.md +++ b/docs/using-the-app.md @@ -6,7 +6,7 @@ 3. Fork an upstream project into the organization's namespace. This will create your **public fork**. A decision point for administrators is whether to permit any user to fork new projects into the organizations, or restrict the ability to fork. These permissions are managed by [the organization's forking policy](https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-organization-settings/managing-the-forking-policy-for-your-organization). A more permissive posture can lower the barrier to contribution, but shouldn't circumvent company policy on approving upstream work. -4. Go the app's URL and authenticate to it. You'll see a list of your organizations that the app is managing. Click on your org's name and you'll see a list of all the public forks in the organization. _What about access control to app/forks inside?_ +4. Go the app's URL and authenticate to it. If your account is in the list of allowed usernames, you'll see a list of your organizations that the app is managing. Click on your org's name and you'll see a list of all the public forks in the organization. ![List of public forks inside the organization](images/public-forks-inside-org.png)