blinkagent[bot] a0a3783a51

docs(dotfiles): add hint about using SSH URLs when HTTPS cloning is restricted (#757 )

Some Git providers (e.g. on-prem GitLab) disable HTTPS cloning by
default, which causes the dotfiles clone to silently fail during
workspace startup. Users see "Startup scripts are still running" but the
dotfiles folder is never populated.

This PR adds two small documentation touches:

1. **`main.tf` default description** — appends a one-liner suggesting
SSH URLs when HTTPS is restricted. This is what users see in the Coder
UI parameter prompt.
2. **`README.md`** — new "SSH vs HTTPS URLs" section with an example and
a brief explanation of why SSH URLs are more reliable during startup.

No logic changes, no new variables — just documentation.

---------

Co-authored-by: blink-so[bot] <211532188+blink-so[bot]@users.noreply.github.com>
Co-authored-by: DevCats <christofer@coder.com>

2026-02-27 14:48:55 -06:00

2.8 KiB

Raw Blame History

display_name

description

icon

verified

Dotfiles

Allow developers to optionally bring their own dotfiles repository.

This will prompt the user for their dotfiles repository URL on template creation using a coder_parameter.

Under the hood, this module uses the coder dotfiles command.

module "dotfiles" {
  count    = data.coder_workspace.me.start_count
  source   = "registry.coder.com/coder/dotfiles/coder"
  version  = "1.3.2"
  agent_id = coder_agent.example.id
}

Examples

Apply dotfiles as the current user

module "dotfiles" {
  count    = data.coder_workspace.me.start_count
  source   = "registry.coder.com/coder/dotfiles/coder"
  version  = "1.3.2"
  agent_id = coder_agent.example.id
}

Apply dotfiles as another user (only works if sudo is passwordless)

module "dotfiles" {
  count    = data.coder_workspace.me.start_count
  source   = "registry.coder.com/coder/dotfiles/coder"
  version  = "1.3.2"
  agent_id = coder_agent.example.id
  user     = "root"
}

Apply the same dotfiles as the current user and root (the root dotfiles can only be applied if sudo is passwordless)

module "dotfiles" {
  count    = data.coder_workspace.me.start_count
  source   = "registry.coder.com/coder/dotfiles/coder"
  version  = "1.3.2"
  agent_id = coder_agent.example.id
}

module "dotfiles-root" {
  count        = data.coder_workspace.me.start_count
  source       = "registry.coder.com/coder/dotfiles/coder"
  version      = "1.3.2"
  agent_id     = coder_agent.example.id
  user         = "root"
  dotfiles_uri = module.dotfiles.dotfiles_uri
}

SSH vs HTTPS URLs

If your Git provider (e.g. GitLab, GitHub Enterprise) restricts HTTPS cloning, use an SSH URL instead:

# HTTPS (may fail if HTTP cloning is disabled)
https://gitlab.example.com/user/dotfiles.git

# SSH (uses the workspace's SSH key)
git@gitlab.example.com:user/dotfiles.git

When a Git provider has HTTPS cloning disabled server-side, the clone will silently fail (the .git folder may exist but the working tree will be empty). SSH URLs avoid this because they authenticate with the workspace's SSH key instead of a token-based HTTPS flow.

Setting a default dotfiles repository

You can set a default dotfiles repository for all users by setting the default_dotfiles_uri variable:

module "dotfiles" {
  count                = data.coder_workspace.me.start_count
  source               = "registry.coder.com/coder/dotfiles/coder"
  version              = "1.3.2"
  agent_id             = coder_agent.example.id
  default_dotfiles_uri = "https://github.com/coder/dotfiles"
}

2.8 KiB Raw Blame History