A Red Hat Ansible project represents at least one playbook that is usually stored in a remote version control system, typically using Git. The project might also include additional playbooks, inventories, and inventory variable files. If the project requires Ansible Content Collections or roles, then the project might also include them, or it might include requirements.yml files that specify them and from where automation controller can download them.

Automation controller can automatically download and get updates for project materials and the resources specified by requirements.yml files when a job template that uses the project is launched.

You can use the following procedure to create a project to share a collection of Ansible Playbooks and roles managed in an existing Git repository.

Users are granted permissions to project resources through assigned roles on the project resource. Roles can be assigned directly to a user or indirectly through a team. For example, for a user to gain permissions on a specific project, they must be assigned or inherit a role for that project.

The following project roles are available:

Initially, only users with the System Administrator or System Auditor user type can access projects. You must specifically configure access for users with the Normal User user type. You cannot assign roles when you create the project; create the project first and then add any roles.

You can assign roles in the Access section of the project editor. Use the following procedure to set roles for a project:

Source control management credentials, also called SCM credentials, store authentication information that automation controller can use to access project materials stored in a version control system such as Git. SCM credentials store the username and the password or private key (and private key passphrase, if any) needed to authenticate access to the source control repository.

Use the following procedure to create an SCM credential so that automation controller can retrieve playbooks, roles, or other materials from a Git repository for a project.

Like machine credentials, private SCM credentials are only usable by their creators and System Administrator and System Auditor users. However, you can share SCM credentials with other users by assigning the credentials to an organization and assigning appropriate roles on those credentials to teams or users in that organization.

The following is the list of roles for SCM credentials:

Initially, only users with the Admin or Auditor organization role can access SCM credentials within their organization. You need to specifically configure any additional user access.

The assignment of SCM credential roles to users or teams dictates who has permissions to an SCM credential belonging to an organization. You cannot assign these permissions when you create the SCM credential. You can adjust them after their creation by editing the credential.

You can assign roles through the Access section of the credential editor page. Use the following procedure to grant permissions to an existing SCM credential that is assigned to an organization.

An SCM project resource in automation controller represents a copy of playbooks, collections, and roles obtained from an SCM source. Because modifications to the contents of these playbooks, collections, and roles are managed in an external SCM system, their respective counterparts in an automation controller project must be routinely updated from the SCM source to reflect changes.

The following sections describe different ways to update SCM project resources in automation controller.

Manual Updates

If you do not want to use these automatic settings, you can manually update a project to the latest version in the source control repository.

Use the following procedure to manually update a project from its SCM source:

1. Log in as a user with the Update role in the project.

2. Navigate to Resources → Projects and then click the Sync Project icon for the project that you want to update.

If the update succeeds, then the status column displays the Successful message and the revision column displays the latest commit hash.

Figure 4.2: Updating an SCM project

Important

The Update role only dictates whether a user can manually trigger an update of a project from its SCM source. It does not impact the update behavior configured by the project’s SCM update option.

For example, a project configured with the Update on Launch SCM update option still performs updates even when the project is used by a user who has not been granted the Update role on the project.

A project can include a copy of the Ansible Content Collections or roles that it needs. It can be a better practice, however, to store those Ansible Content Collections or roles in a separate repository, especially if they are managed by other people, and have automation controller automatically retrieve that content as needed. These sources could be automation hub, the community Ansible Galaxy site, or your own Git repository server, for example.

You manage this by creating a requirements.yml file, just like the one used by the ansible-galaxy command. At the end of a project update, if a project repository includes a valid roles/requirements.yml file, then automation controller automatically installs the defined roles. The output of the project update job contains a task similar to the following:

...output omitted...
TASK [fetch galaxy roles from requirements.(yml/yaml)] *************************
changed: [localhost] => (item=/var/lib/awx/projects/_13__example_project/roles/requirements.yml)
...output omitted...

Similarly, if a project repository includes a valid collections/requirements.yml file, then automation controller automatically installs the defined collections. The output of the project update job contains a task similar to the following:

...output omitted...
TASK [fetch galaxy collections from collections/requirements.(yml/yaml)] *******
changed: [localhost] => (item=/var/lib/awx/projects/_13__example_project/collections/requirements.yml)
...output omitted...