Skip to main content

146. Dependency on Bootstrap Key

Status: Accepted Date: 2025-07-06

Context​

The 27_chezmoi role's primary function is to initialize a user's dotfiles from a private Git repository hosted on GitHub. To clone a private repository, it needs to authenticate with GitHub. This authentication is performed using a dedicated SSH key.

Decision​

This ADR formally documents a critical dependency and ordering requirement.

The 27_chezmoi role must run after the 02_ssh role.

The 02_ssh role is responsible for deploying the bootstrap SSH key and the minimal SSH config that allows for passwordless authentication to GitHub (adr://bootstrap-ssh-strategy, adr://minimal-ssh-config). The chezmoi init command, executed by the 27_chezmoi role, will fail if it cannot successfully authenticate to GitHub to clone the dotfiles repository.

This defines a hard dependency in our numbered role system (adr://role-based-organization). The number 27 was chosen to be significantly after 02 to ensure this dependency is met and to leave room for other intermediate setup tasks.

Consequences​

Positive:

  • Explicit Dependency: Makes the critical dependency between the two roles explicit and documents it as a formal architectural decision.
  • Enforces Correct Ordering: The numbered role system enforces this dependency at a technical level, ensuring the playbook cannot be run in an incorrect order.
  • Improved Debugging: If the 27_chezmoi role fails with an authentication error, this ADR provides immediate context, pointing the developer to check the output and success of the 02_ssh role first.

Negative:

  • Creates Inflexibility: The role ordering is now rigid. We cannot easily run the chezmoi role without also having run the ssh role.

Mitigation:

  • Logical and Necessary Rigidity: This rigidity is not a flaw; it is a logical necessity. It is impossible to clone a private repository without first having the credentials to do so. This ADR simply documents a fundamental requirement of the process. The "inflexibility" is a feature that prevents incorrect or failed playbook runs.