Getting Started
Relevant source files
The following files were used as context for generating this wiki page:Ansible is a simple IT automation system that handles configuration management, application deployment, cloud provisioning, and multi-node orchestration. This guide provides developers with the necessary information to set up a development environment, understand the project structure, run tests, and contribute code to the Ansible project. It is intended for developers looking to contribute, not for end-users of Ansible. For user documentation, see the Ansible website.
The development process prioritizes backwards compatibility and follows a specific deprecation cycle. All contributions are made via pull requests to the devel branch and must adhere to the project's coding guidelines and licensing requirements.
Sources: README.md:13-16, AGENTS.md:6-8, 185-186, 192-193
Development Environment Setup
Setting up a local development environment is the first step to contributing to Ansible. The process involves creating a fork, cloning the repository, and installing the project in an editable mode. Ansible development requires a POSIX-compliant operating system; Windows users should use the Windows Subsystem for Linux (WSL).
The following diagram illustrates the initial setup process.
This workflow ensures that any changes you make to the code are immediately available for testing.
Sources: AGENTS.md:40-45
Python Virtual Environment
While not strictly required for all tasks, using a Python virtual environment is highly recommended for isolating dependencies. The packaging/release.py script, for example, automates the creation of virtual environments for building and publishing releases, demonstrating a best practice for dependency management.
The script uses Python's built-in venv module to create isolated environments.
Sources: packaging/release.py:46, 521-522, 540
Project Structure
The Ansible repository is organized into several key directories. Understanding this structure is crucial for locating code and placing new contributions correctly.
This diagram shows a high-level overview of the main directories within the repository.
The table below describes the purpose of each key directory.
| Directory | Description |
|---|---|
lib/ansible/ | The main library code for Ansible. |
lib/ansible/cli/ | Implementations for command-line interfaces like ansible and ansible-playbook. |
lib/ansible/modules/ | Core modules that are the primary units of work in Ansible. These are executed on remote nodes. |
lib/ansible/module_utils/ | Shared utility code that modules can import. Modules can only import from this directory. |
lib/ansible/plugins/ | The plugin framework, providing extensibility for filters, tests, lookups, and more. |
lib/ansible/collections/ | The framework for Ansible Collections, the modern packaging format for Ansible content. |
test/units/ | Unit tests, which mirror the structure of the lib/ directory. |
test/integration/ | Integration tests, organized by target functionality. |
changelogs/fragments/ | Directory for storing individual changelog entries for each pull request. |
Sources: AGENTS.md:204-227, test/integration/targets/ansible-galaxy-collection-cli/files/expected.txt
Testing
Ansible uses a unified testing tool called ansible-test to run various types of tests. Testing is a critical part of the development process, and pull requests are expected to include appropriate tests.
Test Types and Commands
There are three main types of tests, each with a specific purpose.
| Test Type | Command | Description |
|---|---|---|
| Sanity | ansible-test sanity -v --docker default | Static analysis and linting checks (e.g., pylint, pep8). |
| Unit | ansible-test units -v --docker default | Tests for individual components, typically using pytest. |
| Integration | ansible-test integration -v --docker ubuntu2204 | End-to-end tests for modules and plugins, run against specific targets. |
Tests are preferably run in isolated environments using Docker (--docker) or as a fallback, a virtual environment (--venv). For integration tests, it is important to use a distribution-specific container (e.g., ubuntu2204) rather than the default or base containers.
Sources: AGENTS.md:27-28, 51-76
Diagnosing CI Failures
When a pull request fails CI checks, you can diagnose the issue using the following workflow.
This sequence shows how a developer can use gh CLI commands and local testing to identify and fix CI failures.
Sources: AGENTS.md:81-110
Contribution Workflow
All contributions to Ansible are managed through GitHub pull requests. The process involves creating a feature branch, making changes, and submitting a PR against the devel branch.
Pull Request Requirements
Every pull request must include:
- Changelog Fragment: A YAML file in
changelogs/fragments/that describes the change. The fragment's structure is defined inchangelogs/config.yaml. - Tests: Appropriate unit or integration tests that cover the new or modified code.
Sources: AGENTS.md:121-128, 170-179
PR Submission and Review Flow
The following diagram outlines the typical lifecycle of a pull request.
This flowchart shows the steps from starting work on a feature to getting it merged into the devel branch.
*Sources: README.md:60-62, AGENTS.md:113-120, 185 *
Documentation and Code Style
Ansible has strict standards for documentation and code style to ensure consistency and maintainability.
Module Documentation
All modules and most plugins require documentation to be embedded directly within the Python file as static string variables. These blocks are parsed using AST, so they cannot be dynamically generated.
The required documentation blocks are:
DOCUMENTATION: A YAML string containing the module's description, options, and metadata.EXAMPLES: A YAML or raw string providing usage examples.RETURN: A YAML string describing the values returned by the module.
An alternative for some plugins is "sidecar" documentation, where a .yml file with the same name as the plugin file contains the documentation.
*Sources: lib/ansible/modules/uri.py:11-396, lib/ansible/modules/expect.py:10-101, AGENTS.md:158-164, test/lib/ansible_test/_util/controller/sanity/validate-modules/validate_modules/main.py:1022-1024 *
Below is an example of the DOCUMENTATION block from the ansible.builtin.replace module.
# lib/ansible/modules/replace.py:11-105
DOCUMENTATION = r"""
---
module: replace
author: Evan Kaufman (@EvanK)
extends_documentation_fragment:
- action_common_attributes
- action_common_attributes.files
- files
- validate
attributes:
check_mode:
support: full
# ... (content truncated for brevity)
options:
path:
description:
- The file to modify.
type: path
required: true
aliases: [ dest, destfile, name ]
regexp:
description:
- The regular expression to look for in the contents of the file.
# ... (content truncated for brevity)
"""
Code Style
Key code style guidelines include:
- Line Limit: 160 characters.
- Imports: Must appear after the
DOCUMENTATION,EXAMPLES, andRETURNblocks in modules.from __future__ import annotationsshould be used. - No Trailing Whitespace: Code files should be free of trailing whitespace.
- Licensing: All new code in
ansible-coremust be GPLv3 compatible. Code inlib/ansible/module_utils/defaults to BSD-2-Clause.
*Sources: AGENTS.md:16-24, 144-154 *