8. Projects
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, and Mercurial.
Note
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/settings.py. Use caution when editing this file, as incorrect settings can disable your installation.
This menu displays a list of the projects that are currently available. The list of projects may be sorted and searched by Name, Type, or Status. For each project listed, you can edit project properties and delete the project, using the edit and delete icons.
Buttons located in the upper right corner of the Projects tab provide the following actions:
- Create a new project
- View Activity Stream
Status indicates the state of the project and may be one of the following:
- Running: Source control update is currently in progress.
- Never updated: Project is configured for source control, but has never been updated.
- Failed: The last source control update for this project failed.
- Successful: The last source control update for this project succeeded succeeded.
- Missing: Projects are absent from the project base path of
/var/lib/awx/projects (applicable for manual or source control managed projects).
- OK: The project is not configured for source control, and is correctly in place.
Under Actions, the following actions are available:
- Update: Invoke an immediate update from source control, if configured for this project
- Schedule: Schedule an update from source control, if configured for this project
- Edit: Edit the project
- Delete: Delete the project
- Cancel: Cancel a scheduled update from source control (only available when scheduling a source control update)
Note
Projects of credential type Manual cannot update or schedule SCM-based actions without being reconfigured as an SCM type credential.
8.1. Add a new project
To create a new project, click the 
button, which launches the Create Project dialog.
Enter the appropriate details into the following fields:
- Name
- Description
- Organization (A project must have at least one organization. Pick one organization now to create the project, and then after the project is created you can add additional organizations.)
- SCM Type (Select one of Manual, Git, Subversion, or Mercurial. Refer to Manage playbooks manually and Manage playbooks using Source Control for more detail.)
All fields are required.
Note
Each project path 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.”
8.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.
Warning
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.
8.1.2. Manage playbooks using Source Control
Select the appropriate SCM Type. Then, enter the appropriate details into the following fields:
SCM URL
SCM Branch (Optionally enter the SCM branch for Git or Mercurial.)
Revision # (Optionally enter the Revision # for Subversion.)
SCM Credential (If authentication is required, select the appropriate SCM credential.)
SCM Update Options
- Clean (Remove any local modifications prior to performing an update.)
- Delete on Update (Delete 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 on Launch (Each time a job runs using this project, perform an update to the local repository prior to starting the job. 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.)
Click Save to save your project.
8.2. Updating projects from source control
Update an existing SCM-based project by clicking the 
button.
Note
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.
Click on the dot under Status (far left, beside the name of the Project) to get further details about the update process.
To set a schedule for updating the project from SCM, click the 
button.
This will navigate to the Schedules screen.
This screen displays a list of the schedules that are currently available for the selected Project. The schedule list may be sorted and searched by Name.
The list of schedules includes:
- Name: Clicking the schedule name opens the Edit Schedule dialog
- First Run: The first scheduled run of this task
- Next Run: The next scheduled run of this task
- Final Run: If the task has an end date, this is the last scheduled run of the task.
Buttons located in the upper right corner of the Schedules screen provide the following actions:
- Create a new schedule
- Refresh this view
- View Activity Stream
8.3. Ansible Galaxy Support
At the end of a Project update, Tower searches for a file called roles/requirements.yml in the checkout. If this file is found, the following command automatically runs:
ansible-galaxy install -r 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 to Advanced Control Over Role Requirements in the Ansible documentation.
8.4. Add a new schedule
To create a new schedule click the button, which opens the Add Schedule dialog.
Enter the appropriate details into the following fields and select Save:
- Name (required)
- Start Date (required)
- Start Time (required)
- Local Time Zone (the entered Start Time should be in this timezone)
- UTC Start Time (calculated from Start Time + Local Time Zone)
- Repeat Frequency (appropriate scheduling options are displayed depending on the frequency you select)
The Details tab displays a description of the schedule and a list of the scheduled occurrences in the selected Local Time Zone.
Note
Jobs are scheduled in UTC. Repeating jobs that runs at a specific time of day may move relative to a local timezone when Daylight Savings Time shifts occur.
There are several actions available for schedules, under the Actions column:
- Stop an active schedule or activate a stopped schedule
- Edit Schedule
- Delete schedule
