Playbooks & Execution•6 min read•Ansible Core

Ansible Galaxy, Roles & Collections

Install, inspect, and manage modular Ansible collections and roles from Ansible Galaxy, Git repositories, or custom project scaffolds in CIEL.

Writing monolithic 500-line playbooks leads to duplicated code and maintenance headaches. The standard Ansible practice is to break automation into modular, reusable Collections (such as community.docker, amazon.aws, or ansible.posix) and Roles (such as standardized database setup, user provisioning, or web server configurations).

CIEL provides an integrated package manager under Packages (/packages) that connects directly to Ansible Galaxy, Git repositories, and local role trees.

Install Ansible Package Dialog for Collections and Roles with Upstream Galaxy and Git Sources

1. Packages & Roles Hub (/packages)

The Packages workspace in the navigation sidebar organizes all automation modules available to your project playbooks:

  • Installed Collections: Lists all downloaded Ansible collections stored in ansible_collections/. Displays semantic versions, author metadata, tags, and dependencies extracted from MANIFEST.json and galaxy.yml.
  • Installed Roles: Displays project roles stored in roles/, distinguishing between downloaded Galaxy roles and locally scaffolded custom roles.
  • Top Actions:
    • Install Package: Opens the interactive installation modal to pull collections or roles from Galaxy or Git.
    • New Custom Role: Scaffolds a complete standard Ansible role structure in your project roles directory.
    • Tools Menu: Quick access to the interactive Role Structure Guide and the Import requirements.yml batch installer.

2. Installing Packages via the Galaxy Wizard

Clicking Install Package opens the unified installation modal shown above. It wraps ansible-galaxy CLI operations into an accessible interface:

A. Artifact Type Selector

Toggle between two artifact types:

  • Collection: Executes ansible-galaxy collection install targeting the project collections path (ansible_collections/).
  • Role: Executes ansible-galaxy role install targeting the project roles path (roles/).

B. Package Name or Git URL

Specify where Ansible should fetch the package:

  • Ansible Galaxy: Enter the standard namespace identifier (e.g. community.general, amazon.aws, or geerlingguy.docker).
  • Git Repositories: Enter a Git repository URL prefixed with git+ (e.g. git+https://github.com/organization/ansible-collection-custom.git). Useful for private enterprise collections hosted on GitHub, GitLab, or internal Git servers.
  • Direct Archives: Direct HTTP/HTTPS URLs to .tar.gz or .tgz distribution tarballs.

C. Version / Branch / Tag Selection

  • Galaxy Packages: Enter a specific semantic version (e.g. 1.3.0 or ^2.1.0) to lock dependencies. Leaving this blank downloads the latest stable release.
  • Git Sources: Enter a Git reference such as a branch (main, develop) or tag (v1.0.0).

D. Force Reinstall (--force flag)

Check this option to pass the --force flag to the underlying runner. This forces Ansible Galaxy to overwrite existing local directories, which is critical when updating Git branches or recovering from modified role files.


3. Batch Installation with requirements.yml

For teams maintaining infrastructure-as-code declarations across environments:

  1. Open Tools > Import requirements.yml in the Packages header.
  2. Paste your standard Ansible Galaxy requirements.yml definition:
requirements.yml(yaml)
roles:
  - name: geerlingguy.nginx
    version: 3.2.0
  - name: geerlingguy.postgresql
    version: 3.4.2

collections:
  - name: community.general
    version: 9.2.0
  - name: ansible.posix
    version: 1.5.4
  - name: git+https://github.com/internal-corp/ansible-network-core.git
    type: git
    version: v2.1.0
  1. Click Run Install. CIEL executes ansible-galaxy install -r requirements.yml in the project root, pulling all declared dependencies in a single background task and streaming output logs directly to the modal.

4. Scaffolding Custom Project Roles

When building internal automation, avoid creating directories and metadata files by hand:

  1. Click New Custom Role in the header.
  2. Enter a role name (e.g. ciel_common or db_replica).
  3. Fill in optional author, company, license, and minimum Ansible version parameters.
  4. Click Create Role.

CIEL scaffolds the canonical Ansible role architecture instantly:

  • tasks/main.yml: Main list of task directives.
  • handlers/main.yml: Service restart handlers and event listeners.
  • defaults/main.yml: Low-precedence default variables (Level 2).
  • vars/main.yml: High-precedence role variables (Level 15).
  • templates/: Destination folder for Jinja2 template files (.j2).
  • meta/main.yml: Role dependencies and compatibility metadata.
  • README.md: Role documentation template.

You can inspect and edit every scaffolded YAML file directly in the browser via Studio or the Role Detail drawer.


5. External References

For upstream Ansible documentation on working with Galaxy packages and roles: