diff --git a/docs/guides/cloning-git-repositories.md b/docs/guides/cloning-git-repositories.md new file mode 100644 index 0000000000000..40813f249277a --- /dev/null +++ b/docs/guides/cloning-git-repositories.md @@ -0,0 +1,72 @@ +# Cloning Git Repositories + +
+ Author: + + Bruno Quaresma + + +
+August 06, 2024 + +--- + +When starting to work on a project, engineers usually need to clone a Git +repository. Even though this is often a quick step, it can be automated using +the [Coder Registry](https://registry.coder.com/) to make a seamless Git-first +workflow. + +The first step to enable Coder to clone a repository is to provide +authorization. This can be achieved by using the Git provider, such as GitHub, +as an authentication method. If you don't know how to do that, we have written +documentation to help you: + +- [GitHub](https://coder.com/docs/admin/auth#github) +- [GitLab self-managed](https://coder.com/docs/admin/external-auth#gitlab-self-managed) +- [Self-managed git providers](https://coder.com/docs/admin/external-auth#self-managed-git-providers) + +With the authentication in place, it is time to set up the template to use the +[Git Clone module](https://registry.coder.com/modules/git-clone) from the +[Coder Registry](https://registry.coder.com/) by adding it to our template's +Terraform configuration. + +```hcl +module "git-clone" { + source = "registry.coder.com/modules/git-clone/coder" + version = "1.0.12" + agent_id = coder_agent.example.id + url = "https://github.com/coder/coder" +} +``` + +> You can edit the template using an IDE or terminal of your preference, or by +> going into the +> [template editor UI](https://coder.com/docs/templates/creating#editing-templates). + +You can also use +[template parameters](https://coder.com/docs/templates/parameters) to customize +the Git URL and make it dynamic for use cases where a template supports multiple +projects. + +```hcl +data "coder_parameter" "git_repo" { + name = "git_repo" + display_name = "Git repository" + default = "https://github.com/coder/coder" +} + +module "git-clone" { + source = "registry.coder.com/modules/git-clone/coder" + version = "1.0.12" + agent_id = coder_agent.example.id + url = data.coder_parameter.git_repo.value +} +``` + +> If you need more customization, you can read the +> [Git Clone module](https://registry.coder.com/modules/git-clone) documentation +> to learn more about the module. + +Don't forget to build and publish the template changes before creating a new +workspace. You can check if the repository is cloned by accessing the workspace +terminal and listing the directories. diff --git a/docs/manifest.json b/docs/manifest.json index 82dd73ada47c8..6fe08f10191d2 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -1164,6 +1164,11 @@ "title": "Scanning Coder Workspaces with JFrog Xray", "description": "Integrate Coder with JFrog Xray", "path": "./guides/xray-integration.md" + }, + { + "title": "Cloning Git Repositories", + "description": "Automatically clone Git repositories into your workspace", + "path": "./guides/cloning-git-repositories.md" } ] }