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

**URL:** <https://forum.ansible.com/t/how-to-set-up-a-repository-for-an-ansible-collection-step-by-step/10722>\
**Category:** Guides, FAQs & Howtos\
**Tags:** module, collections, getting-started, howto\
**Created:** [November 6, 2024, 8:45am UTC](https://forum.ansible.com/t/how-to-set-up-a-repository-for-an-ansible-collection-step-by-step/10722 "2024-11-06T08:45:42Z")\
**Posts on this page:** 1\
**Page:** 1

<div class="post-metadata">

**Author:** ![Andersson007](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/andersson007/32/89_2.png) [@Andersson007](https://forum.ansible.com/u/Andersson007)\
**Post date:** [November 6, 2024, 8:45am UTC](https://forum.ansible.com/t/how-to-set-up-a-repository-for-an-ansible-collection-step-by-step/10722/1 "2024-11-06T08:45:42Z")

</div>

Hello everyone!

In the [previous post](http://forum.ansible.com/t/how-to-create-an-ansible-collection-with-a-simple-module-step-by-step/9718) 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](https://github.com/ansible-collections/collection_template) 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](https://github.com/ansible-collections/collection_template) 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](https://us1.discourse-cdn.com/ansible/original/2X/a/aa8178364b2b2df9224e0eb1f3254c60bf83e148.png)

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

```bash
$ 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.

```bash
$ 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:

```bash
$ 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:

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

```

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

```yaml
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:

```yaml
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:

```yaml
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:

```bash
$ ansible-test sanity --docker
$ ansible-test integration --docker

```

#### 8. Commit the changes and push to your remote repo

```bash
$ 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](https://us1.discourse-cdn.com/ansible/original/2X/8/8c1b10fa4ff7268a907236437baccb6670dfc59a.png)

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](https://us1.discourse-cdn.com/ansible/original/2X/5/57745c2e3bc26079dba7b32f2933faaa8fd948f2.png)

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:

```bash
$ git checkout main
$ git pull upstream main

```

There 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.

Read the next topic [How to release an Ansible collection step by step](https://forum.ansible.com/t/how-to-release-an-ansible-collection-step-by-step/38879).

## References

- [Ansible collection creator path](https://docs.ansible.com/ansible/latest/dev_guide/developing_collections_path.html): a consistent overview of the Ansible collection creator journey from an idea for the first module/role to having your collection included in the Ansible community package.
- [Ansible developer journey](https://docs.ansible.com/developers.html)

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