|
| 1 | +#Git Providers |
| 2 | + |
| 3 | +Coder integrates with git providers so developers can authenticate with repositories within their workspace. |
| 4 | + |
| 5 | +##How it works |
| 6 | + |
| 7 | +When developers use`git` inside their workspace, they are first prompted to authenticate. After that, Coder will store/refresh tokens for future operations. |
| 8 | + |
| 9 | +<videoautoplayplaysinlineloop> |
| 10 | + <sourcesrc="https://github.com/coder/coder/blob/main/site/static/gitauth.mp4?raw=true"type="video/mp4"> |
| 11 | +Your browser does not support the video tag. |
| 12 | +</video> |
| 13 | + |
| 14 | +##Configuration |
| 15 | + |
| 16 | +To add a git provider, you'll need to create an OAuth application. The following providers are supported: |
| 17 | + |
| 18 | +-[GitHub](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app) (GitHub apps are also supported) |
| 19 | +-[GitLab](https://docs.gitlab.com/ee/integration/oauth_provider.html) |
| 20 | +-[BitBucket](https://support.atlassian.com/bitbucket-cloud/docs/use-oauth-on-bitbucket-cloud/) |
| 21 | +-[Azure DevOps](https://learn.microsoft.com/en-us/azure/devops/integrate/get-started/authentication/oauth?view=azure-devops) |
| 22 | + |
| 23 | +Example callback URL:`https://coder.example.com/gitauth/primary-github/callback`. Use an arbitrary ID for your provider (e.g.`primary-github`). |
| 24 | + |
| 25 | +Set the following environment variables to[configure the Coder server](./configure.md): |
| 26 | + |
| 27 | +```sh |
| 28 | +CODER_GITAUTH_0_ID="primary-github" |
| 29 | +CODER_GITAUTH_0_TYPE=github|gitlab|azure-devops|bitbucket |
| 30 | +CODER_GITAUTH_0_CLIENT_ID=xxxxxx |
| 31 | +CODER_GITAUTH_0_CLIENT_SECRET=xxxxxxx |
| 32 | +``` |
| 33 | + |
| 34 | +###Self-managed git providers |
| 35 | + |
| 36 | +Custom authentication and token URLs should be |
| 37 | +used for self-managed Git provider deployments. |
| 38 | + |
| 39 | +```sh |
| 40 | +CODER_GITAUTH_0_AUTH_URL="https://github.example.com/oauth/authorize" |
| 41 | +CODER_GITAUTH_0_TOKEN_URL="https://github.example.com/oauth/token" |
| 42 | +``` |
| 43 | + |
| 44 | +###Custom scopes |
| 45 | + |
| 46 | +Optionally, you can request custom scopes: |
| 47 | + |
| 48 | +```sh |
| 49 | +CODER_GITAUTH_0_SCOPES="repo:read repo:write write:gpg_key" |
| 50 | +``` |
| 51 | + |
| 52 | +###Multiple git providers (enterprise) |
| 53 | + |
| 54 | +Multiple providers are an Enterprise feature.[Learn more](../enterprise.md). |
| 55 | + |
| 56 | +A custom regex can be used to match a specific repository or organization to limit auth scope. Here's a sample config: |
| 57 | + |
| 58 | +```sh |
| 59 | +# Provider 1) github.com |
| 60 | +CODER_GITAUTH_0_ID=primary-github |
| 61 | +CODER_GITAUTH_0_TYPE=github |
| 62 | +CODER_GITAUTH_0_CLIENT_ID=xxxxxx |
| 63 | +CODER_GITAUTH_0_CLIENT_SECRET=xxxxxxx |
| 64 | +CODER_GITAUTH_0_REGEX=github.com/orgname |
| 65 | + |
| 66 | +# Provider 2) github.example.com |
| 67 | +CODER_GITAUTH_1_ID=secondary-github |
| 68 | +CODER_GITAUTH_1_TYPE=github |
| 69 | +CODER_GITAUTH_1_CLIENT_ID=xxxxxx |
| 70 | +CODER_GITAUTH_1_CLIENT_SECRET=xxxxxxx |
| 71 | +CODER_GITAUTH_1_REGEX=github.example.com |
| 72 | +CODER_GITAUTH_1_AUTH_URL="https://github.example.com/oauth/authorize" |
| 73 | +CODER_GITAUTH_1_TOKEN_URL="https://github.example.com/oauth/token" |
| 74 | +``` |
| 75 | + |
| 76 | +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): |
| 77 | + |
| 78 | +```sh |
| 79 | +git config --global credential.useHttpPathtrue |
| 80 | +``` |