Source Control Integration

AWX integrates with source control management (SCM) systems to manage project content including playbooks, roles, and inventory files. Projects in AWX point to SCM repositories and can be configured to update automatically.

Supported SCM Types

AWX supports the following source control systems:

Manual - Local project files on the AWX server
Git - Git repositories (most common)
Subversion (SVN) - SVN repositories
Red Hat Insights - Red Hat Insights integration
Remote Archive - Remote tar, zip, or other archive files

Git Integration

Basic Configuration

To configure a Git project:

Project Configuration:
  Name: My Ansible Project
  Organization: Default
  SCM Type: Git
  SCM URL: https://github.com/ansible/ansible-examples.git
  SCM Branch/Tag/Commit: main

Git Credentials

For private repositories, create a Source Control credential:

Credential Type: Source Control
Fields:
  Username: git-user
  Password: <token or password>
  # OR for SSH:
  SSH Private Key: <paste SSH private key>
  SSH Key Unlock: <passphrase if key is encrypted>

Advanced Git Options

Branch/Tag/Commit

Specify a specific version to checkout:

SCM Branch: main              # Branch name
SCM Branch: v2.1.0            # Tag name
SCM Branch: a1b2c3d4          # Specific commit SHA

Refspec

For advanced Git operations, specify a custom refspec:

SCM Refspec: refs/pull/*/head:refs/remotes/origin/pr/*

This allows you to fetch and use pull request branches.

Project Options

Clean - Discard local changes before updating (equivalent to git clean -fdx)
Delete on Update - Delete the project directory before syncing
Track Submodules - Update Git submodules on each project update
Update Revision on Launch - Automatically update project before running jobs
Allow Branch Override - Let job templates override the project branch

SSH Key Authentication

For Git over SSH, configure your credential with an SSH private key:

Credential Configuration:
  Name: GitHub SSH Key
  Credential Type: Source Control
  Username: git
  SSH Private Key: |
    -----BEGIN OPENSSH PRIVATE KEY-----
    b3BlbnNzaC1rZXktdjEAAAAABG5vbmUAAAAEbm9uZQAAAAAAAAABAAABFwAAAAdzc2gtcn
    ...
    -----END OPENSSH PRIVATE KEY-----

HTTPS with Personal Access Token

For GitHub, GitLab, or other platforms using tokens:

SCM URL: https://github.com/myorg/myrepo.git
Credential:
  Username: oauth2  # or your username
  Password: ghp_xxxxxxxxxxxxxxxxxxxxx  # Personal Access Token

Subversion (SVN) Integration

Configuration

Project Configuration:
  Name: SVN Project
  SCM Type: Subversion
  SCM URL: https://svn.example.com/repos/ansible
  SCM Branch: trunk  # or branches/dev, tags/v1.0

SVN Credentials

Credential Type: Source Control
Fields:
  Username: svn-user
  Password: svn-password

Red Hat Insights Integration

Integrate with Red Hat Insights for vulnerability and compliance scanning:

Project Configuration:
  Name: Insights Project
  SCM Type: Red Hat Insights
  Credential: <Insights Credential>

The Insights credential requires:

Credential Type: Red Hat Insights
Fields:
  Username: insights-username
  Password: insights-password

Remote Archive Integration

Pull project content from remote archives:

Project Configuration:
  Name: Archive Project
  SCM Type: Remote Archive
  SCM URL: https://example.com/playbooks.tar.gz

Supported formats:

.tar.gz / .tgz
.tar.bz2
.zip

SCM Inventory Sources

Use project content as inventory sources:

Inventory Source Configuration:
  Name: SCM Inventory
  Source: Sourced from a Project
  Project: <select project>
  Inventory File: inventory/hosts  # relative path in project
  Update on Project Update: Yes

Supported Inventory Formats

INI format - Traditional Ansible inventory
YAML format - Modern YAML-based inventory
Dynamic scripts - Executable inventory scripts
Inventory plugins - Ansible inventory plugin YAML files

Example Project Structure

ansible-project/
├── playbooks/
│   ├── site.yml
│   └── webservers.yml
├── roles/
│   └── common/
├── inventory/
│   ├── production/
│   │   ├── hosts
│   │   ├── group_vars/
│   │   └── host_vars/
│   └── staging/
│       └── hosts
└── collections/
    └── requirements.yml

Project Updates

Manual Updates

Update a project via the UI or API:

curl -X POST https://awx.example.org/api/v2/projects/1/update/ \
  -H "Authorization: Bearer <token>"

Automatic Updates

Configure projects to update automatically:

Update on Launch - Update before job template runs
Update on Project Commit - Use webhooks to trigger updates (GitHub, GitLab)
Scheduled Updates - Set up scheduled project syncs

Webhook Configuration

Enable webhook notifications for automatic project updates:

In AWX, enable webhooks on the project
Copy the webhook URL and key
Configure in your SCM platform:

GitHub:

Webhook URL: https://awx.example.org/api/v2/webhook/github/
Content Type: application/json
Secret: <webhook-key>
Events: Just the push event

GitLab:

URL: https://awx.example.org/api/v2/webhook/gitlab/
Secret Token: <webhook-key>
Trigger: Push events

Troubleshooting

Common Issues

SSH Key Authentication Fails:

Verify the SSH key format (OpenSSH, not PEM)
Check key permissions on the Git server
Ensure the key is added to authorized_keys or deployment keys

Git Clone Fails with SSL Error:

Verify SSL certificate on Git server
Consider using “Verify SSL” option in project settings

Submodules Not Updating:

Enable “Track Submodules” in project options
Verify submodule URLs are accessible with provided credentials

Branch Override Not Working:

Ensure “Allow Branch Override” is enabled on project
Verify the prompt setting is enabled on job template

Debug Project Updates

View project update logs:

# Get project update job
curl https://awx.example.org/api/v2/projects/1/project_updates/ \
  -H "Authorization: Bearer <token>"

# View specific update output
curl https://awx.example.org/api/v2/project_updates/123/stdout/ \
  -H "Authorization: Bearer <token>"

Best Practices

Repository Organization

Keep playbooks, roles, and inventory in a clear structure
Use collections/requirements.yml for Ansible collections
Store credentials in AWX, not in the repository
Use .gitignore to exclude sensitive files

Branch Strategy

Use main or master for production
Create feature branches for development
Use tags for releases
Enable branch override for testing

Performance

Use shallow clones for large repositories (Git default)
Enable caching when possible
Schedule updates during low-usage periods
Use webhooks instead of polling

Security

Use SSH keys or personal access tokens (not passwords)
Rotate credentials regularly
Limit credential access via RBAC
Enable branch protection in SCM platform
Review commit signatures and verification

API Examples

Create Git Project

curl -X POST https://awx.example.org/api/v2/projects/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Git Project",
    "organization": 1,
    "scm_type": "git",
    "scm_url": "https://github.com/ansible/ansible-examples.git",
    "scm_branch": "main",
    "scm_clean": true,
    "scm_update_on_launch": true,
    "credential": 5
  }'

Update Project

curl -X PATCH https://awx.example.org/api/v2/projects/1/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"scm_branch": "develop"}'

​Supported SCM Types

​Git Integration

​Basic Configuration

​Git Credentials

​Advanced Git Options

​Branch/Tag/Commit

​Refspec

​Project Options

​SSH Key Authentication

​HTTPS with Personal Access Token

​Subversion (SVN) Integration

​Configuration

​SVN Credentials

​Red Hat Insights Integration

​Remote Archive Integration

​SCM Inventory Sources

​Supported Inventory Formats

​Example Project Structure

​Project Updates

​Manual Updates

​Automatic Updates

​Webhook Configuration

​Troubleshooting

​Common Issues

​Debug Project Updates

​Best Practices

​Repository Organization

​Branch Strategy

​Performance

​Security

​API Examples

​Create Git Project

​Update Project

​See Also