How to set up a repository for an Ansible collection step by step

Get Help Guides, FAQs & Howtos
, ,
1

Hello everyone!

In the previous post we created a dummy module and its integration tests.
If you didn’t, please do.

Let’s now put that stuff in a GitHub repo.

Thankfully, we can use the collection_template repository to get many templates like README, GitHub workflow template for CI to automatically run the tests in a repo, Execution Environments-related ones and others not to re-invent the wheel.

1. Fork the collection_template repository by clicking the Fork button on its homepage.

2. In your GitHub profile create a repository for the collection using the collection_template repo as template:

create-repo
create-repo804×808 62.4 KB

3. Copy the local collection instance we created to somewhere as a backup and remove its original directory:

$ cp -r ansible_collections/my_namespace/my_collection ~/my_collection-back
$ rm -rf ansible_collections/my_namespace/my_collection

4. Clone the remote repo locally instead of the original source directory.

$ git clone git@github.com:Andersson007/my_namespace.my_collection.git ansible_collections/my_namespace/my_collection

5. Copy the module and its integration tests from the backup to the repo, change the current directory to it:

$ cp -r ~/my_collection-back/* ansible_collections/my_namespace/my_collection/
$ cd ansible_collections/my_namespace/my_collection

6. Create a new branch, add the directories we copied:

$ git checkout -b init_setup
$ git add plugins/ tests/

5. Change the following fields in the galaxy.yml file, in my case:

namespace: my_namespace
name: my_collection

For a real collection, fill it in carefully.

6. In the docs/docsite/links.yml change the following fields:

edit_on_github:
  repository: ansible-collections/community.REPO_NAME
...
extra_links:
  - description: Report an issue
    url: https://github.com/ansible-collections/community.REPO_NAME/issues/new/choose

in my case to:

edit_on_github:
  repository: Andersson007/my_namespace/my_collection
...
extra_links:
  - description: Report an issue
    url: https://github.com/Andersson007/my_namespace/my_collection/issues/new/choose

7. Run sanity and integration tests locally against the whole collection (not specifying files or targets as we did in the previous post) just to make sure they pass:

$ ansible-test sanity --docker
$ ansible-test integration --docker

8. Commit the changes and push to your remote repo

$ git commit -a -m "Initial commit"
$ git push origin init_setup

9. Go to your GitHub repo. You’ll probably see the suggestion to create a pull request (PR), do it.

create-pr
create-pr960×674 62.3 KB

If you don’t see it, go to the Pull requests tab and create it manually by clicking the New pull request button.

10. At the bottom of the PR page you’ll see a section with test jobs.

ci-box
ci-box948×944 96.2 KB

If something failed (has a red cross instead of a green check), you can click Details and see the reason.
In this case, go back to your local repo, fix it, then commit and push like in step 9.
Then check your PR again.
After all the checks are green, click the Merge pull request green button at the bottom of your PR to merge it.

11. Go to your local repo, switch to the main branch and update it by pulling the changes:

$ git checkout main
$ git pull upstream main

Here we go, we have the collection repo set up!

Now you can contribute to this collection following the algorithm above. Recap:

  1. In the main branch, run git pull upstream main to make sure it’s up-to-date
  2. Create a new branch
  3. Change the code
  4. Commit and push to upstream
  5. Create a pull request
  6. After test are green, if you’re the only maintainer, merge the PR, otherwise ask other maintainers to review before merging the PR.

In one of the next topics of this series, we’ll show you how to contribute to a collection outside of your GitHub profile/organization and cover other useful topics.

Don’t want to wait?

Please take a look at the following guidelines:

Any feedback is welcome in comments:) Thanks for reading!

4 Likes