14. Projects¶

14.1.1. Manage playbooks manually¶

• Create one or more directories to store playbooks under the Project Base Path (for example, /var/lib/awx/projects/)

• Create or copy playbook files into the playbook directory.

• Ensure that the playbook directory and files are owned by the same UNIX user and group that the Tower service runs as.

• Ensure that the permissions are appropriate for the playbook directories and files.

If you have trouble adding a project path, check the permissions and SELinux context settings for the project directory and files.

14.1.2. Manage playbooks using Source Control¶

Note

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.

1. Select the appropriate option from the SCM Type drop-down menu list.

2. Enter the appropriate details into the following fields:

• 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.

3. Click Save to save your project.

Tip

Using a GitHub link offers an easy way to use a playbook. To help get you started, use the helloworld.yml file 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.

14.2.1. Add Permissions¶

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:

1. Click the Permissions tab.

2. Click the button to open the Add Users/Teams window.

3. Specify the users or teams that will have access then assign them specific roles:

1. Click to select one or multiple check boxes beside the name(s) of the user(s) or team(s) to select them.

Note

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)

Tip

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.

2. Select the role to apply to the selected user or team.

Note

You can assign roles to multiple users and teams by navigating between the Users and Teams tabs without saving.

4. Review your role assignments for each user and team.

5. 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.

14.5.1. Schedule a Project¶

To schedule a project run, click the Schedules tab.

• If schedules are already set up; review, edit, or enable/disable your schedule preferences.

• If schedules have not been set up, refer to Schedules for more information.