From 71119f8fcf6e31d8acc3faca502ff1765019183f Mon Sep 17 00:00:00 2001
From: Nicholas Wiersma <nick@wiersma.co.za>
Date: Mon, 21 Oct 2024 20:14:34 +0200
Subject: [PATCH] feat: support GitHub App authentication (#1988)

Adds support for using GitHub Apps as a form of authentication
---
 cmd/proxy/Dockerfile                         |  5 +++
 docs/content/configuration/authentication.md | 46 ++++++++++++++++++++
 2 files changed, 51 insertions(+)

diff --git a/cmd/proxy/Dockerfile b/cmd/proxy/Dockerfile
index 7ca589bbe..e498e191d 100644
--- a/cmd/proxy/Dockerfile
+++ b/cmd/proxy/Dockerfile
@@ -43,6 +43,11 @@ RUN chmod 644 /config/config.toml
 # Add tini, see https://github.com/gomods/athens/issues/1155 for details.
 RUN apk add --update git git-lfs mercurial openssh-client subversion procps fossil tini
 
+# Add git-credential-github-app for native integration with GitHub Apps
+RUN wget -O git-credential-github-app.tar.gz https://github.com/bdellegrazie/git-credential-github-app/releases/download/v0.3.0/git-credential-github-app_v0.2.0_Linux_x86_64.tar.gz \
+  && tar xvzf 'git-credential-github-app.tar.gz' git-credential-github-app -C /usr/local/bin \
+  && rm git-credential-github-app.tar.gz || true;
+
 ARG USER=athens
 RUN adduser -D -h /home/$USER $USER
 
diff --git a/docs/content/configuration/authentication.md b/docs/content/configuration/authentication.md
index 584ccf03a..002d5d336 100644
--- a/docs/content/configuration/authentication.md
+++ b/docs/content/configuration/authentication.md
@@ -308,3 +308,49 @@ $ docker run --rm -d \
     -e "SSH_AUTH_SOCK=/.ssh_agent_sock" \
     -e ATHENS_DISK_STORAGE_ROOT=/var/lib/athens -e ATHENS_STORAGE_TYPE=disk --name athens-proxy -p 3000:3000 gomods/athens:canary
 ```
+
+## GitHub Apps
+
+Instead of using a Machine User on GitHub, it is possible to create a GitHub App and authenticate via it. 
+
+Create a GitHub App in **Settings > Developer settings > GitHub Apps** and install it. The AppID/ClientID, Installation ID and Private Key are
+required from the App.
+
+Install the [GitHub App Git Credential Helper](https://github.com/bdellegrazie/git-credential-github-app) in your `$PATH`. The Athens Docker image comes
+with this pre-installed.
+
+Configure your [global Git config](https://git-scm.com/docs/git-config) as follows:
+
+```
+[credential "https://github.com/your-org"]
+    helper = "github-app -username <app-name> -appId <app-id> -privateKeyFile <path-to-private-key> -installationId <installation-id>"
+    useHttpPath = true
+
+[credential "https://github.com"]
+    helper = "cache --timeout=3600"
+
+[url "https://github.com"]
+    insteadOf = ssh://git@github.com
+```
+
+This instructs Git to authenticate with the GitHub App and cache the results for 3600s (the authentication token is valid for 1 hour).
+
+Now, builds executed through the Athens proxy should be able to clone the `github.com/your-org/your-repo` dependency over GitHub Apps.
+
+### GitHub Enterprise Self-hosted
+
+To authenticate against a self-hosted GitHub Enterprise, the instructions are the same for GitHub hosted Apps
+with the exception for the Git config, which should include your domain, as follows:
+
+```
+[credential "https://github.example.com/your-org"]
+    helper = "github-app -username <app-name> -appId <app-id> -privateKeyFile <path-to-private-key> -installationId <installation-id> -domain github.example.com"
+    useHttpPath = true
+
+[credential "https://github.example.com"]
+    helper = "cache --timeout=3600"
+
+[url "https://github.example.com"]
+    insteadOf = ssh://git@github.com
+```
+