GO Ansible

A Go module for programmatically executing Ansible playbooks with support for Galaxy integration, temporary file management, and flexible configuration.

Documentation: https://pkg.go.dev/github.com/arillso/go.ansible/v2

Quick Start

Install the module:

go get github.com/arillso/go.ansible/v2

Basic usage:

package main

import (
    "context"
    "log"
    "github.com/arillso/go.ansible/v2" // package name is "ansible"
)

func main() {
    pb := ansible.NewPlaybook()
    pb.Config.Playbooks = []string{"site.yml"}
    pb.Config.Inventories = []string{"localhost,"}

    if err := pb.Exec(context.Background()); err != nil {
        log.Fatalf("Execution failed: %v", err)
    }
}

Examples

Runnable examples live in example_test.go and on pkg.go.dev. A few common setups:

Vault password

The password is written to a temporary file and passed via --vault-password-file. Set Config.TempDir to a tmpfs mount in security-critical environments so secrets never touch persistent disk.

pb := ansible.NewPlaybook()
pb.Config.Playbooks = []string{"site.yml"}
pb.Config.Inventories = []string{"production,"}
pb.Config.VaultPassword = "s3cr3t"
if err := pb.Exec(context.Background()); err != nil {
    log.Fatal(err)
}

Galaxy requirements

Roles and collections from a requirements file are installed before the run.

pb := ansible.NewPlaybook()
pb.Config.GalaxyFile = "requirements.yml"
pb.Config.Playbooks = []string{"site.yml"}
pb.Config.Inventories = []string{"localhost,"}
if err := pb.Exec(context.Background()); err != nil {
    log.Fatal(err)
}

Extra vars, limit and tags

pb := ansible.NewPlaybook()
pb.Config.Playbooks = []string{"site.yml"}
pb.Config.Inventories = []string{"production,"}
pb.Config.ExtraVars = []string{"env=staging", "version=1.2.3"}
pb.Config.Limit = "web"
pb.Config.Tags = "deploy"
if err := pb.Exec(context.Background()); err != nil {
    log.Fatal(err)
}

Cancellation with context

Cancelling the context terminates the underlying ansible-playbook process — useful for honouring SIGINT or an overall deadline.

ctx, cancel := context.WithCancel(context.Background())
defer cancel()
pb := ansible.NewPlaybook()
pb.Config.Playbooks = []string{"site.yml"}
pb.Config.Inventories = []string{"localhost,"}
if err := pb.Exec(ctx); err != nil { // returns a context error when cancelled
    log.Fatal(err)
}

Preview the generated command without running Ansible via pb.CommandStrings(ctx).

Features

• Automated playbook resolution with glob pattern support
• Secure temporary file management for SSH keys and Vault passwords
• Ansible Galaxy role and collection installation
• Flexible command customization (inventories, extra vars, SSH options)
• Debug mode with command tracing
• Context-based execution with cancellation support

Testing

Run tests:

go test -v ./...

License

MIT License

Copyright

(c) 2021-2026, Arillso