Add self-hosting guide for private repository deployment

Author: dash14

README.md

@@ -444,6 +444,10 @@ Given these implementation costs versus the strict preconditions for the attack
 
 ## FAQ
 
+**Q: Can I host buildcage in my own private repository?**
+
+A: Yes. You can import the repository into your organization and build the Docker image yourself. See the [Self-Hosting Guide](./docs/self-hosting.md) for details.
+
 **Q: Does this slow down my builds?**
 
 A: Minimal impact. The proxy adds negligible latency (<1ms per request). DNS caching and connection pooling keep overhead low.

docs/self-hosting.md

@@ -0,0 +1,112 @@
+# Self-Hosting Guide
+
+This guide explains how to host your own buildcage Docker image in a private GitHub repository. This is useful when you want to:
+
+- Keep the build infrastructure private within your organization
+- Control exactly which version of buildcage is deployed
+- Audit the source code before using it in your CI/CD pipelines
+
+## Prerequisites
+
+- A GitHub Organizations account with **GitHub Team** or **Enterprise** plan (required for private repository packages)
+
+## 1. Import the Repository
+
+Since forking creates a public repository, use **GitHub's import** feature to create a private copy.
+
+1. Go to [github.com/new/import](https://github.com/new/import)
+2. Enter the source URL: `https://github.com/dash14/buildcage.git`
+3. Select your organization as the owner
+4. Set the repository name (e.g., `buildcage`)
+5. Choose **Private**
+6. Click **Begin import**
+
+## 2. Build and Publish the Docker Image
+
+Your imported repository already contains the **Build and Push Docker Image** workflow (`.github/workflows/docker-publish.yml`). This workflow builds the image from source and publishes it to your repository's GitHub Container Registry (GHCR).
+
+To trigger the build:
+
+1. Go to your repository on GitHub
+2. Navigate to **Actions** > **Build and Push Docker Image**
+3. Click **Run workflow**
+
+Once complete, the image will be available at:
+
+```
+ghcr.io/<your_org>/buildcage
+```
+
+## 3. Configure Package Visibility
+
+The published package needs to be accessible from the repositories that will use it.
+
+1. Go to `github.com/<your_org>/buildcage/pkgs/container/buildcage`
+2. Click **Package settings**
+3. Under **Manage Actions access**, add the repositories that need to pull the image
+
+## 4. Configure Actions Access
+
+Allow other repositories in your organization to use the actions from your private repository:
+
+1. Go to your buildcage repository's **Settings** > **Actions** > **General**
+2. Under **Access**, select **Accessible from repositories in the '\<your_org\>' organization**
+
+## 5. Update Your Workflows
+
+In the repositories where you want to use buildcage, make two changes:
+
+### Add GHCR login step
+
+Add a login step before the buildcage setup, and ensure the job has `packages: read` permission:
+
+```yaml
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Login to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Start buildcage
+        id: buildcage
+        uses: <your_org>/buildcage/setup@v1
+        with:
+          proxy_mode: audit
+      # ... rest of your workflow
+```
+
+Note that `uses:` now points to `<your_org>/buildcage/setup@v1` instead of `dash14/buildcage/setup@v1`. The same applies to the report action (`<your_org>/buildcage/report@v1`).
+
+## Syncing with Upstream
+
+### Initial setup
+
+Clone your private repository and register the upstream remote:
+
+```bash
+git clone https://github.com/<your_org>/buildcage.git
+cd buildcage
+git remote add upstream https://github.com/dash14/buildcage.git
+```
+
+### Pulling updates
+
+Fetch the latest changes from the original repository and merge them into your copy:
+
+```bash
+git fetch upstream --tags --force
+git merge upstream/main
+git push origin HEAD --tags --force
+```
+
+After pushing a new version tag, the **Build and Push Docker Image** workflow will automatically trigger and publish the updated image.