code3tech.devtools

Production-Ready Ansible Collection for CI/CD Infrastructure

Automate your complete CI/CD infrastructure—from self-hosted runners to container platforms and version management—with unified Ansible configuration across multiple providers.

Multi-Provider CI/CD | Container Platforms | Version Management | Production-Grade

Quick Start • Documentation • Support

Built For

Platform Engineers building self-service CI/CD infrastructure
DevOps Teams managing multi-provider environments
Site Reliability Engineers maintaining production-grade runner fleets

The Challenge

Managing self-hosted CI/CD infrastructure across different providers requires learning provider-specific APIs, maintaining separate deployment scripts for each platform, ensuring consistency across heterogeneous environments, and scaling infrastructure while keeping configuration manageable.

The Solution

A unified Ansible Collection that provides consistent configuration across all CI/CD providers, API-driven automation for lifecycle management, production-tested patterns ready for enterprise deployment, and an extensible architecture for future provider additions.

CI/CD Strategy Building Blocks

Every modern CI/CD strategy requires these core components. This collection provides all of them with a unified approach.

Self-Hosted Runners & Agents

Purpose: Cost control, security compliance, custom hardware requirements

Capabilities:

Multi-provider support: GitHub Actions, GitLab CI, Azure DevOps
API-driven lifecycle management (create, update, delete)
Multi-runner deployment per host with isolated directories
Service verification and automated monitoring
Extensible architecture for additional providers

Container Platforms

Purpose: Consistent build environments, reproducible deployments

Capabilities:

Docker: Industry-standard container platform with BuildKit optimization
Podman: Daemonless, rootless alternative for enhanced security
Automatic registry authentication handling
Production-optimized configurations
Multi-platform support (Ubuntu, Debian, RHEL)

Version Management

Purpose: Runtime consistency across teams and environments

Capabilities:

asdf version manager with 300+ plugin ecosystem
Centralized group-based architecture
Binary installation for reliability
Shell integration (bash, zsh, fish)
Multi-language support (Node.js, Python, Ruby, Go, and more)

The Unified Approach

All components use the same Ansible configuration pattern: consistent variable structure, unified authentication methods, standardized error handling, and common service management.

Result: Learn once, deploy everywhere.

Key Features

Automation	Security	Production
API-driven management	Ansible Vault integration	Battle-tested patterns
Zero-touch deployment	Automatic permission fixes	Multi-distribution testing
Idempotent operations	SELinux/AppArmor support	Service verification

Lifecycle Management	Multi-Platform	Documentation
Create, update, delete	Ubuntu/Debian/RHEL	Comprehensive guides
Service management	x86_64 + ARM64	Real-world examples
Clean unregistration	Container support	Troubleshooting resources

Included Roles

CI/CD Runners & Agents

Azure DevOps Agents

Deploy and manage Azure DevOps self-hosted agents on Linux servers.

Key Capabilities:

Multi-agent support with isolated directories per host
Three agent types: Self-hosted, Deployment Group, Environment
Automatic resource creation via Azure DevOps REST API
Pipeline permission configuration for environments
Service verification and lifecycle management
Clean agent unregistration and removal

Role README | Complete Guide

GitHub Actions Runners

Deploy and manage GitHub Actions self-hosted runners on Linux servers.

Key Capabilities:

Multi-runner support with isolated directories per host
Three deployment scopes: Organization, Repository, Enterprise
Label management and updates via GitHub REST API
Runner group creation and assignment
Ephemeral runner support for enhanced security
Service verification and lifecycle management

Role README | Complete Guide

GitLab CI Runners

Deploy and manage GitLab CI self-hosted runners on Linux servers.

Key Capabilities:

Multi-runner support with isolated directories per host
Three runner types: Instance, Group, Project runners
API-based management: Create, update, delete via GitLab REST API
Tag management without re-registration
Advanced configuration: run_untagged, locked, access_level
Service verification and lifecycle management

Role README | Complete Guide

Container Platforms

Docker

Complete Docker Engine installation and configuration with Docker Compose support.

Key Capabilities:

Multi-platform support: Ubuntu 22+, Debian 11+, RHEL/CentOS/Rocky 9+
Registry authentication with automatic permission handling
BuildKit enabled by default for faster builds
Optimized logging and storage configuration
User group management with security controls

Role README | Complete Guide

Podman

Podman installation with rootless container support.

Key Capabilities:

Daemonless container engine (no Docker daemon required)
Enhanced rootless support with per-user authentication
Complete toolchain: Buildah and Skopeo included
OCI-compliant and Docker command compatible
Multi-platform support across all major distributions

Role README | Complete Guide

Version Management

asdf

asdf version manager with centralized group-based architecture.

Key Capabilities:

Centralized plugin management for all users
Group-based permissions with asdf group
300+ plugins: Node.js, Python, Ruby, Golang, Terraform, and more
Shell integration for bash, zsh, and fish
Binary installation for reliability and performance

Role README | Complete Guide

Quick Start

Installation

Step 1: Install the collection from Ansible Galaxy

ansible-galaxy collection install code3tech.devtools

Step 2: Install required dependencies

ansible-galaxy collection install -r requirements.yml

Your First Deployment

Choose your use case and create a playbook:

Option A: Deploy CI/CD Runners

---
- name: Deploy GitHub Actions runners
  hosts: runner_hosts
  become: true
  
  roles:
    - role: code3tech.devtools.github_actions_runners
      vars:
        github_api_token: "{{ vault_github_token }}"
        github_runners_list:
          - name: "runner-01"
            state: "started"
            labels: ["linux", "x64"]

Option B: Deploy Container Platform

---
- name: Deploy Docker
  hosts: docker_hosts
  become: true
  
  roles:
    - role: code3tech.devtools.docker
      vars:
        docker_users: ["{{ ansible_user }}"]

Step 3: Run your playbook

ansible-playbook setup.yml -i inventory

Next Steps:

Complete Usage Guide - Detailed setup procedures
Role Documentation - Role-specific configuration
Example Playbooks - Ready-to-use examples

Usage Guide

CI/CD Runners Setup

Prerequisites

Before deploying runners or agents, ensure you have:

API Tokens: Personal access tokens or runner registration tokens
- Store securely in Ansible Vault (never commit tokens to version control)
- Token Setup Guide
Target Hosts: Prepared Linux servers
- Supported: Ubuntu 22.04+, Debian 11+, RHEL 9+
- Requirements: 2GB RAM, 10GB disk space, sudo access
Network Access: Connectivity to provider APIs
- GitHub: https://api.github.com
- GitLab: https://gitlab.com/api or your GitLab instance
- Azure: https://dev.azure.com

Basic Runner Deployment

1. Create inventory:

[github_runners]
runner-host-01 ansible_host=192.168.1.10

[gitlab_runners]
runner-host-02 ansible_host=192.168.1.11

[azure_agents]
agent-host-01 ansible_host=192.168.1.12

2. Store tokens securely:

# Create encrypted vault file
ansible-vault create vars/vault.yml

# Add tokens:
vault_github_token: "ghp_xxxxxxxxxxxx"
vault_gitlab_token: "glpat-xxxxxxxxxxxx"
vault_azure_pat: "xxxxxxxxxxxx"

3. Create playbook:

---
- name: Deploy CI/CD Runners
  hosts: github_runners
  become: true
  vars_files:
    - vars/vault.yml
  
  roles:
    - role: code3tech.devtools.github_actions_runners
      vars:
        github_api_token: "{{ vault_github_token }}"
        github_runners_list:
          - name: "runner-01"
            state: "started"
            labels: ["linux", "production"]

4. Deploy:

ansible-playbook deploy-runners.yml -i inventory --ask-vault-pass

Detailed Guides:

Container Platform Setup

Docker Deployment

Deploy Docker with user access and registry authentication:

---
- name: Setup Docker
  hosts: docker_hosts
  become: true
  vars_files:
    - vars/vault.yml
  
  roles:
    - role: code3tech.devtools.docker
      vars:
        docker_users:
          - "{{ ansible_user }}"
        docker_registries_auth:
          - registry: "ghcr.io"
            username: "myuser"
            password: "{{ vault_github_token }}"

Docker Complete Setup

Podman Deployment

Deploy Podman with rootless support:

---
- name: Setup Podman
  hosts: podman_hosts
  become: true
  
  roles:
    - role: code3tech.devtools.podman
      vars:
        podman_rootless_users:
          - "appuser"

Podman Rootless Guide

Version Manager Setup

asdf Deployment

Deploy asdf with language runtimes for development teams:

---
- name: Setup asdf
  hosts: dev_servers
  become: true
  
  roles:
    - role: code3tech.devtools.asdf
      vars:
        asdf_plugins:
          - name: nodejs
            versions: ["20.11.0"]
            global: "20.11.0"
          - name: python
            versions: ["3.11.7"]
            global: "3.11.7"

asdf Complete Guide

Requirements

Requirement	Version
Ansible	>= 2.15
Python	>= 3.9
Target OS	Ubuntu 22.04+, Debian 11+, RHEL 9+

Required Collections

ansible-galaxy collection install -r requirements.yml

Dependencies:

community.docker >= 3.4.0 (Docker registry authentication)
containers.podman >= 1.10.0 (Podman registry authentication)

Supported Distributions

Distribution	Versions
Ubuntu	22.04 (Jammy), 24.04 (Noble), 25.04 (Plucky)
Debian	11 (Bullseye), 12 (Bookworm), 13 (Trixie)
RHEL/Rocky/Alma	9, 10

Documentation

Getting Started

Getting Started Guide

CI/CD Runners

GitHub Actions Runners

GitLab CI Runners

Azure DevOps Agents

Container Platforms

Docker

Podman

Version Management

asdf

Reference

FAQ - Frequently asked questions

Example Playbooks

The collection includes ready-to-use example playbooks in the playbooks/ directory:

Azure DevOps Agents

Playbook	Description
install-production.yml	Production deployment with validation
install-single-agent.yml	Basic single agent installation
install-multi-agent.yml	Multiple agents per host

GitHub Actions Runners

Playbook	Description
install-production.yml	Production deployment with validation
install-single-runner.yml	Basic single runner installation
install-multi-runner.yml	Multiple runners per host

GitLab CI Runners

Playbook	Description
install-production.yml	Production deployment with all features and comprehensive validation

Docker

Playbook	Description
install-docker.yml	Production Docker installation with optimizations

Podman

Playbook	Description
install-podman.yml	Production Podman installation with rootless support

asdf

Playbook	Description
install-asdf-basic.yml	Quick install with lightweight plugins (direnv, jq)
install-asdf-full.yml	Full installation with Node.js and Python
setup-multi-user.yml	Multi-user configuration

Running Examples

# Install dependencies
ansible-galaxy collection install -r requirements.yml

# Run a playbook
ansible-playbook playbooks/docker/install-docker.yml -i your_inventory

See playbooks/README.md for complete documentation.

Development

Setup Environment

# Clone the repository
git clone https://github.com/kode3tech/ansible-col-devtools.git
cd ansible-col-devtools

# Activate virtual environment (creates if needed)
source activate.sh

# Install dependencies
ansible-galaxy collection install -r requirements.yml

# Verify installation
ansible --version
molecule --version

Testing

# Test a specific role
cd roles/docker
molecule test

# Test all roles
make test

# Run linters
make lint

Makefile Commands

make help              # Show available commands
make install           # Install dependencies
make lint              # Run yamllint and ansible-lint
make test              # Test all roles with Molecule
make build             # Build collection tarball
make install-collection # Install collection locally
make clean             # Clean build artifacts

Collection Structure

code3tech.devtools/
├── galaxy.yml                    # Collection metadata
├── README.md                     # This file
├── CHANGELOG.md                  # Version history
├── requirements.yml              # Collection dependencies
├── roles/
│   ├── azure_devops_agents/      # Azure DevOps Agents role
│   ├── docker/                   # Docker role
│   ├── podman/                   # Podman role
│   └── asdf/                     # asdf role
├── playbooks/                    # Example playbooks
│   ├── azure_devops_agents/
│   ├── docker/
│   ├── podman/
│   └── asdf/
├── plugins/
│   └── shared_tasks/             # Reusable tasks
└── docs/                         # Documentation
    ├── user-guides/
    ├── reference/
    └── FAQ.md

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'feat: add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Guidelines

Follow existing code style and use FQCN for all modules
Add tests for new features
Update documentation
Ensure all tests pass (make test)
Ensure linting passes (make lint)
Use conventional commits format

See CONTRIBUTING.md for detailed guidelines.

License

MIT License - see LICENSE file for details.

Authors

Code3Tech DevOps Team

GitHub: @kode3tech
Email: suporte@code3.tech

Issues & Support

Bug Reports: GitHub Issues
Feature Requests: GitHub Issues

Links

Made with ❤️ by Code3Tech DevOps Team

Name		Name	Last commit message	Last commit date
Latest commit History 47 Commits
.github		.github
docs		docs
meta		meta
playbooks		playbooks
plugins		plugins
roles		roles
tests/sanity		tests/sanity
.ansible-lint		.ansible-lint
.gitignore		.gitignore
.markdownlint.json		.markdownlint.json
.markdownlintignore		.markdownlintignore
.pylintrc		.pylintrc
.tool-versions		.tool-versions
.yamllint		.yamllint
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
SECURITY.md		SECURITY.md
activate.sh		activate.sh
ansible.cfg		ansible.cfg
galaxy.yml		galaxy.yml
inventory.example		inventory.example
requirements.txt		requirements.txt
requirements.yml		requirements.yml

License

kode3tech/ansible-col-devtools

Folders and files

Latest commit

History

Repository files navigation

code3tech.devtools

Production-Ready Ansible Collection for CI/CD Infrastructure

Table of Contents

Built For

The Challenge

The Solution

CI/CD Strategy Building Blocks

Self-Hosted Runners & Agents

Container Platforms

Version Management

The Unified Approach

Key Features

Included Roles

CI/CD Runners & Agents

Azure DevOps Agents

GitHub Actions Runners

GitLab CI Runners

Container Platforms

Docker

Podman

Version Management

asdf

Quick Start

Installation

Your First Deployment

Usage Guide

CI/CD Runners Setup

Prerequisites

Basic Runner Deployment

Container Platform Setup

Docker Deployment

Podman Deployment

Version Manager Setup

asdf Deployment

Requirements

Required Collections

Supported Distributions

Documentation

Getting Started

CI/CD Runners

GitHub Actions Runners

GitLab CI Runners

Azure DevOps Agents

Container Platforms

Docker

Podman

Version Management

asdf

Reference

Example Playbooks

Azure DevOps Agents

GitHub Actions Runners

GitLab CI Runners

Docker

Podman

asdf

Running Examples

Development

Setup Environment

Testing

Makefile Commands

Collection Structure

Contributing

Guidelines

License

Authors

Issues & Support

Links

About

Topics

Resources

License

Code of conduct

Contributing

Packages