Merge pull request #59 from github-community-projects/ahpook/march-do…

…c-updates

Quick doc updates to reflect new auth improvements

.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=

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).

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)