Skip to content
Coder Docs
Get startedCustomize your template

Clone private repositories

Clone private GitHub repositories in your workspace using a Coder external-auth data source.

On this page

Now that you've finished Launch your first workspace, you can let your workspaces clone private GitHub repositories without a manual login each time.

The Quickstart template already clones public repositories through its Git Repository (Optional) parameter with no extra setup. A private repository needs authentication, which is what you add here. In this guide, you add the coder_external_auth data source, connect your workspace to GitHub, and clone a private repository with no manual login. This guide uses GitHub, and the same external-auth pattern works for other providers.

Note

This guide assumes your Quickstart template is open for editing. If it's not, you can edit the template from the web by finding the template, selecting the three dots menu, and selecting Edit files. Refer to Customize workspace startup for more information.

What you'll do

  • Check mark Add the coder_external_auth data source to the template.
  • Check mark Connect your workspace to GitHub with the Login with GitHub button.
  • Check mark Clone a private repository without a manual login.

Data sources for their side effect

You already met one data source in Add a programming language: coder_parameter reads a choice from the workspace owner.

coder_external_auth is a data source you add for its side effect rather than its value. Its presence tells Coder that a workspace requires an authenticated session with a provider before it starts. The id points at a provider configured on the Coder deployment, and the local Coder server you started in Part 1 already has a github provider available.

Note

External authentication lets a workspace sign in to an outside service, such as a Git provider, before it starts. A default Coder install includes a built-in GitHub app, so id = "github" works without extra setup. An admin can configure other providers (GitLab, Bitbucket, Azure DevOps, or generic OIDC) or replace the built-in GitHub app. To learn more, refer to External authentication.

Require GitHub authentication

Add this coder_external_auth block to main.tf:

data "coder_external_auth" "github" {
  id = "github"
}

Then publish a new version of the template:

In the web editor, add the coder_external_auth block to main.tf. Select Build, wait for the build to pass, then select Publish.

Warning

Adding this block makes GitHub authentication required: a workspace on this template can't start until you authenticate, with no option to skip. If you'd rather leave it optional, set optional = true in the coder_external_auth block so users can skip authentication when they create or update a workspace.

Connect your workspace to GitHub

Update the workspace you built in Launch your first workspace to the version you just published. Because the local Coder server is already connected to GitHub, you don't configure an OAuth app; you only authorize the workspace.

On your workspace, select Update. The update form shows a Login with GitHub button: select it, follow the prompts to authorize Coder, then select Update and restart. The following screenshot shows the External Authentication section of the workspace creation screen before connecting GitHub:

External Authentication with GitHub before logging inExternal Authentication with GitHub before logging in

Once you authorize Coder, the workspace starts, and Coder stores and refreshes your GitHub token for later builds. After authorizing Coder, Coder replaces the Login with GitHub button with an Authenticated message:

External Authentication with GitHub after logging inExternal Authentication with GitHub after logging in

Clone a private repository

Now that your workspace is connected to GitHub, point the Git Repository (Optional) parameter at a private repository.

On your workspace, set Git Repository (Optional) to your private repository URL in the update form, then select Update and restart.

On the next build, the workspace clones the private repository with no manual login, because Coder supplies your GitHub token to git.

What just happened

You added one data source and connected your workspace to GitHub:

  • coder_external_auth declared that the workspace needs an authenticated GitHub session before it starts.
  • Selecting Login with GitHub authorized Coder, and Coder now supplies a GitHub token to git for every build.

A coder_parameter reads an answer from the workspace owner. A coder_external_auth data source reaches outside the template for a prerequisite the deployment provides. Both are data sources, and neither creates infrastructure.

Final code

What's next?

You finished the Customize your template series, and your workspaces can now clone private repositories.

This is the last guide in the series. To keep going, explore more of what Coder offers:

Or revisit the Customize your template overview for the full list of guides.

Learn more

Edit on GitHub