bd18be6c0c
* Ensure there is a single source of collection metadata * Allow collection subdirs to be detected by a galaxy.yml or MANIFEST.json * Add documentation about installing and downloading collection directories * Add an example for downloading a git repository * Update documented valid metadata sources for installing git repositories Co-authored-by: Sviatoslav Sydorenko <wk.cvs.github@sydorenko.org.ua> Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com>
84 lines
4.2 KiB
Text
84 lines
4.2 KiB
Text
You can install a collection in a git repository by providing the URI to the repository instead of a collection name or path to a ``tar.gz`` file. The collection must contain a ``galaxy.yml`` or ``MANIFEST.json`` file, which will be used to generate the would-be collection artifact data from the directory. The URI should be prefixed with ``git+`` (or with ``git@`` to use a private repository with ssh authentication) and optionally supports a comma-separated `git commit-ish <https://git-scm.com/docs/gitglossary#def_commit-ish>`_ version (for example, a commit or tag).
|
|
|
|
.. warning::
|
|
|
|
Embedding credentials into a git URI is not secure. Make sure to use safe auth options for security reasons. For example, use `SSH <https://help.github.com/en/github/authenticating-to-github/connecting-to-github-with-ssh>`_, `netrc <https://linux.die.net/man/5/netrc>`_ or `http.extraHeader <https://git-scm.com/docs/git-config#Documentation/git-config.txt-httpextraHeader>`_/`url.<base>.pushInsteadOf <https://git-scm.com/docs/git-config#Documentation/git-config.txt-urlltbasegtpushInsteadOf>`_ in Git config to prevent your creds from being exposed in logs.
|
|
|
|
.. code-block:: bash
|
|
|
|
# Install a collection in a repository using the latest commit on the branch 'devel'
|
|
ansible-galaxy collection install git+https://github.com/organization/repo_name.git,devel
|
|
|
|
# Install a collection from a private github repository
|
|
ansible-galaxy collection install git@github.com:organization/repo_name.git
|
|
|
|
# Install a collection from a local git repository
|
|
ansible-galaxy collection install git+file:///home/user/path/to/repo/.git
|
|
|
|
In a ``requirements.yml`` file, you can also use the ``type`` and ``version`` keys in addition to using the ``git+repo,version`` syntax for the collection name.
|
|
|
|
.. code-block:: yaml
|
|
|
|
collections:
|
|
- name: https://github.com/organization/repo_name.git
|
|
type: git
|
|
version: devel
|
|
|
|
Git repositories can be used for collection dependencies as well. This can be helpful for local development and testing but built/published artifacts should only have dependencies on other artifacts.
|
|
|
|
.. code-block:: yaml
|
|
|
|
dependencies: {'git@github.com:organization/repo_name.git': 'devel'}
|
|
|
|
Default repository search locations
|
|
-----------------------------------
|
|
|
|
There are two paths searched in a repository for collections by default.
|
|
|
|
The first is the ``galaxy.yml`` or ``MANIFEST.json`` file in the top level of the repository path. If the file exists it's used as the collection metadata and the individual collection will be installed.
|
|
|
|
.. code-block:: text
|
|
|
|
├── galaxy.yml
|
|
├── plugins/
|
|
│ ├── lookup/
|
|
│ ├── modules/
|
|
│ └── module_utils/
|
|
└─── README.md
|
|
|
|
The second is a ``galaxy.yml`` or ``MANIFEST.json`` file in each directory in the repository path (one level deep). In this scenario, each directory with a metadata file is installed as a collection.
|
|
|
|
.. code-block:: text
|
|
|
|
directory/
|
|
├── docs/
|
|
├── MANIFEST.json
|
|
├── plugins/
|
|
│ ├── inventory/
|
|
│ └── modules/
|
|
└── roles/
|
|
|
|
Specifying the location to search for collections
|
|
-------------------------------------------------
|
|
|
|
If you have a different repository structure or only want to install a subset of collections, you can add a fragment to the end of your URI (before the optional comma-separated version) to indicate which path ansible-galaxy should inspect for metadata file(s). The path should be a directory to a collection or multiple collections (rather than the path to a ``galaxy.yml`` file or ``MANIFEST.json`` file).
|
|
|
|
.. code-block:: text
|
|
|
|
namespace/
|
|
└── name/
|
|
├── docs/
|
|
├── galaxy.yml
|
|
├── plugins/
|
|
│ ├── README.md
|
|
│ └── modules/
|
|
├── README.md
|
|
└── roles/
|
|
|
|
.. code-block:: bash
|
|
|
|
# Install all collections in a particular namespace
|
|
ansible-galaxy collection install git+https://github.com/organization/repo_name.git#/namespace/
|
|
|
|
# Install an individual collection using a specific commit
|
|
ansible-galaxy collection install git+https://github.com/organization/repo_name.git#/namespace/name/,7b60ddc245bc416b72d8ea6ed7b799885110f5e5
|