How to Integrate aqua with CI/CD Pipelines: Complete GitHub Actions and CircleCI Guide

Integrate aqua with CI/CD pipelines using the official aqua-installer GitHub Action or CircleCI Orb to install tools with automatic checksum verification and caching.

The aqua CLI—developed in the aquaproj/aqua repository—is a declarative tool version manager that ensures the same binary versions run on developer laptops and CI runners. Because the CLI entry point at cmd/aqua/main.go is a thin wrapper around the controller logic in pkg/controller/install/install.go, the exact same installation and verification behavior applies whether you run aqua i locally or inside a containerized job.

GitHub Actions Integration

Installing aqua with the Official Action

The fastest way to integrate aqua with CI/CD pipelines on GitHub is the aqua-installer action. It downloads the aqua binary, verifies its SHA-256 checksum, and executes aqua i to install all tools defined in aqua.yaml.

# .github/workflows/ci.yml

name: CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: aquaproj/aqua-installer@v4
        with:
          aqua_version: v2.43.1
          aqua_opts: ""
        env:
          AQUA_CONFIG: aqua.yaml

      - run: |
          go test ./...
          terraform fmt -check

The action validates the installer script's checksum (as documented in website/docs/products/aqua-installer/index.md) before executing, ensuring the binary integrity matches the source code in pkg/checksum.

Caching Tool Binaries Across Runs

To avoid re-downloading tools on every job, cache the aqua installation directory at ~/.local/share/aquaproj-aqua. The cache key should hash aqua.yaml so it invalidates when your tool versions change.

- uses: actions/cache@v3
  with:
    path: ~/.local/share/aquaproj-aqua
    key: ${{ runner.os }}-aqua-${{ hashFiles('aqua.yaml') }}
    restore-keys: |
      ${{ runner.os }}-aqua-

If you use split configuration files (.aqua/*.yaml), include those patterns in the hash key as shown in the installer documentation lines 30-34.

Automating Checksum Updates

When you modify tool versions, aqua-checksums.json must be updated to reflect new SHA-256 hashes. Use the reusable workflow from the aqua repository to automate this via PR:

# .github/workflows/update-checksums.yml

name: Update aqua-checksums.json
on:
  schedule:
    - cron: '0 0 * * 0'
  workflow_dispatch:

jobs:
  update:
    uses: aquaproj/aqua/.github/workflows/update-checksum-workflow.yml@main

This workflow runs aqua update-checksum and commits changes, leveraging the checksum controller logic in pkg/controller/install/install.go.

CircleCI Integration

Importing the CircleCI Orb

For CircleCI pipelines, use the circleci-orb-aqua to install aqua and expose tools on the $PATH. The Orb uses the same underlying installer as the GitHub Action, ensuring consistent behavior with the local CLI.

version: 2.1
orbs:
  aqua: aquaproj/circleci-orb-aqua@1

workflows:
  test:
    jobs:
      - aqua/install:
          aqua_version: v2.43.1
          aqua_opts: ""
      - test:
          requires:
            - aqua/install

The Orb validates the binary checksum against pkg/checksum verification logic before adding ~/.local/share/aquaproj-aqua/bin to the environment.

Updating Checksums in CircleCI Workflows

To keep aqua-checksums.json synchronized within CircleCI, invoke the update-checksum command after the installation job:

- aqua/update-checksum:
    requires:
      - aqua/install

This command executes aqua update-checksum and requires a write-enabled GitHub token to commit changes back to the repository.

Implementing Cache Persistence

CircleCI's caching mechanism mirrors the GitHub Actions strategy. Restore the aqua directory before installation and save it afterward:

- restore_cache:
    keys:
      - v2-aqua-{{ .Environment.CIRCLE_OS_NAME }}-{{ checksum "aqua.yaml" }}
- aqua/install:
    aqua_version: v2.43.1
- save_cache:
    paths:
      - ~/.local/share/aquaproj-aqua
    key: v2-aqua-{{ .Environment.CIRCLE_OS_NAME }}-{{ checksum "aqua.yaml" }}

Architecture and Configuration Files

Understanding the underlying implementation helps debug CI failures. The aqua architecture separates concerns across three layers:

• CLI Layer (cmd/aqua/main.go): Parses commands and forwards to controllers
• Controller Layer (pkg/controller/install/install.go): Handles package resolution, version management, and checksum verification
• Runtime Layer (pkg/config, pkg/checksum): Reads aqua.yaml and validates aqua-checksums.json

Key files you must commit to your repository for CI integration:

• aqua.yaml: Declares tool versions and registries (source: aqua/aqua.yaml in the aqua repo)
• aqua-checksums.json: Stores SHA-256 hashes for verification; required when require_checksum is enabled in your configuration

When aqua_opts is set to an empty string (""), the controller performs a full installation rather than lazy linking, which is optimal for CI caching but consumes more storage.

Summary

• Use official wrappers: The aquaproj/aqua-installer action and aquaproj/circleci-orb-aqua Orb provide verified, checksum-protected installation methods.
• Cache aggressively: Store ~/.local/share/aquaproj-aqua between runs to eliminate redundant downloads.
• Secure by default: Commit aqua-checksums.json and enable require_checksum to ensure the controller in pkg/controller/install/install.go validates every binary against its SHA-256 hash.
• Unify environments: The same aqua.yaml configuration drives both local development and CI/CD pipelines, eliminating "works on my machine" discrepancies.

Frequently Asked Questions

How do I pin a specific aqua version in my CI pipeline?

Specify the aqua_version parameter in the aqua-installer action or CircleCI Orb. For example, set aqua_version: v2.43.1 to ensure the controller logic from that release handles your installations. The installer downloads the exact release asset from GitHub and verifies its checksum before execution.

Why should I disable lazy installation (-l) in CI environments?

Setting aqua_opts: "" disables the default -l (lazy install) flag, forcing aqua i to download and install all binaries immediately rather than creating symlinks that download on first use. This ensures all tools are present in the cache directory (~/.local/share/aquaproj-aqua) before you save the cache, preventing runtime downloads during job execution.

What happens if aqua-checksums.json is missing or outdated in CI?

If your aqua.yaml has require_checksum: true (recommended), the checksum verifier in pkg/checksum will halt the installation and exit with an error when it cannot verify a tool's SHA-256 hash. In GitHub Actions, use the reusable update-checksum workflow to automatically refresh this file via pull requests. In CircleCI, use the aqua/update-checksum command to regenerate and commit the file.

Can I use aqua in GitLab CI or other non-GitHub/CircleCI platforms?

Yes. Because the aqua binary is a standalone Go executable built from cmd/aqua/main.go, you can install it in any container or VM by downloading the release asset and running aqua i. Ensure the ~/.local/share/aquaproj-aqua/bin directory is added to $PATH and cache that directory between jobs using your platform's caching primitives.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}