A Project is a logical collection of Ansible playbooks, represented in Tower.
You can manage playbooks and playbook directories by either placing them manually under the Project Base Path on your Tower server, or by placing your playbooks into a source code management (SCM) system supported by Tower, including Git, Subversion, Mercurial, and Red Hat Insights. To create a Red Hat Insights project, refer to Setting up an Insights Project.
By default, the Project Base Path is
/var/lib/awx/projects, but this may have been modified by the Tower administrator. It is configured in
/etc/tower/conf.d/custom.py. Use caution when editing this file, as incorrect settings can disable your installation.
This menu displays the list of the projects that are currently available. The default view is collapsed (Compact) with project name and its status, but you can expand to see more information. You can sort this list by various criteria, and perform a search to filter the projects of interest.
For each project listed, you can get the latest SCM revision (), copy the project attributes (), or delete () the project, using the respective icons next to each project. Starting with Ansible Tower 3.7, projects are allowed to be updated while a related job is running.
Status indicates the state of the project and may be one of the following (note that you can also filter your view by specific status types):
/var/lib/awx/projects(applicable for manual or source control managed projects).
Projects of credential type Manual cannot update or schedule source control-based actions without being reconfigured as an SCM type credential.
If deleting items that are used by other work items, a message opens listing the items are affected by the deletion and prompts you to confirm the deletion. Some screens will contain items that are invalid or previously deleted, so they will fail to run. Below is an example of such a message:
To create a new project:
If adding a manual project, each project path inside of the project root folder can only be assigned to one project. If you receive the following message, ensure that you have not already assigned the project path to an existing project:
All of the project paths have been assigned to existing projects, or there are no directories found in the base path.
You will need to add a project path before creating a new project.
If you have trouble adding a project path, check the permissions and SELinux context settings for the project directory and files.
If you have not added any Ansible playbook directories to the base project path, you will receive the following message from Tower:
Correct this issue by creating the appropriate playbook directories and checking out playbooks from your SCM or otherwise copying playbooks into the appropriate playbook directories.
By default, Ansible Tower has a system-wide setting that allows roles to be dynamically downloaded from a
requirements.yml file for SCM projects. You may turn off this setting in the Jobs tab of the Settings () menu by switching the Enable Role Download toggle button to OFF.
- SCM URL - See an example in the help text.
- SCM Branch/Tag/Commit - Optionally enter the SCM branch, tags, commit hashes, arbitrary refs, or revision number (if applicable) from the source control (Git, Subversion, or Mercurial) to checkout. Some commit hashes and refs may not be available unless you also provide a custom refspec in the next field.
- SCM Refspec - This field is an option specific to git source control and only advanced users familiar and comfortable with git should specify which references to download from the remote repository. For more detail, see job branch overriding.
- SCM Credential - If authentication is required, select the appropriate SCM credential
- SCM Update Options:
- Clean - Removes any local modifications prior to performing an update.
- Delete on Update - Deletes the local repository in its entirety prior to performing an update. Depending on the size of the repository this may significantly increase the amount of time required to complete an update.
- Update Revision on Launch - Updates the revision of the project to the current revision in the remote source control. To avoid job overflows if jobs are spawned faster than the project can sync, selecting this allows you to configure a Cache Timeout to cache prior project syncs for a certain number of seconds.
- Allow Branch Override - Allows a job template that uses this project to launch with a specified SCM branch or revision other than that of the project’s. For more detail, see job branch overriding.
Using a GitHub link offers an easy way to use a playbook. To help get you started, use the
helloworld.ymlfile available at: https://github.com/ansible/tower-example.git
This link offers a very similar playbook to the one created manually in the instructions found in the Ansible Tower Quick Start Guide. Using it will not alter or harm your system in anyway.
Please note that immediately after adding a project setup to use source control, a “Sync” starts that fetches the project details from the configured source control.
The set of Permissions assigned to this project (role-based access controls) that provide the ability to read, modify, and administer projects, inventories, job templates, and other Tower elements are Privileges.
You can access the project permissions via the Permissions tab next to the Details tab. This screen displays a list of users that currently have permissions to this project. The list may be sorted and searched by User, Role, or Team Role.
The Permissions tab allows you to review, grant, edit, and remove associated permissions for users as well as team members. To assign permissions to a particular user for this resource:
- Click to select one or multiple check boxes beside the name(s) of the user(s) or team(s) to select them.
You can select multiple users and teams at the same time by navigating between the Users and Teams tabs without saving.
After selections are made, the window expands to allow you to select a role from the drop-down menu list for each user or team you chose.
The example above shows options associated with inventories. Different resources have different options available:
- Admin allows read, run, and edit privileges (applies to all resources)
- Use allows use of a resource in a job template (applies all resources except job templates)
- Update allows updating of project via the SCM Update (applies to projects and inventories)
- Ad Hoc allows use of Ad Hoc commands (applies to inventories)
- Execute allows launching of a job template (applies to job templates)
- Read allows view-only access (applies to all resources)
Use the Key button in the roles selection pane to display a description of each of the roles. For more information, refer to the Roles section of this guide.
- Select the role to apply to the selected user or team.
NoteYou can assign roles to multiple users and teams by navigating between the Users and Teams tabs without saving.
Click Save when done, and the Add Users/Teams window closes to display the updated roles assigned for each user and team.
To remove Permissions for a particular user, click the Disassociate (x) button next to its resource.
This launches a confirmation dialog, asking you to confirm the disassociation.
Clicking the Notifications tab allows you to review any notification integrations you have setup.
Use the toggles to enable or disable the notifications to use with your particular project. For more detail, see Enable and Disable Notifications.
If no notifications have been set up, click the NOTIFICATIONS link from inside the gray box to create a new notification.
Refer to Notification Types for additional details on configuring various notification types.
Clicking on Job Templates allows you to add and review any job templates or workflow templates associated with this project. Click Expanded to view details about each template, including the statuses of the jobs that ran using that template, and other useful information. You can sort this list by various criteria, and perform a search to filter the templates of interest.
From this view, you can also launch (), copy (), or delete () the template configuration. Note, the example above shows the expanded view.
Clicking on Schedules allows you to review any schedules set up for this project.
At the end of a Project update, Tower searches for a file called
requirements.yml in the
roles directory, located at
<project-top-level-directory>/roles/requirements.yml. If this file is found, the following command automatically runs:
ansible-galaxy install -r roles/requirements.yml -p ./roles/ --force
This file allows you to reference Galaxy roles or roles within other repositories which can be checked out in conjunction with your own project. The addition of this Ansible Galaxy support eliminates the need to create git submodules for achieving this result.
For more information and examples on the syntax of the
requirements.yml file, refer the role requirements section in the Ansible documentation.
If there are any directories that should specifically be exposed, you can specify those in the Configure Tower screen in the Paths to Expose to Isolated Jobs or by updating the following entry in the settings file:
AWX_PROOT_SHOW_PATHS = ['/list/of/', '/paths']
The primary file you may want to add to
/var/lib/awx/.ssh, if your playbooks need to use keys or settings defined there.
If you made changes in the settings file, be sure to restart services with the
ansible-tower-service restart command after your changes have been saved.
In the Tower User Interface, you can configure these settings in the Jobs settings window. Click the () icon in each of the fields for further detail.
Tower supports project-specific Ansible collections in job runs. If you specify a collections requirements file in the SCM at
collections/requirements.yml, Tower will install collections in that file in the implicit project sync before a job run. To specify a collections requirement:
ansible-galaxy collection install -r requirements.yml -p <job tmp location>
Starting with Ansible Tower 3.6, the project folder will be copied for each job run. This allows playbooks to make local changes to the source tree for convenience, such as creating temporary files, without the possibility of interference with other jobs.
For more information, refer to Using Collections.