I have been working on deploying some VMs in a development environment at work, which I wanted to configure with Ansible and as part of that I needed to manage the hosts file. Fortunately I already have an Ansible role for doing that that I wrote in April so, rather than email (or get some other way) the code to myself, I decided to publish it on GitHub and install the role from there both sides.

Migrating role to GitHub

Fortunately this is really straight-forward - the form of the role repository is exactly the same as the folder inside roles alongside a playbook. So, it was just a case of copying this and wrapping it with a README.md and my preferred licence, the GNU General Public License v3. To start this process, I created a new repository in GitHub and accepted their templates for these two files:

Initialised repository screenshot

I decided to attempt to copy with preserved history, based on some instructions I found on StackOverflow.

First step, clone the new repository:

git clone https://github.com/loz-hurst/ansible-role-hosts-file.git

Which failed with Support for password authentication was removed on August 13, 2021. (which I’d forgotten - shows how often I’ve been using GitHub lately!), with a link to “information on currently recommended modes of authentication” telling I had to setup a new personal access token and try again. Which I did, replacing the old PAT that expired in 2023.

Next, I went to my existing repository and verified there were no uncommitted changes to the role:

$ git status roles/hosts-file
[...]
nothing to commit, working tree clean

before creating a patch file:

git log \
  --pretty=email \
  --patch-with-stat \
  --reverse \
  --full-index \
  --binary \
  -m \
  --first-parent \
  -- roles/hosts-file \
  > hosts-file-role-export.patch

I then changed to the new repository and applied the patch:

git am -p3 --committer-date-is-author-date < hosts-file-role-export.patch

(-p3 strips off the roles/hosts-file part of the original paths)

This preserved the history, although the log looks a bit weird with the older commit coming after the initial commit according to the dates:

$ git log
[...]
Date:   Sun Apr 14 16:51:51 2024 +0100

    hosts-file role added
[...]
Date:   Fri Aug 30 10:06:34 2024 +0100

    Initial commit

At this point I discovered that I had only made one commit to that role, so other than preserving the date that I originally did the work there was little benefit to going through these motions but a useful exercise and now I know how to do it for the future…

I topped each file with the recommended GNU GPL licence text and updated the README.md, just adding a summary of what the role does and a copy & paste of meta/argument_specs.yaml reworked slightly to be more human-friendly.

When I came to install it (see “Using the role” below), I found that ansible-galaxy refuses to install it without a meta/main.yml file so I added one:

---
galaxy_info:
  role_name: hosts_file
  author: Laurence Alexander Hurst
  description: Ansible role for managing hosts files on a variety of operating systems
  license: GPLv3
  # Not been tested on anything prior to this - may work but YMMV
  min_ansible_version: 2.16.3
...

In the process, I renamed the role (and repository) from hosts-file to hosts_file, to match Ansible Galaxy naming requirements. This also had the neat side-effect of meaning I could update everything to the new role name and test it was working, before deleting the old role.

Using the role

To use the role, I added it to the requirements.yaml file in my main playbook repository (where I had exported it from):

---

roles:
  - name: hosts_file
    src: https://github.com/loz-hurst/ansible-role-hosts_file.git

#[...]
...

And installed using:

ansible-galaxy install -r requirements.yml

Once I was satisfied everything was happily using the new role, I deleted the old role’s files from my playbook repository’s roles directory.