From 6e8d62258bd9f31af65f4e46674117782181df31 Mon Sep 17 00:00:00 2001 From: Ben Date: Fri, 4 Nov 2022 16:28:31 +0000 Subject: [PATCH 1/2] docs: git auth --- docs/admin/git-providers.md | 80 +++++++++++++++++++++++++++++++++++++ docs/manifest.json | 6 +++ 2 files changed, 86 insertions(+) create mode 100644 docs/admin/git-providers.md diff --git a/docs/admin/git-providers.md b/docs/admin/git-providers.md new file mode 100644 index 0000000000000..45b2c2b03773f --- /dev/null +++ b/docs/admin/git-providers.md @@ -0,0 +1,80 @@ +# Git Providers + +Coder integrates with git providers so developers can authenticate with repositories within their workspace. + +## How it works + +When developers use `git` inside their workspace, they are first prompted to authenticate. After that, Coder will store/refresh tokens for future operations. + + + +## Configuration + +To add a git provider, you'll need to create an OAuth application. The following providers are supported: + +- [GitHub](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app) (GitHub apps are also supported) +- [GitLab](https://docs.gitlab.com/ee/integration/oauth_provider.html) +- [BitBucket](https://support.atlassian.com/bitbucket-cloud/docs/use-oauth-on-bitbucket-cloud/) +- [Azure DevOps](https://learn.microsoft.com/en-us/azure/devops/integrate/get-started/authentication/oauth?view=azure-devops) + +Example callback URL: `https://coder.example.com/api/v2/gitauth/primary-github/callback`. Use an arbitrary ID for your provider (e.g. `primary-github`). + +Set the following environment variables to [configure the Coder server](./configure.md): + +```sh +CODER_GITAUTH_0_ID="primary-github" +CODER_GITAUTH_0_TYPE=github|gitlab|azure-devops|bitbucket +CODER_GITAUTH_0_CLIENT_ID=xxxxxx +CODER_GITAUTH_0_CLIENT_SECRET=xxxxxxx +``` + +### Self-managed git providers + +Custom authentication and token URLs should be +used for self-managed Git provider deployments. + +```sh +CODER_GITAUTH_0_AUTH_URL="https://github.example.com/oauth/authorize" +CODER_GITAUTH_0_TOKEN_URL="https://github.example.com/oauth/token" +``` + +### Custom scopes + +Optionally, you can request custom scopes: + +```sh +CODER_GITAUTH_0_SCOPES="repo:read repo:write write:gpg_key" +``` + +### Multiple git providers (enterprise) + +Multiple providers are an Enterprise feature. [Learn more](../enterprise.md). + +A custom regex can be used to match a specific repository or organization to limit auth scope. Here's a sample config: + +```sh +# Provider 1) github.com +CODER_GITAUTH_0_ID=primary-github +CODER_GITAUTH_0_TYPE=github +CODER_GITAUTH_0_CLIENT_ID=xxxxxx +CODER_GITAUTH_0_CLIENT_SECRET=xxxxxxx +CODER_GITAUTH_0_REGEX=github.com/orgname + +# Provider 2) github.example.com +CODER_GITAUTH_1_ID=secondary-github +CODER_GITAUTH_1_TYPE=github +CODER_GITAUTH_1_CLIENT_ID=xxxxxx +CODER_GITAUTH_1_CLIENT_SECRET=xxxxxxx +CODER_GITAUTH_1_REGEX=github.example.com +CODER_GITAUTH_1_AUTH_URL="https://github.example.com/oauth/authorize" +CODER_GITAUTH_1_TOKEN_URL="https://github.example.com/oauth/token" +``` + +To support regex matching for paths (e.g. github.com/orgname), youll need to add this to the [Coder agent startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script): + +```sh +git config --global credential.useHttpPath true +``` diff --git a/docs/manifest.json b/docs/manifest.json index 40d03779a0a45..6f46ffab923fb 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -230,6 +230,12 @@ "path": "./admin/configure.md", "icon_path": "./images/icons/toggle_on.svg" }, + { + "title": "Git Providers", + "description": "Learn how connect Coder with external git providers", + "icon_path": "./images/icons/git.svg", + "path": "./admin/git-providers.md" + }, { "title": "Upgrading", "description": "Learn how to upgrade Coder", From f93ffaea4b0ef9e6bbfb42cf816262de547d56a7 Mon Sep 17 00:00:00 2001 From: Geoffrey Huntley Date: Tue, 8 Nov 2022 04:54:42 +1000 Subject: [PATCH 2/2] Update docs/admin/git-providers.md --- docs/admin/git-providers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin/git-providers.md b/docs/admin/git-providers.md index 45b2c2b03773f..a457ac717ede9 100644 --- a/docs/admin/git-providers.md +++ b/docs/admin/git-providers.md @@ -20,7 +20,7 @@ To add a git provider, you'll need to create an OAuth application. The following - [BitBucket](https://support.atlassian.com/bitbucket-cloud/docs/use-oauth-on-bitbucket-cloud/) - [Azure DevOps](https://learn.microsoft.com/en-us/azure/devops/integrate/get-started/authentication/oauth?view=azure-devops) -Example callback URL: `https://coder.example.com/api/v2/gitauth/primary-github/callback`. Use an arbitrary ID for your provider (e.g. `primary-github`). +Example callback URL: `https://coder.example.com/gitauth/primary-github/callback`. Use an arbitrary ID for your provider (e.g. `primary-github`). Set the following environment variables to [configure the Coder server](./configure.md):