docs: add deployment docs (moved from app repo)

Author: lwasser

astro.config.mjs

@@ -68,6 +68,14 @@ export default defineConfig({
                       { label: 'implementations', slug: 'project/implementations' },
                   ],
               },
+
+              {
+                  label: 'Development',
+                  items: [
+                      { label: 'about', slug: 'development/about-the-bot' },
+                      { label: 'development', slug: 'development/local-deploy' },
+                  ],
+              },
           ],
           }),
       sitemap()

src/assets/app-created.png

@@ -0,0 +1,40 @@
+---
+id: local
+title: Testing the All-Contributors App
+sidebar_label: Test the Bot Locally
+---
+
+## Understanding GitHub Apps and Local Development
+
+### What is a GitHub App?
+
+A GitHub App is how bots interact with GitHub. It's:
+
+- **An account** - GitHub knows "this is the AllContributors bot"
+- **A permission system** - defines what the bot can read/write (issues, PRs,
+  files)
+- **A webhook endpoint** - where GitHub sends events (like "someone commented
+  on an issue")
+
+When someone comments `@all-contributors please add @user for code`, GitHub
+sends that comment as a webhook to whatever URL is configured in the GitHub App
+settings.
+
+### Why create your own test app?
+
+The production AllContributors app is configured to send webhooks to the
+production Vercel deployment. You can't use it for local development because:
+
+1. The webhooks go to production, not your laptop
+2. Your changes would affect real repositories
+3. You'd need to deploy every change just to test it
+
+### Local development flow:
+
+1. **Create your own GitHub App** - your personal copy with its own settings
+2. **Point its webhooks at your local machine** - so events come to you
+3. **Install it only on test repos** - isolated from production
+4. **Run the bot code locally** - make changes, test immediately
+5. **When ready** - deploy to Vercel and test with preview deployments
+
+This gives you a safe sandbox to develop in.

src/assets/delivery-comment.png

@@ -0,0 +1,143 @@
+---
+id: local
+title: How to deploy the bot locally
+sidebar_label: Help us Improve
+---
+
+import { Aside } from "@astrojs/starlight/components";
+import { Picture } from "astro:assets";
+import appInstalled from "@assets/where-app-is-installed.png";
+import appCreated from "@assets/app-created.png";
+import deliveryComment from "@assets/delivery-comment.png";
+
+## Local Bot Setup
+
+To test the bot locally, you need to create your own GitHub App and configure
+it to point to your local machine.
+
+<Aside type="caution">
+  Uninstall the production all-contributors bot from your user account before
+  continuing; if you don't, multiple bots will respond to your GitHub comments.
+</Aside>
+
+To get your app running against GitHub:
+
+## 1. Create a GitHub App for testing in your account:
+
+- Go to your account's GitHub
+  [developer settings](https://github.com/settings/developers)
+- Create a [new GitHub app](https://github.com/settings/apps/new)
+
+Required fields are:
+
+- `name`, which can be whatever you like, globally unique on GitHub
+- `homepage url`, which can be set to anything
+- `webhook url`, which can be set to anything
+
+Important fields are:
+
+- `webhook secret`, set this to `development`
+- `Permissions` which should be set
+  [as defined in the app.yml](https://github.com/all-contributors/all-contributors-bot/blob/main/app.yml#L54),
+  e.g. set read & write for `Repository contents`, `Issues` and
+  `Pull Requests`, and read for `Repository Metadata`
+- `Subscribe to Events` which should be set
+  [as defined in the app.yml](https://github.com/all-contributors/all-contributors-bot/blob/main/app.yml#L15),
+  e.g. check the checkbox for `Issue comment`
+- Ensure `Where can this GitHub App be installed?` is set to
+  `only this account`
+
+<Picture
+  src={appInstalled}
+  formats={["avif", "webp"]}
+  alt="A screenshot ...."
+/>
+
+## 2. Configure Your GitHub App for testing
+
+You should now have an app created
+
+<Picture src={appCreated} formats={["avif", "webp"]} alt="A screenshot ...." />
+
+- On the General Tab, Click `Generate Private Key` and download it for later
+  usage, call it something like `allcontributorsbot.pem`
+- On the Install Tab, Install the app/bot on your user
+
+## 3. Configure Your local to talk to the GitHub app
+
+Create a file named `.env` with the following template:
+
+```txt
+APP_ID=
+WEBHOOK_SECRET=development
+PRIVATE_KEY=
+```
+
+### Values
+
+- `APP_ID`, you can get this from the General tab on the developer settings for
+  your app
+- `WEBHOOK_SECRET`, leave as development (you set this on app setup)
+- `PRIVATE_KEY` when you generated the private key from your app, you should
+  have a `allcontributorsbot.pem` file locally (or similar). run
+  `openssl base64 < allcontributorsbot.pem | tr -d '\n' | pbcopy` on the file
+  which will copy the base64 contents onto your clipboard, paste that into the
+  line for `PRIVATE_KEY`
+
+## 4. Setup a test GitHub repository/with issues PR
+
+- Setup a repository under your name (the name on GitHub where the bot is
+  installed)
+- Enable issues and pull requests
+- Create an issue
+- Comment on the issue: `@all-contributors please add @jakebolam for design`
+  (replace @jakebolam with your username)
+
+To verify if the bot should have seen this goto
+[your app settings](https://github.com/settings/apps/). On the Advanced Tab,
+Click the most recent deliver to see the payload. It should look something like
+this:
+
+<Picture
+  src={deliveryComment}
+  formats={["avif", "webp"]}
+  alt="A screenshot ...."
+/>
+
+Copy the payload and save it locally in a file called
+`test-webhook-payload.json`. Also make note of the headers under the 'Headers'
+section.
+
+## 5. Send your first hook
+
+1. Install the node modules for the bot `yarn install`
+2. Run the bot `yarn start`
+3. Curl the bot (or use Postman, using the headers you got from the previous
+   step and the content from `test-webhook-payload.json`) If you're using
+   `curl`, this will look something like this:
+
+```console
+curl -vX POST http://localhost:3000/ -d @test-webhook-payload.json \
+--header "Content-Type: application/json" \
+--header "User-Agent: GitHub-Hookshot/4d63832" \
+--header "X-GitHub-Delivery: 413857f0-8b61-11eb-92be-566b7aa5f6ee" \
+--header "X-GitHub-Event: issue_comment" \
+--header "X-GitHub-Hook-ID: 297478976" \
+--header "X-GitHub-Hook-Installation-Target-ID: 105785" \
+--header "X-GitHub-Hook-Installation-Target-Type: integration" \
+--header "X-Hub-Signature: sha1=ed222e6750dc2954a422ed8dd371f9da66368104" \
+--header "X-Hub-Signature-256: sha256=04d0943f20545ac8df974466c502e4b9743d3618149b03f4ea1a9e658bf31fd0"
+```
+
+If there are no errors in the bot console, check your GitHub test issue to see
+the bot respond :tada:
+
+## Using [smee.io](https://smee.io/)
+
+Alternatively, instead of having to mock the webhook payload using `curl`, you
+can add an additional environment variable called `WEBHOOK_PROXY_URL` and set
+it to a [smee.io](https://smee.io) channel URL.
+
+Once you've done that, set the Webhook URL for you app in GitHub to the same
+channel URL and, after a server restart, your bot will be able to directly
+respond to incoming webhooks.