Skip to main content

133. Minimal Bootstrap SSH Config

Status: Accepted Date: 2025-07-06

Context​

As part of our bootstrap SSH strategy (adr://bootstrap-ssh-strategy), we deploy a dedicated SSH key pair (id_ed25519.github) that is used to clone our dotfiles from GitHub. For this key to be used automatically, we need an SSH configuration that tells the SSH client to use this specific key when connecting to github.com.

We do not want Ansible to manage the user's full, complex ~/.ssh/config file, as that is part of their personal environment and should be managed by their dotfiles.

Decision​

The 02_ssh Ansible role will create a minimal ~/.ssh/config file with a single purpose: to associate the bootstrap key with the github.com host.

The generated config file will contain only one entry:

Host github.com
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519.github

This file will be created with secure permissions. It is a temporary, single-purpose configuration. Later in the Ansible run, the 27_chezmoi role will deploy the user's full dotfiles, which will overwrite this minimal file with the user's complete, personal ~/.ssh/config.

Consequences​

Positive:

  • Enables Automated Cloning: This configuration is the critical link that allows the subsequent chezmoi role to clone the dotfiles repository from GitHub without requiring a password or interactive prompt.
  • Minimalism: Ansible manages the absolute bare minimum required to get the process started. It does not touch any other host configurations or user preferences.
  • Clear Separation of Concerns: Reinforces the separation between infrastructure provisioning (Ansible's job) and user environment configuration (chezmoi's job). Ansible creates the temporary bootstrap config, and chezmoi replaces it with the final, authoritative one.

Negative:

  • Temporary File: This config file is created only to be overwritten shortly after. This could be seen as slightly inefficient.
  • Potential for Confusion: A user inspecting the ~/.ssh/config file mid-provisioning might be confused by its minimal content.

Mitigation:

  • Necessary Step: Creating and then overwriting this file is a necessary and deliberate part of the bootstrap process. The inefficiency is negligible.
  • Automated Process: The provisioning process is fully automated and runs quickly. The window during which this temporary file exists is very short, so the risk of user confusion is minimal. The process is designed to be a self-contained, atomic operation.