If you’ve been following my blog series, you already know I’ve set up Ansible AWX on Kubernetes using Helm. Now the next logical step for me was — how do I actually get my playbooks into AWX without manually uploading them every time?
The answer is GitLab. In this blog I’ll walk through how I installed GitLab on a VM, pushed my Ansible playbooks to it, and then synced that repo into AWX as a project — in two ways:
Using an SSH key (SCM Private Key) — this is what I actually use in production
Using a Personal Access Token over HTTP — good for quick lab setups
Let’s get into it.
What We’re Building Here
The flow looks like this:
Ansible Server → Push Playbooks → GitLab (self-hosted VM) → Sync → AWX Project & Templates
Once this is set up, every time I update a playbook and push to GitLab, AWX syncs and picks up the latest version automatically. That’s the real power of this setup.
Part 1 — Installing GitLab on a VM
I installed GitLab on a separate Ubuntu 22.04 VM. Here’s exactly what I ran:
Step 1 — Install Dependencies
sudo apt update
sudo apt install -y curl openssh-server ca-certificates tzdata perl
Step 2 — Add GitLab Repository and Install
curl https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh | sudo bash
sudo apt install gitlab-ce
Step 3 — Configure GitLab
sudo vi /etc/gitlab/gitlab.rb
Update the external URL to your VM IP:
rubyexternal_url ‘http://10.*.*.**‘
Then reconfigure:
sudo gitlab-ctl reconfigure
Step 4 — Get the Initial Root Password
sudo cat /etc/gitlab/initial_root_password
Open http://10.*.*.* in your browser → log in with root and the password above.
Tip: Change your root password immediately after first login — User Settings → Password.
Part 2. Creating a repo and pushing playbooks
Inside GitLab, I created a new blank project called:
ansibleawx
Set it to private and moved on.
On my Ansible server, I configured Git:
git config --global user.name "Sireesha"
git config --global user.email "[email protected]"
Then inside my playbook directory:
cd /etc/ansible
git init
git remote add origin http://ip/ansibleawx.git
git add .
git commit -m "Initial commit - adding ansible playbooks"
git branch -M patches
git push -u origin patches
I’m using a patches branch here because that’s what I decided to track in AWX later.
That part matters more than it looks — branch mismatches will bite you.
Part3. Connecting AWX to GitLab using SSH (production way)
This is the setup I actually use properly. It’s more secure and avoids token expiry issues.
Generate SSH key (on AWX side)
ssh-keygen -t rsa -b 4096 -C "awx@ansible"
Then grab the public key:
cat ~/.ssh/id_rsa.pub
Add it to GitLab
GitLab → User Settings → SSH Keys → paste key → save
Nothing complicated here.
Create AWX credential
In AWX:
Credentials → Add
Name: gitlab-cred
Type: Source Control
Username: root
SCM Private Key: paste private key (~/.ssh/id_rsa)
Click Save.
Create AWX project
AWX → Projects → Add
Name: AnsibleAWX
SCM Type: Git
URL: http:///ansibleawx.git
Branch: patches
Credential: gitlab-cred
Once saved, AWX syncs automatically.
When it turns green, you’re good.
That’s the moment everything starts clicking.
This is exactly the gitlab-cred credential I have set up — you can see from the screenshot it shows Credential Type: Source Control and SCM Private Key: Encrypted.
Part4. Alternative: HTTP with Personal Access Token
This is the quicker setup I used in a lab environment.
Create token in GitLab
GitLab → Settings → Access Tokens
Scope: read_repository
Copy it (you only see it once).
Add to AWX
Credentials → Add
Name: gitlab-http-cred
Username: root
Password:
Save.
Create project
Same as before, but use this credential instead.
It works fine — just not as clean or durable as SSH.
Part 5 — Creating Job Templates in AWX
Once the project sync works, playbooks automatically appear in AWX.
So I created a simple job template:
AWX → Templates → Add
- Name: Linux Server Setup
- Job Type: Run
- Inventory: your inventory
- Project: AnsibleAWX
- Playbook: select from dropdown
- Credentials: your machine credentials
Save and launch.
At this point, AWX is basically running whatever is in GitLab.
No file copying. No manual updates.
Errors I Hit Along the Way
Error 1 — Git Push Branch Mismatch
error: src refspec main does not match any
Fix — rename the branch to match what you set in AWX:
git branch -M patches
git push -u origin patches
Error 2 — AWX Sync Failed on SSH Host KeyHost key verification failed
Fix — in your AWX Project settings under Source Control Options, tick:
✅ Disregard Host Checks
Error 3 — Playbook Dropdown Empty in Job TemplateAfter syncing, the playbook dropdown was empty when creating a job template
.
Fix — go back to your Project → hit the Sync button (circular arrow) → wait for green → go back to template. Playbooks will appear.
Before this, updating a playbook meant manually copying files and hoping AWX had the latest version. Now my workflow is:
Edit playbook → git push to patches branch → AWX syncs → Launch job
Everything is version controlled, auditable, and consistent.
Drop your questions in the comments — happy to help!
— Sireesha