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.
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 fromMANIFEST.jsonandgalaxy.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 installtargeting the project collections path (ansible_collections/). - Role: Executes
ansible-galaxy role installtargeting 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, orgeerlingguy.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.gzor.tgzdistribution tarballs.
C. Version / Branch / Tag Selection
- Galaxy Packages: Enter a specific semantic version (e.g.
1.3.0or^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:
- Open Tools > Import requirements.yml in the Packages header.
- Paste your standard Ansible Galaxy
requirements.ymldefinition:
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- Click Run Install. CIEL executes
ansible-galaxy install -r requirements.ymlin 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:
- Click New Custom Role in the header.
- Enter a role name (e.g.
ciel_commonordb_replica). - Fill in optional author, company, license, and minimum Ansible version parameters.
- 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:
- Ansible Galaxy User Guide: Installing collections and roles from Galaxy or Git repositories.
- Ansible Collections Overview: Understanding collection packaging, namespaces, and content organization.
- Ansible Roles Guide: Role directory structure, handlers, and reuse patterns.