.. _developing_galaxy: ********************** Galaxy Developer Guide ********************** You can host collections and roles on Galaxy to share with the Ansible community. Galaxy content is formatted in pre-packaged units of work such as :ref:`roles `, and new in Galaxy 3.2, :ref:`collections `. You can create roles for provisioning infrastructure, deploying applications, and all of the tasks you do everyday. Taking this a step further, you can create collections which provide a comprehensive package of automation that may include multiple playbooks, roles, modules, and plugins. .. contents:: :local: :depth: 2 .. _creating_collections_galaxy: Creating collections for Galaxy =============================== Collections are a distribution format for Ansible content. You can use collections to package and distribute playbooks, roles, modules, and plugins. You can publish and use collections through `Ansible Galaxy `_. See :ref:`developing_collections` for details on how to create collections. .. _creating_roles_galaxy: Creating roles for Galaxy ========================= Use the ``init`` command to initialize the base structure of a new role, saving time on creating the various directories and main.yml files a role requires .. code-block:: bash $ ansible-galaxy init role_name The above will create the following directory structure in the current working directory: .. code-block:: text role_name/ README.md .travis.yml defaults/ main.yml files/ handlers/ main.yml meta/ main.yml templates/ tests/ inventory test.yml vars/ main.yml If you want to create a repository for the role, the repository root should be `role_name`. Force ----- If a directory matching the name of the role already exists in the current working directory, the init command will result in an error. To ignore the error use the ``--force`` option. Force will create the above subdirectories and files, replacing anything that matches. Container enabled ----------------- If you are creating a Container Enabled role, pass ``--type container`` to ``ansible-galaxy init``. This will create the same directory structure as above, but populate it with default files appropriate for a Container Enabled role. For instance, the README.md has a slightly different structure, the *.travis.yml* file tests the role using `Ansible Container `_, and the meta directory includes a *container.yml* file. Using a custom role skeleton ---------------------------- A custom role skeleton directory can be supplied as follows: .. code-block:: bash $ ansible-galaxy init --role-skeleton=/path/to/skeleton role_name When a skeleton is provided, init will: - copy all files and directories from the skeleton to the new role - any .j2 files found outside of a templates folder will be rendered as templates. The only useful variable at the moment is role_name - The .git folder and any .git_keep files will not be copied Alternatively, the role_skeleton and ignoring of files can be configured via ansible.cfg .. code-block:: text [galaxy] role_skeleton = /path/to/skeleton role_skeleton_ignore = ^.git$,^.*/.git_keep$ Authenticate with Galaxy ------------------------ Using the ``import``, ``delete`` and ``setup`` commands to manage your roles on the Galaxy website requires authentication in the form of an API key, you must create an account on the Galaxy website. #. Log in to the Galaxy website and open the `Preferences `_ view. #. Select **Show API key** and then copy it. #. Save your token in the path set in the :ref:`GALAXY_TOKEN_PATH`. Import a role ------------- The ``import`` command requires that you first authenticate using the ``login`` command. Once authenticated you can import any GitHub repository that you own or have been granted access. Use the following to import to role: .. code-block:: bash $ ansible-galaxy import github_user github_repo By default the command will wait for Galaxy to complete the import process, displaying the results as the import progresses: .. code-block:: text Successfully submitted import request 41 Starting import 41: role_name=myrole repo=githubuser/ansible-role-repo ref= Retrieving GitHub repo githubuser/ansible-role-repo Accessing branch: devel Parsing and validating meta/main.yml Parsing galaxy_tags Parsing platforms Adding dependencies Parsing and validating README.md Adding repo tags as role versions Import completed Status SUCCESS : warnings=0 errors=0 Branch ^^^^^^ Use the ``--branch`` option to import a specific branch. If not specified, the default branch for the repo will be used. Role name ^^^^^^^^^ By default the name given to the role will be derived from the GitHub repository name. However, you can use the ``--role-name`` option to override this and set the name. No wait ^^^^^^^ If the ``--no-wait`` option is present, the command will not wait for results. Results of the most recent import for any of your roles is available on the Galaxy web site by visiting *My Imports*. Delete a role ------------- The ``delete`` command requires that you first authenticate using the ``login`` command. Once authenticated you can remove a role from the Galaxy web site. You are only allowed to remove roles where you have access to the repository in GitHub. Use the following to delete a role: .. code-block:: bash $ ansible-galaxy delete github_user github_repo This only removes the role from Galaxy. It does not remove or alter the actual GitHub repository. Travis integrations ------------------- You can create an integration or connection between a role in Galaxy and `Travis `_. Once the connection is established, a build in Travis will automatically trigger an import in Galaxy, updating the search index with the latest information about the role. You create the integration using the ``setup`` command, but before an integration can be created, you must first authenticate using the ``login`` command; you will also need an account in Travis, and your Travis token. Once you're ready, use the following command to create the integration: .. code-block:: bash $ ansible-galaxy setup travis github_user github_repo xxx-travis-token-xxx The setup command requires your Travis token, however the token is not stored in Galaxy. It is used along with the GitHub username and repo to create a hash as described in `the Travis documentation `_. The hash is stored in Galaxy and used to verify notifications received from Travis. The setup command enables Galaxy to respond to notifications. To configure Travis to run a build on your repository and send a notification, follow the `Travis getting started guide `_. To instruct Travis to notify Galaxy when a build completes, add the following to your .travis.yml file: .. code-block:: text notifications: webhooks: https://galaxy.ansible.com/api/v1/notifications/ List Travis integrations ^^^^^^^^^^^^^^^^^^^^^^^^ Use the ``--list`` option to display your Travis integrations: .. code-block:: bash $ ansible-galaxy setup --list ID Source Repo ---------- ---------- ---------- 2 travis github_user/github_repo 1 travis github_user/github_repo Remove Travis integrations ^^^^^^^^^^^^^^^^^^^^^^^^^^ Use the ``--remove`` option to disable and remove a Travis integration: .. code-block:: bash $ ansible-galaxy setup --remove ID Provide the ID of the integration to be disabled. You can find the ID by using the ``--list`` option. .. seealso:: :ref:`collections` Shareable collections of modules, playbooks and roles :ref:`playbooks_reuse_roles` All about ansible roles `Mailing List `_ Questions? Help? Ideas? Stop by the list on Google Groups :ref:`communication_irc` How to join Ansible chat channels