Create Ansible Playbooks

Register Git-backed Ansible playbooks in Harness IaCM, attach playbook variables, and install Ansible Galaxy dependencies from a requirements file.

A playbook in Harness IaCM is a pointer to automation you maintain in Git: Harness stores the repository coordinates and fetches the playbook content at pipeline run time. This guide shows you how to register a playbook, attach playbook-level variables, and enable Ansible Galaxy so collection dependencies install automatically before the playbook runs.

What you will learn from this topic

Registration: Point Harness at the repository, branch or commit, and path where your playbook lives.
Scope: How a playbook's account, organization, or project scope is determined, and how to reference it across scopes in a pipeline.
Variables: Attach playbook-scoped Ansible variables (passed as --extra-vars) and environment variables (injected into the process environment), including secrets.
Ansible Galaxy: Enable automatic installation of collections from a requirements.yml file before execution.
Traceability: Review the playbook's activity history.

Before you begin

Playbook in Git: Your playbook must be stored in a Git repository, either Harness Code Repository or a third-party provider. Go to Connect to a code repository to set up a connector with read access.
An inventory to target: Playbooks run against inventories at pipeline time. Go to Create Ansible inventories to create one.
A requirements file (Galaxy only): To install Galaxy dependencies automatically, the repository must contain a requirements file such as requirements.yml listing the collections your playbook needs.

Register a playbook

Follow the interactive guide or the step-by-step instructions to register a playbook and enable Ansible Galaxy.

To register a playbook, do the following:

In the IaCM module, select Playbooks in the left sidebar under Configuration.
Select + New Playbook. The Create Playbook dialog opens.
Enter a Name for the playbook. Description and Tags are optional.
Under Repository, configure the Git source:
- Select Git Provider: Choose Harness Code Repository or Third-party Git provider.
- Git Connector: Select the connector with access to your repository (third-party providers only).
- Repository: Select or enter the repository name.
- Git Fetch Type: Choose Latest from Branch, Git Tag, or Commit SHA, and supply the branch, tag, or SHA.
- File Path: Enter the path to the playbook file within the repository, for example site.yml or playbooks/site.yml.
Select Save.

The playbook detail page opens with four tabs: Playbook Definition, Variables, Activity History, and Configuration. The Playbook Definition tab renders the playbook file fetched from Git, read-only. For example:

- name: Galaxy smoke test
  hosts: all
  gather_facts: true

  tasks:
    - name: Show we are running
      ansible.builtin.debug:
        msg: "hello from playbook on {{ inventory_hostname }}"

    - name: Create a file
      ansible.builtin.copy:
        dest: ./hello.txt
        content: "hello world\n"

    - name: Archive it (community.general)
      community.general.archive:
        path: ./hello.txt
        dest: ./hello.tgz
        format: gz

Harness does not store or modify playbook content. Every pipeline run fetches from the configured Git coordinates, so pull requests, reviews, and tags on the playbook repository remain your source of truth.

Playbook scope

A playbook belongs to the account, organization, or project scope of the Git connector you select under Repository. There is no separate scope selector: creating a playbook from a project-scoped connector creates a project-scoped playbook, and creating one from an account-scoped or organization-scoped connector creates a playbook at that scope. Each repository in the Repository field shows a scope badge (Project, Organization, or Account) so you can confirm where it resolves before you save.

Scoping a playbook at the account or organization level lets every project under that scope reuse it, rather than registering the same playbook per project. To run a playbook from a different scope in a pipeline, open the pipeline's Input tab and select it from the Project, Organization, or Account tab in the playbook picker; Harness resolves the cross-scope reference automatically, so you do not need to type an account. or org. prefix.

Pin production playbooks to a Git Tag or Commit SHA rather than a branch. Branch-based fetching always takes the latest commit, which means an unreviewed merge changes what production runs.

Add playbook variables

The playbook Variables tab has two independent editors: Ansible Variables and Environment Variables. Saving one collection does not affect the other.

Ansible variables

Ansible variables travel with the playbook rather than the inventory, which makes them the right place for values that belong to the automation itself, independent of which hosts it targets. Harness passes them to ansible-playbook as --extra-vars at run time.

To add Ansible variables, do the following:

Open the playbook and select its Variables tab.
Under Ansible Variables, select + Add Variable.
Set the Type (string or secret), enter the Key and Value, then select Save Changes.

Secret-typed Ansible variables reference a Harness secret and are masked in logs. Go to Authenticate private Ansible Galaxy content for how secret-typed variables reach the plugin at run time.

When a playbook and inventory define an Ansible variable with the same key, the playbook value wins. The plugin logs the collision and the precedence decision without exposing the values.

Environment variables

Environment variables are injected into the Ansible process environment before ansible-playbook runs. Use them for process-level settings such as ANSIBLE_HOST_KEY_CHECKING or custom tool paths. They are not passed as --extra-vars and are not available as Ansible variables in playbook tasks.

To add environment variables, do the following:

Open the playbook and select its Variables tab.
Under Environment Variables, select + Add Variable.
Set the Type (string or secret), enter the Key and Value, then select Save Changes.

Secret-typed environment variables are resolved at run time and masked in logs. Pipeline-defined environment values win collisions with playbook environment variables.

Install Ansible Galaxy dependencies

Playbooks that use community or private collections need those collections installed in the execution container before the playbook runs. Instead of baking collections into a custom image, you can have Harness install them at run time from a requirements file in your playbook repository.

To enable Galaxy dependency installation on a playbook, do the following:

Open the playbook and select its Configuration tab.
Under the Ansible Galaxy section, turn on the Enable Ansible Galaxy toggle.
In Requirements File, enter the path to your requirements file in the connected repository, for example requirements.yml. The requirements file path is required when the toggle is on.
Select Apply Changes.

At pipeline run time, the Harness Ansible plugin runs ansible-galaxy collection install -r <requirements file> as a pre-flight step, after cloning the repository and before executing the playbook.

A typical requirements.yml looks like this:

collections:
  - name: community.general
  - name: ansible.posix
    version: ">=1.5.0"
  - name: my_namespace.my_collection

Collections hosted on a private Galaxy server, Red Hat Automation Hub, or a private Git repository need credentials at install time. Go to Authenticate private Ansible Galaxy content to configure ANSIBLE_GALAXY_SERVER_* settings, Git credential triples, or .netrc authentication.

Runtime installation adds time to every pipeline run and depends on the Galaxy server being reachable. For production pipelines with stable dependencies, consider a pre-built image with collections baked in. Go to Manage playbook dependencies to compare both approaches.

View activity history

The playbook's Activity History tab lists executions that used this playbook, with the inventory, pipeline execution, and status of each run. Use it together with the inventory activity history to answer what ran, where, and when.

Troubleshooting

Ansible Galaxy requirements file must be set error when saving a playbook in Harness IaCM

When the Ansible Galaxy option is enabled, the requirements file path is required. Enter the path relative to the repository root, for example requirements.yml, or disable the option.

ansible-galaxy collection install fails during the pre-flight phase in a Harness IaCM pipeline

Verify the requirements file path is correct relative to the repository root and that the execution environment can reach the Galaxy server. For private servers, configure ANSIBLE_GALAXY_SERVER_* authentication settings.

Playbook not found error in Harness IaCM pipeline because repository, branch, or path is incorrect

Verify the Git connector, repository, branch or commit, and folder path on the playbook configuration, and confirm the connector has read access to that branch.

An account-scoped or organization-scoped playbook does not appear in a project pipeline's playbook picker in Harness IaCM

Confirm the playbook was created from a connector scoped to the account or organization, not the project, and that your role has View permission on playbooks at that scope. Open the pipeline's Input tab and check the Account or Organization tab in the playbook picker, not only Project.

Next steps

Your playbook is registered with its dependencies handled, ready to run against an inventory.

Go to Get started with Ansible to run the playbook from a pipeline with the IACMAnsiblePlugin step.
Go to Authenticate private Ansible Galaxy content to authenticate private collection sources.
Go to Output variables for Ansible to export values from playbook runs to later pipeline steps.

PreviousManage Hosts and Groups

NextAuthenticate Private Ansible Galaxy Content

Last updated 2 days ago

Was this helpful?