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 -appId -privateKeyFile -installationId " + 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 -appId -privateKeyFile -installationId -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 +``` +