cchurch.scm

SCM

This role is used to checkout code from Source Control Management (SCM) systems like git, hg (Mercurial), or svn (Subversion).

Requirements

If you are checking out code using SSH, you need to have a deployment key for the user specified in scm_target_user, or you must enable SSH agent forwarding for the Ansible connection.

You will need administrative privileges to install the SCM package, checkout code as a different user (if scm_target_user is not the same as ansible_user), or create the scm_target_user account.

Role Variables

Here are the main variables you can set for this role:

scm_type: The type of SCM to use. It can be git (default), hg, or svn.
scm_url: The URL of the repository (required). For example, http://server/repo or ssh://server/repo.
scm_version: The specific branch, tag, revision, or commit you wish to checkout, like master or HEAD.
scm_force: A true/false option that tells the SCM to discard modified files in an existing directory. Default is false.
scm_delete_on_update: A true/false option that decides whether to delete the target folder before updating. Default is false.
scm_username: The username needed to access scm_url, used only with svn.
scm_password: The password for scm_url, used only with svn.
scm_target_path: The directory where the code will be checked out (defaults to "~/src").
scm_target_user: The user account to use for checking out the code (default is ansible_user, which means no special privileges are needed). This user will be created if it's different from ansible_user.
scm_target_user_home: The home directory for the new scm_target_user.

Additional variables to customize this role (though not often needed):

scm_accept_hostkey: A true/false option for SSH host key acceptance. Default is true for git.
scm_depth: To create a shallow clone (minimum value is 1), applicable only for git.
scm_executable: The path to the git, hg, or svn executable.
scm_export: To export instead of checkout/update (works with svn).
scm_key_file: A path to a private key file for git checkouts.
scm_purge: To delete untracked files when updating (only for hg).
scm_recursive: A true/false option to clone the repository, including any submodules (for git).
scm_remote: The name of the remote repository (only for git).
scm_switch: To switch within svn before updating.
scm_track_submodules: A true/false option to track latest commits in submodules (for git).
scm_update: A true/false option to pull in new changes from the main repository.
scm_verify_commit: A true/false option to check GPG signed commits (for git).
scm_packages: Packages required for your specific system's package manager.
scm_ssh_agent_forwarding: A true/false option to allow SSH agent forwarding when scm_target_user differs from ansible_user.
scm_ssh_auth_sock_sudoers_file: File path added to sudoers.d when enabling SSH agent forwarding.

You can also define a variable for notifications:

scm_notify_on_updated: The handler name to notify when the checkout changes. The default is "scm updated".

The role will also set a fact called scm_update_result to show the result of the update task for each host.

Dependencies

None.

Example Playbook

Here's an example playbook that checks out a public git repository and notifies after updating:

- hosts: all
  roles:
    - role: cchurch.scm
      vars:
        scm_type: git
        scm_url: https://github.com/cchurch/ansible-sign.git
        scm_target_path: ~/src/ansible-sign
        scm_version: master
  handlers:
    - name: ansible sign updated
      debug:
        msg: "{{ scm_target_path }} was updated from {{ scm_url }} to {{ scm_update_result.after }}."
      listen: scm updated