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

> Easily integrate aqua with CI/CD pipelines using GitHub Actions and CircleCI. Install tools securely with automatic checksum verification and caching.

- Repository: [aquaproj/aqua](https://github.com/aquaproj/aqua)
- Tags: how-to-guide
- Published: 2026-02-25

---

**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`](https://github.com/aquaproj/aqua/blob/main/cmd/aqua/main.go) is a thin wrapper around the controller logic in [`pkg/controller/install/install.go`](https://github.com/aquaproj/aqua/blob/main/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`](https://github.com/aquaproj/aqua/blob/main/aqua.yaml).

```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`](https://github.com/aquaproj/aqua/blob/main/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`](https://github.com/aquaproj/aqua/blob/main/aqua.yaml) so it invalidates when your tool versions change.

```yaml
- 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`](https://github.com/aquaproj/aqua/blob/main/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:

```yaml

# .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`](https://github.com/aquaproj/aqua/blob/main/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.

```yaml
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`](https://github.com/aquaproj/aqua/blob/main/aqua-checksums.json) synchronized within CircleCI, invoke the `update-checksum` command after the installation job:

```yaml
- 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:

```yaml
- 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`](https://github.com/aquaproj/aqua/blob/main/cmd/aqua/main.go)): Parses commands and forwards to controllers
- **Controller Layer** ([`pkg/controller/install/install.go`](https://github.com/aquaproj/aqua/blob/main/pkg/controller/install/install.go)): Handles package resolution, version management, and checksum verification
- **Runtime Layer** (`pkg/config`, `pkg/checksum`): Reads [`aqua.yaml`](https://github.com/aquaproj/aqua/blob/main/aqua.yaml) and validates [`aqua-checksums.json`](https://github.com/aquaproj/aqua/blob/main/aqua-checksums.json)

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

- [`aqua.yaml`](https://github.com/aquaproj/aqua/blob/main/aqua.yaml): Declares tool versions and registries (source: [`aqua/aqua.yaml`](https://github.com/aquaproj/aqua/blob/main/aqua/aqua.yaml) in the aqua repo)
- [`aqua-checksums.json`](https://github.com/aquaproj/aqua/blob/main/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`](https://github.com/aquaproj/aqua/blob/main/aqua-checksums.json) and enable `require_checksum` to ensure the controller in [`pkg/controller/install/install.go`](https://github.com/aquaproj/aqua/blob/main/pkg/controller/install/install.go) validates every binary against its SHA-256 hash.
- **Unify environments**: The same [`aqua.yaml`](https://github.com/aquaproj/aqua/blob/main/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`](https://github.com/aquaproj/aqua/blob/main/aqua-checksums.json) is missing or outdated in CI?

If your [`aqua.yaml`](https://github.com/aquaproj/aqua/blob/main/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`](https://github.com/aquaproj/aqua/blob/main/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.