Creating Projects

Projects in AWX represent a logical collection of Ansible playbooks, sourced from version control systems (Git, Subversion) or manually placed on the AWX server.

Understanding Projects

A Project in AWX:

Contains Ansible playbooks, roles, and related files
Syncs content from SCM (Source Control Management) systems
Can be assigned to an organization
Requires appropriate credentials for private repositories
Supports multiple SCM types: Git, Subversion, Red Hat Insights, and Remote Archive

Project Types

SCM-Based

Projects synced from version control (Git, SVN) - recommended approach

Manual

Playbooks manually placed in the project directory on the AWX server

Insights

Projects that sync from Red Hat Insights

Remote Archive

Projects from remote archive files (tar, zip)

Creating a Git Project

Prepare Your Repository

Ensure your Git repository contains:

Ansible playbooks (.yml or .yaml files)
Optional: roles/ directory
Optional: group_vars/ and host_vars/
Optional: collections/requirements.yml
Optional: roles/requirements.yml

Example repository structure:

my-ansible-project/
├── playbooks/
│   ├── site.yml
│   ├── deploy.yml
│   └── configure.yml
├── roles/
│   └── webserver/
├── inventory/
│   └── hosts.yml
└── collections/
    └── requirements.yml

Create via Web UI

Navigate to Projects in the left sidebar
Click Add
Fill in the project details:
- Name: Descriptive project name
- Organization: Select the organization
- Default Execution Environment: Optional EE
- Source Control Type: Select “Git”
- Source Control URL: Your repository URL
- Source Control Branch/Tag/Commit: Branch name (default: master/main)
- Source Control Credential: Select if private repo
Configure SCM options:
- Clean: Discard local changes before sync
- Delete: Remove project before sync
- Track submodules: Track Git submodules
- Update on Launch: Update before running jobs
Click Save

Create via API

curl -X POST https://awx.example.com/api/v2/projects/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Infrastructure Playbooks",
    "description": "Core infrastructure automation playbooks",
    "organization": 1,
    "scm_type": "git",
    "scm_url": "https://github.com/example/ansible-playbooks.git",
    "scm_branch": "main",
    "scm_clean": true,
    "scm_update_on_launch": true,
    "scm_update_cache_timeout": 300
  }'

Create via Ansible

- name: Create AWX project
  awx.awx.project:
    name: Infrastructure Playbooks
    description: Core infrastructure automation playbooks
    organization: Engineering
    scm_type: git
    scm_url: https://github.com/example/ansible-playbooks.git
    scm_branch: main
    scm_clean: true
    scm_update_on_launch: true
    scm_update_cache_timeout: 300
    state: present
    controller_host: awx.example.com
    controller_oauthtoken: "{{ awx_token }}"

Project Configuration Options

SCM Update Behavior

Update on Launch
Cache Timeout
Allow Override

scm_update_on_launch: When enabled, the project syncs from SCM before each job run.

scm_update_on_launch: true
scm_update_cache_timeout: 300  # seconds

Use when:

Playbooks change frequently
You want the latest code for every job
CI/CD pipelines push regular updates

scm_update_cache_timeout: Seconds before considering cached update stale.

scm_update_cache_timeout: 86400  # 24 hours

Set to 0 to always update
Higher values reduce SCM load
Lower values ensure fresher content

allow_override: Permits job templates to override the SCM branch.

allow_override: true

Enables testing different branches without creating new projects.

SCM Authentication

Create SCM Credential

For private repositories, create an SCM credential:

- name: Create Git credential
  awx.awx.credential:
    name: GitHub Personal Access Token
    organization: Engineering
    credential_type: Source Control
    inputs:
      username: git
      password: "{{ github_token }}"
    state: present

Assign to Project

- name: Create project with credential
  awx.awx.project:
    name: Private Repo Project
    organization: Engineering
    scm_type: git
    scm_url: https://github.com/example/private-repo.git
    credential: GitHub Personal Access Token
    state: present

Supported Credential Types

Username/Password: Basic authentication
SSH Key: For SSH URLs ([email protected]:...)
Personal Access Token: GitHub, GitLab tokens

Working with Git Branches

Specifying Branches

# Use specific branch
scm_branch: develop

# Use tag
scm_branch: v1.2.3

# Use commit SHA
scm_branch: abc123def456

Branch Override in Job Templates

When allow_override is enabled:

- name: Create job template with branch override
  awx.awx.job_template:
    name: Deploy from Feature Branch
    project: Infrastructure Playbooks
    playbook: deploy.yml
    ask_scm_branch_on_launch: true
    state: present

Launch with specific branch:

curl -X POST https://awx.example.com/api/v2/job_templates/1/launch/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"scm_branch": "feature/new-deployment"}'

Advanced SCM Options

Git Refspec

Fetch additional references beyond the default branch:

scm_refspec: '+refs/pull/*:refs/remotes/origin/pull/*'
scm_branch: 'pull/42/head'

Useful for:

Testing pull requests
Accessing non-standard refs
Fetching multiple branches

Git Submodules

Track Git submodules in your project:

scm_track_submodules: true

Clean and Delete Options

Clean
Delete on Update

scm_clean: true

Discards local modifications (equivalent to git clean -fdx)

scm_delete_on_update: true

Deletes the project directory before syncing (fresh clone each time)

Manual Projects

For manual projects without SCM:

Create Manual Project

- name: Create manual project
  awx.awx.project:
    name: Manual Playbooks
    organization: Engineering
    scm_type: ""
    local_path: manual_project
    state: present

Place Playbooks on Server

Copy playbooks to the AWX server:

# On AWX server
sudo mkdir -p /var/lib/awx/projects/manual_project
sudo cp -r /path/to/playbooks/* /var/lib/awx/projects/manual_project/
sudo chown -R awx:awx /var/lib/awx/projects/manual_project

Manual projects are not recommended for production. Use SCM-based projects for better version control and auditability.

Project Signing and Verification

AWX supports content verification using GPG signatures:

- name: Create signing credential
  awx.awx.credential:
    name: GPG Signing Key
    credential_type: GPG Public Key
    inputs:
      gpg_public_key: "{{ lookup('file', 'pubkey.asc') }}"
    state: present

- name: Create verified project
  awx.awx.project:
    name: Signed Playbooks
    organization: Engineering
    scm_type: git
    scm_url: https://github.com/example/signed-repo.git
    signature_validation_credential: GPG Signing Key
    state: present

Updating Projects

Manual Update

Web UI
API
Ansible

Navigate to Projects
Click the sync icon next to the project
Monitor the update status

# Trigger project update
curl -X POST https://awx.example.com/api/v2/projects/1/update/ \
  -H "Authorization: Bearer YOUR_TOKEN"

# Check update status
curl https://awx.example.com/api/v2/project_updates/123/ \
  -H "Authorization: Bearer YOUR_TOKEN"

- name: Update project
  awx.awx.project_update:
    project: Infrastructure Playbooks
    wait: true

Scheduled Updates

Schedule regular project syncs:

- name: Schedule nightly project update
  awx.awx.schedule:
    name: Nightly Sync
    unified_job_template: Infrastructure Playbooks
    rrule: "DTSTART:20260101T020000Z RRULE:FREQ=DAILY;INTERVAL=1"
    state: present

Viewing Project Playbooks

List available playbooks in a project:

# Via API
curl https://awx.example.com/api/v2/projects/1/playbooks/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

[
  "site.yml",
  "playbooks/deploy.yml",
  "playbooks/configure.yml",
  "playbooks/backup.yml"
]

Collections and Roles

AWX automatically installs collections and roles defined in your project:

Collections

Create collections/requirements.yml:

collections:
  - name: community.general
    version: ">=3.0.0"
  - name: ansible.posix
  - name: amazon.aws
    version: 5.1.0

Roles

Create roles/requirements.yml:

roles:
  - src: geerlingguy.apache
    version: 3.1.4
  - src: geerlingguy.mysql
  - src: https://github.com/example/custom-role.git
    name: custom_role
    version: main

Collections and roles are installed during project updates and are cached for subsequent job runs.

Execution Environments

Assign a default execution environment to the project:

- name: Create project with execution environment
  awx.awx.project:
    name: Infrastructure Playbooks
    organization: Engineering
    scm_type: git
    scm_url: https://github.com/example/playbooks.git
    default_environment: Custom EE
    state: present

This EE will be used by default for all job templates using this project.

Project Permissions

Grant users and teams access to projects:

# Grant team use access
- name: Grant project use permission
  awx.awx.role:
    team: DevOps Team
    project: Infrastructure Playbooks
    role: use
    state: present

# Grant user admin access
- name: Grant project admin permission
  awx.awx.role:
    user: john.doe
    project: Infrastructure Playbooks
    role: admin
    state: present

Project roles:

Admin: Full control over the project
Use: Use project in job templates
Update: Trigger project updates
Read: View project details

Troubleshooting

Project update fails with authentication error

Check your SCM credential:

# Test Git access manually
git ls-remote https://github.com/example/repo.git

# For SSH URLs
ssh -T [email protected]

Verify credential username and password/token
For SSH, ensure the key is correct
Check repository permissions

Playbooks not appearing in project

Ensure:

Files have .yml or .yaml extensions
Files are valid Ansible playbooks (start with --- and contain plays)
Project update completed successfully
Check project update logs for errors

# View project update output
curl https://awx.example.com/api/v2/project_updates/123/stdout/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Collections or roles not installing

Check:

Requirements files are named correctly (requirements.yml)
Requirements files are valid YAML
AWX has internet access (or access to your Galaxy server)
Review project update logs

# Test requirements file locally
ansible-galaxy collection install -r collections/requirements.yml
ansible-galaxy role install -r roles/requirements.yml

Project stuck in 'pending' status

Check:

AWX task manager is running
Instance groups are available
Review /var/log/tower/ logs on AWX server

# Check project update status
curl https://awx.example.com/api/v2/project_updates/?project=1 \
  -H "Authorization: Bearer YOUR_TOKEN"

Best Practices

Use SCM

Always use SCM-based projects instead of manual projects for better version control

Enable Updates

Enable update-on-launch for development, disable for production (use manual updates)

Branch Strategy

Use stable branches for production projects, enable override for testing

Cache Timeout

Set appropriate cache timeouts to balance freshness and performance

Job Templates

Create job templates using your projects

Credentials

Set up SCM credentials for private repositories

Execution Environments

Configure execution environments for your projects

Project API

Complete API reference for projects

Overview

Installation

Core Concepts

User Guide

Advanced Features

Integrations

Administration

​Understanding Projects

​Project Types

SCM-Based

Manual

Insights

Remote Archive

​Creating a Git Project

​Project Configuration Options

​SCM Update Behavior

​SCM Authentication

​Supported Credential Types

​Working with Git Branches

​Specifying Branches

​Branch Override in Job Templates

​Advanced SCM Options

​Git Refspec

​Git Submodules

​Clean and Delete Options

​Manual Projects

​Project Signing and Verification

​Updating Projects

​Manual Update

​Scheduled Updates

​Viewing Project Playbooks

​Collections and Roles

​Collections

​Roles

​Execution Environments

​Project Permissions

​Troubleshooting

​Best Practices

Use SCM

Enable Updates

Branch Strategy

Cache Timeout

​Related Resources

Job Templates

Credentials

Execution Environments

Project API

Build docs developers (and LLMs) love

Understanding Projects

Project Types

Creating a Git Project

Project Configuration Options

SCM Update Behavior

SCM Authentication

Supported Credential Types

Working with Git Branches

Specifying Branches

Branch Override in Job Templates

Advanced SCM Options

Git Refspec

Git Submodules

Clean and Delete Options

Manual Projects

Project Signing and Verification

Updating Projects

Manual Update

Scheduled Updates

Viewing Project Playbooks

Collections and Roles

Collections

Roles

Execution Environments

Project Permissions

Troubleshooting

Best Practices

Related Resources