opensource/coder
3
0
Fork 0
mirror of https://github.com/coder/coder.git synced 2026-09-24 15:04:27 +08:00
Code Issues Packages Projects Releases Wiki Activity

chore(docs): update docs for correct use of shell and console and enforce linewidth (#9245)

Browse Source
This commit is contained in:
Muhammad Atif Ali
2023-08-23 12:27:57 +03:00
committed by GitHub
parent ed2b1236c0
commit d37f6d80f7
96 changed files with 2838 additions and 1457 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/admin/git-providers.md
+42 -23
View File
@@ -1,10 +1,13 @@
# Git Providers
Coder integrates with git providers to automate away the need for developers to authenticate with repositories within their workspace.
Coder integrates with git providers to automate away the need for developers to
authenticate with repositories within their workspace.
## How it works
When developers use `git` inside their workspace, they are prompted to authenticate. After that, Coder will store and refresh tokens for future operations.
When developers use `git` inside their workspace, they are prompted to
authenticate. After that, Coder will store and refresh tokens for future
operations.
<video autoplay playsinline loop>
<source src="https://github.com/coder/coder/blob/main/site/static/gitauth.mp4?raw=true" type="video/mp4">
@@ -13,18 +16,22 @@ Your browser does not support the video tag.
## Configuration
To add a git provider, you'll need to create an OAuth application. The following providers are supported:
To add a git provider, you'll need to create an OAuth application. The following
providers are supported:
- [GitHub](#github-app)
- [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/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):
Set the following environment variables to
[configure the Coder server](./configure.md):
```console
```env
CODER_GITAUTH_0_ID="primary-github"
CODER_GITAUTH_0_TYPE=github|gitlab|azure-devops|bitbucket
CODER_GITAUTH_0_CLIENT_ID=xxxxxx
@@ -33,11 +40,15 @@ CODER_GITAUTH_0_CLIENT_SECRET=xxxxxxx
### GitHub
1. [Create a GitHub App](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app) to enable fine-grained access to specific repositories, or a subset of permissions for security.
1. [Create a GitHub App](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app)
to enable fine-grained access to specific repositories, or a subset of
permissions for security.
![Register GitHub App](../images/admin/github-app-register.png)
2. Adjust the GitHub App permissions. You can use more or less permissions than are listed here, this is merely a suggestion that allows users to clone repositories:
2. Adjust the GitHub App permissions. You can use more or less permissions than
are listed here, this is merely a suggestion that allows users to clone
repositories:
![Adjust GitHub App Permissions](../images/admin/github-app-permissions.png)
@@ -48,7 +59,8 @@ CODER_GITAUTH_0_CLIENT_SECRET=xxxxxxx
| Workflows | Read & Write | Grants access to update files in `.github/workflows/`. |
| Metadata | Read-only | Grants access to metadata written by GitHub Apps. |
3. Install the App for your organization. You may select a subset of repositories to grant access to.
3. Install the App for your organization. You may select a subset of
repositories to grant access to.
![Install GitHub App](../images/admin/github-app-install.png)
@@ -56,7 +68,7 @@ CODER_GITAUTH_0_CLIENT_SECRET=xxxxxxx
GitHub Enterprise requires the following authentication and token URLs:
```console
```env
CODER_GITAUTH_0_VALIDATE_URL="https://github.example.com/login/oauth/access_token/info"
CODER_GITAUTH_0_AUTH_URL="https://github.example.com/login/oauth/authorize"
CODER_GITAUTH_0_TOKEN_URL="https://github.example.com/login/oauth/access_token"
@@ -66,7 +78,7 @@ CODER_GITAUTH_0_TOKEN_URL="https://github.example.com/login/oauth/access_token"
Azure DevOps requires the following environment variables:
```console
```env
CODER_GITAUTH_0_ID="primary-azure-devops"
CODER_GITAUTH_0_TYPE=azure-devops
CODER_GITAUTH_0_CLIENT_ID=xxxxxx
@@ -78,10 +90,10 @@ CODER_GITAUTH_0_TOKEN_URL="https://app.vssps.visualstudio.com/oauth2/token"
### Self-managed git providers
Custom authentication and token URLs should be
used for self-managed Git provider deployments.
Custom authentication and token URLs should be used for self-managed Git
provider deployments.
```console
```env
CODER_GITAUTH_0_AUTH_URL="https://github.example.com/oauth/authorize"
CODER_GITAUTH_0_TOKEN_URL="https://github.example.com/oauth/token"
CODER_GITAUTH_0_VALIDATE_URL="https://your-domain.com/oauth/token/info"
@@ -91,7 +103,7 @@ CODER_GITAUTH_0_VALIDATE_URL="https://your-domain.com/oauth/token/info"
Optionally, you can request custom scopes:
```console
```env
CODER_GITAUTH_0_SCOPES="repo:read repo:write write:gpg_key"
```
@@ -99,9 +111,10 @@ CODER_GITAUTH_0_SCOPES="repo:read repo:write write:gpg_key"
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:
A custom regex can be used to match a specific repository or organization to
limit auth scope. Here's a sample config:
```console
```env
# Provider 1) github.com
CODER_GITAUTH_0_ID=primary-github
CODER_GITAUTH_0_TYPE=github
@@ -120,20 +133,24 @@ CODER_GITAUTH_1_TOKEN_URL="https://github.example.com/login/oauth/access_token"
CODER_GITAUTH_1_VALIDATE_URL="https://github.example.com/login/oauth/access_token/info"
```
To support regex matching for paths (e.g. github.com/orgname), you'll need to add this to the [Coder agent startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script):
To support regex matching for paths (e.g. github.com/orgname), you'll need to
add this to the
[Coder agent startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script):
```console
```shell
git config --global credential.useHttpPath true
```
## Require git authentication in templates
If your template requires git authentication (e.g. running `git clone` in the [startup_script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script)), you can require users authenticate via git prior to creating a workspace:
If your template requires git authentication (e.g. running `git clone` in the
[startup_script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script)),
you can require users authenticate via git prior to creating a workspace:
![Git authentication in template](../images/admin/git-auth-template.png)
The following example will require users authenticate via GitHub and auto-clone a repo
into the `~/coder` directory.
The following example will require users authenticate via GitHub and auto-clone
a repo into the `~/coder` directory.
```hcl
data "coder_git_auth" "github" {
@@ -156,4 +173,6 @@ EOF
}
```
See the [Terraform provider documentation](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/git_auth) for all available options.
See the
[Terraform provider documentation](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/git_auth)
for all available options.