Default variable details
Some of debops.yadm
default variables have more extensive configuration
than simple strings or lists, here you can find documentation and examples for
them.
yadm__dotfiles
The yadm__*_dotfiles
variables define a list of custom dotfile
git repositories to clone to the host, so that they are available
locally. The dotfiles will be cloned to the directory defined by the
yadm__dotfiles_root
variable, with subdirectories corresponding to
the repository host (for example github.com
), repository owner (for example
drybjed
), and finally the dotfiles.git
directory, which contains a bare
git repository itself.
The repositories are cloned and/or updated using the root
account, with
optional GPG signature verification. The role does not execute any code
contained in the repositories at this stage. Users are then able to use the
yadm script to install or update their desired dotfiles from the
local mirror instead of the remote repository. This can be done either
manually, or via other Ansible roles.
Because yadm uses the $HOME
directory directly as the
git work directory, it's best to avoid putting non-dotfile files
like README.md
and similar in the master
branch of the repository
(yadm will check it out by default). If you want to present a README
file in the dotfiles repository, you can put it on a separate git
branch and set it as default branch in the GitHub repository settings.
See yadm dotfile repository examples for an example repositories compatible with yadm script.
Examples
Clone dotfiles without any GPG signature verification:
yadm__dotfiles:
- name: 'user'
git:
- repo: 'https://github.com/user/dotfiles'
Disable the default drybjed
dotfiles from being cloned automatically and
remove them if they are present:
yadm__dotfiles:
- name: 'drybjed'
state: 'absent'
Syntax
The variables are YAML lists, each list entry is a YAML dictionary that uses specific parameters:
name
Required. A name of a given dotfile entry, not used otherwise. Entries with the same
name
parameter are merged together, this can be used to modify existing entries later on.state
Optional. If not specified or
present
, a given dotfile repository will be cloned or updated by the role. Ifabsent
, a given repository and GPG keys will be removed from the host, or will not be imported and cloned. Ifignore
, a given configuration entry will be ignored during evaluation by the role.gpg
Optional. A string containing a GPG key fingerprint used to sign the commits and/or tags in the dotfile repository; you can also specify multiple GPG fingerprints as a YAML list. Spaces in the fingerprint will be automatically removed. An alternative format is a YAML dictionary for each list element, with specific parameters:
id
The GPG key fingerprint.
keybase
Optional. The name of the Keybase profile which should be used to lookup the GPG key.
state
Optional, either
present
(import the GPG key) orabsent
(remove the GPG key from the keyring).
The specified GPG keys will be added to the
root
GPG keyring in the~/.gnupg/pubring.gpg
file and subsequently used to verify commits in cloned or updated git repositories.The GPG keys are managed via the debops.keyring Ansible role, see its documentation for more details.
git
Optional. A string containing an URL to the git repository with dotfiles; you can also specify multiple URLs as a YAML list. Only public repositories accessible via
https://
make sense - the role does not support cloning private repositories using a password, or repositories accessible over SSH connection. An alternative format is a YAML dictionary for each list element, with specific parameters:repo
The URL of the repository.
version
The git branch/tag to checkout - not useful because the role will clone bare git repositories without checking them out.