Ansible Gitlab Component

This GitLab component runs Ansible playbooks in a structured and GitOps-friendly way. It supports secure key injection, Windows host compatibility, and full access to GitLab CI/CD environment variables for API calls, tagging, and traceability.

🔧 Requires GitLab 15.11+ and Component CI/CD syntax.

---

See Also:

• Ansible OCI – Docker runtime image for Ansible workflows
• StageFreight GitLab Component – GitLab component that provides CI pipeline orchestration for releases
• StageFreight OCI (Docker Image) – A general-purpose DevOps automation image built to accelerate CI/CD pipelines.

---

📦 Usage

Add the component to your .gitlab-ci.yml:

deploy:
  stage: deploy
  needs: [sync-fs]
  component: $CI_SERVER_FQDN/components/ansible/run@~latest
  inputs:
    ansible_dir: "$CI_PROJECT_DIR/ansible"
    ansible_inventory: "$CI_PROJECT_DIR/ansible/inventory"
    ansible_playbook: "ansible/playbooks/deploy.yaml"
    ssh_private_key: $SSH_PRIVATE_KEY
    windows_password: $ANSIBLE_WINDOWS_PASSWORD

    ci_commit_tag: "$CI_COMMIT_TAG"
    ci_project_dir: "$CI_PROJECT_DIR"
    gitlab_api_url: "$CI_API_V4_URL"
    gitlab_branch: "main"
    gitlab_project_id: "$CI_PROJECT_ID"
    gitlab_token: "$GITLAB_TOKEN"

⚙️ Inputs

run

Ansible Config

Configuration settings for Ansible execution

Name	Required	Default	Description
ansible_host_key_checking	🚫	""	Disables SSH host key checking. (Discouraged in untrusted environments.)
ansible_inventory	🚫	"ansible/inventory"	Path to an inventory file with hosts/infra to target.
ansible_playbook	✅	""	Path to a playbook file.
sops_age_key_b64	🚫	""	A Base64-encoded Age key for SOPS.
sops_age_key_path	🚫	""	Path to an Age key stored as a file for SOPS.
ssh_private_key	🚫	""	The SSH private key used for SSH key-based auth.
windows_password	🚫	""	The password used to connect to non-domain managed Windows hosts.
working_dir	🚫	""	The base path to assign during ansible execution.

Gitlab Job Config

Inputs that configure GitLab Job behavior

Name	Required	Default	Description
job	🚫	"run-ansible"	The intended name of the CI job spawned by this component.
artifacts	🚫	[]	An array of paths to preserve as CI/CD artifacts.
gitlab_branch	🚫	"main"	Target Git branch for commits.
gitlab_token	🚫	""	Token for authenticating GitLab API calls.
stage	🚫	"ansible"	The intended name of the CI stage this job will run in.

---

test

Ansible Testing Config

Configuration for Ansible testing and linting jobs

Name	Required	Default	Description
job	🚫	"test-ansible"	The intended name of the CI job spawned by this component.
stage	🚫	"$[[ inputs.stage ]]"
root_dir	🚫	"${CI_PROJECT_DIR}/ansible"	Root directory containing Ansible config, inventory, and playbooks.
project_file	✅	""	The filename of a valid Ansible Playbook that will be tested/linted.

---

GitLab CI/CD variables

These allow for easy API interaction and Git-aware deployments.

Name	Default	Description
ci_commit_tag	$CI_COMMIT_TAG	Tag (if any) triggering the pipeline.
ci_project_dir	$CI_PROJECT_DIR	Project directory on runner.
gitlab_api_url	$CI_API_V4_URL	API endpoint for GitLab (e.g., https://gitlab.com/api/v4).
gitlab_branch	main	Branch to commit back to (if applicable).
gitlab_project_id	$CI_PROJECT_ID	Numeric project ID.
gitlab_token	$GITLAB_TOKEN	Token used for GitLab API auth.

🔐 Secrets and SSH

The component automatically:

• Writes the ssh_private_key to a secure id_rsa file
• Adds it to the SSH agent
• Disables host key checking to reduce CI pipeline interruptions
• This makes it easy to connect to remote infrastructure without exposing secrets in job logs.

💡 Windows Support

To target Windows hosts (e.g., for winrm), set the remote_windows_pass and configure your inventory accordingly.

Example:

192.168.1.20 ansible_user=Administrator ansible_connection=winrm ansible_winrm_server_cert_validation=i

📝 Output

All output is printed cleanly in GitLab’s job log with labeled sections:

• SSH setup
• Directory navigation
• Playbook execution

This makes debugging and traceability straightforward for infrastructure teams.

🧪 Example Inventory

[linux]
192.168.1.10 ansible_user=ubuntu

[windows]
192.168.1.20 ansible_user=Administrator ansible_connection=winrm ansible_winrm_server_cert_validation=ignore

🚀 Release Highlights

• 🔄 Refactored to use Component CI syntax
• 🧠 Now injects full GitLab CI/CD context
• 🪪 SSH key configuration is handled automatically
• 🪟 Windows support enabled with remote_windows_pass
• ⚠️ Breaking Change: older jobs using custom script/entrypoints should migrate to this standardized component format

📜 Disclaimer

The Ansible GitOps Component (“Component”) is provided as-is, with zero guarantees—express, implied, or accidentally conjured via a mistyped YAML key. By using this Component, you accept that things might go wonderfully… or go full rm -rf / (hopefully not, but hey, Ansible can be spicy).

The author assumes no responsibility for any blown-up infrastructure, botched deployments, inexplicable UNREACHABLE errors, or sudden desires to rewrite your entire infra in Terraform. If using this Component causes you to rethink your life choices, deep dive into the Ansible documentation abyss, or spiral into 2am playbook debugging marathons—still not liable.

Not responsible if:

• Your CI pipeline mutinies and decides to deploy to prod at 3am.
• Your Windows hosts suddenly go on strike.
• Ansible decides to lint your soul instead of your YAML.

Conversely, if everything does go off without a hitch, that’s probably thanks to the tireless efforts of the Open Source community, Red Hat’s excellent documentation, and sheer dumb luck. The developer of this Component takes no credit for any miracles.

Use responsibly, test ruthlessly, and always keep --check mode close to your heart.

Ansible: Because sometimes, clicking through 12 servers manually is just not it.