Pipery Ansible CD#

Repository: pipery-ansible-cd
Release tag: v1.1.0
Catalog: /catalog/

Reusable GitHub Action for Ansible-based deployment with structured logging via Pipery.

Table of Contents#

Quick Start
Pipeline Overview
Configuration Options
Usage Examples
GitLab CI
Bitbucket Pipelines
About Pipery
Development

Quick Start#

name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pipery-dev/ansible-cd@v1.1.0
        with:
          playbook: deploy.yml
          inventory: inventory/production
          ssh_key: ${{ secrets.SSH_KEY }}

Pipeline Overview#

Step	Description	Skip Input
Requirements	Install pip and Ansible dependencies	`skip_requirements`
Deploy	Execute Ansible playbook	`skip_deploy`
Status check	Verify deployment	`skip_status_check`

Configuration Options#

Name	Default	Description
`project_path`	`.`	Path to the project source tree.
`config_file`	`.pipery/config.yaml`	Path to Pipery config file.
`playbook`	`playbook.yml`	Path to the Ansible playbook file.
`inventory`	`inventory`	Path to the Ansible inventory file.
`requirements`	``	Path to requirements.txt for pip.
`ansible_requirements`	``	Path to requirements.yml for ansible-galaxy.
`extra_vars`	``	Extra variables as JSON or key=val pairs.
`ssh_key`	``	SSH private key for connecting to hosts.
`ssh_known_hosts`	``	Known hosts content for SSH.
`become`	`false`	Use sudo/become for privilege escalation.
`tags`	``	Comma-separated playbook tags to run.
`log_file`	`pipery.jsonl`	Path to write the JSONL log file.
`skip_requirements`	`false`	Skip pip/galaxy requirements install.
`skip_deploy`	`false`	Skip playbook run step.
`skip_status_check`	`false`	Skip status check step.

Usage Examples#

Example 1: Basic Ansible playbook deployment#

name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pipery-dev/ansible-cd@v1.1.0
        with:
          playbook: deploy.yml
          inventory: inventory/production
          ssh_key: ${{ secrets.SSH_KEY }}

Example 2: With Ansible Galaxy requirements#

- uses: pipery-dev/ansible-cd@v1.1.0
  with:
    playbook: site.yml
    inventory: inventories/production/hosts.yml
    ansible_requirements: requirements.yml
    ssh_key: ${{ secrets.SSH_KEY }}

Example 3: Run specific tags only#

- uses: pipery-dev/ansible-cd@v1.1.0
  with:
    playbook: deploy.yml
    inventory: inventory/production
    tags: docker,service
    ssh_key: ${{ secrets.SSH_KEY }}

Example 4: With extra variables and privilege escalation#

- uses: pipery-dev/ansible-cd@v1.1.0
  with:
    playbook: deploy.yml
    inventory: inventory/production
    extra_vars: '{"version":"1.2.3","env":"prod"}'
    become: true
    ssh_key: ${{ secrets.SSH_KEY }}

Example 5: With Python dependencies#

- uses: pipery-dev/ansible-cd@v1.1.0
  with:
    playbook: deploy.yml
    inventory: inventory/production
    requirements: requirements.txt
    ansible_requirements: requirements.yml
    ssh_key: ${{ secrets.SSH_KEY }}

Example 6: Known hosts configuration#

- uses: pipery-dev/ansible-cd@v1.1.0
  with:
    playbook: deploy.yml
    inventory: inventory/production
    ssh_key: ${{ secrets.SSH_KEY }}
    ssh_known_hosts: ${{ secrets.SSH_KNOWN_HOSTS }}

GitLab CI#

Use the GitLab mirror template when .gitlab-ci.yml is published for this pipeline family. Import it from the mirrored GitLab project or use it as a reference implementation for running the same Pipery pipeline outside GitHub Actions.

The GitLab pipeline maps action inputs to CI/CD variables, publishes pipery.jsonl as an artifact, and maintains the same skip controls. Store credentials as protected GitLab CI/CD variables.

include:
  - project: pipery-dev/ansible-cd
    ref: v1.1.0
    file: /.gitlab-ci.yml

GitLab CI Variables#

Configure these protected variables in Settings > CI/CD > Variables:

SSH_KEY - SSH private key (base64-encoded)
SSH_KNOWN_HOSTS - Known hosts content
ANSIBLE_PLAYBOOK - Path to playbook file
ANSIBLE_INVENTORY - Path to inventory file

Bitbucket Pipelines#

Bitbucket Cloud pipelines provide an alternative to GitHub Actions. Use Bitbucket shared pipeline imports to reference the exported Pipery pipeline instead of copying YAML into every application repository.

Getting Started#

Add a Bitbucket import source for the shared Pipery pipeline and import the exported pipeline by name:

definitions:
  imports:
    pipery-shared: pipery-dev/ansible-cd:v1.1.0
    pipery-custom: pipery-dev/ansible-cd:v1.1.0:.bitbucket/shared-pipelines.yml

pipelines:
  branches:
    main:
      import: pipery-ansible-cd@pipery-shared

  custom:
    run-pipery:
      import: pipery-ansible-cd@pipery-custom

Use {project-path}/{repo-slug}:{branch-or-tag} for a shared repository bitbucket-pipelines.yml, or {project-path}/{repo-slug}:{branch-or-tag}:{config-filepath} for another exported YAML file.

Configure Protected Variables in Repository Settings > Pipelines > Repository Variables:
- SSH_KEY - SSH private key (base64-encoded)
- SSH_KNOWN_HOSTS - Known hosts content
- ANSIBLE_PLAYBOOK - Playbook file path
- ANSIBLE_INVENTORY - Inventory file path
Commit to trigger deployment

Pipeline Stages#

The Bitbucket equivalent follows the same structure:

checkout → setup → requirements → deploy → status_check → logs

Features#

Support for VMs and bare metal servers
Ansible Galaxy role/collection support
Python dependency management
SSH key-based authentication
Privilege escalation (become)
Tag-based playbook execution
Extra variables support
Known hosts management
JSONL-based pipeline logging
90-day log retention

About Pipery#

Pipery Pipery is an open-source CI/CD observability platform. Every step script runs under psh (Pipery Shell), which intercepts all commands and emits structured JSONL events — giving you full visibility into your pipeline without any manual instrumentation.

Browse logs in the Pipery Dashboard
Find all Pipery actions on GitHub Marketplace
Source code: pipery-dev

Development#

# Run the action locally against test-project/
pipery-actions test --repo .

# Regenerate docs
pipery-actions docs --repo .

# Dry-run release
pipery-actions release --repo . --dry-run