CI/CD Integration

Overview

Dokrypt integrates with CI/CD pipelines so your smart contract tests run automatically on every push and pull request. The dokrypt ci generate command scaffolds workflow files for your CI provider.

Quick Start

# Generate a GitHub Actions workflow
dokrypt ci generate --provider github

# Generate with testnet deployment step
dokrypt ci generate --provider github --deploy

# Generate for GitLab CI
dokrypt ci generate --provider gitlab

GitHub Actions

Generate Workflow

dokrypt ci generate --provider github

This creates .github/workflows/dokrypt.yml:

name: Dokrypt CI

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  test:
    name: Smart Contract Tests
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Install Dokrypt
        run: npm install -g dokrypt@latest

      - name: Verify installation
        run: dokrypt doctor

      - name: Start environment
        run: dokrypt up --detach --fresh

      - name: Wait for services
        run: dokrypt status --wait --timeout 60s

      - name: Run tests
        run: dokrypt test run --json > test-results.json

      - name: Upload test results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: test-results
          path: test-results.json

      - name: Stop environment
        if: always()
        run: dokrypt down --volumes

What It Does

Triggers on push to main/develop and on pull requests
Installs Dokrypt via npm
Runs dokrypt doctor to verify Docker is available
Starts the full environment (dokrypt up)
Runs all tests with JSON output for machine parsing
Uploads test results as a build artifact
Cleans up the environment even if tests fail

With Deployment

dokrypt ci generate --provider github --deploy

Adds a deploy-testnet job that runs after tests pass on the main branch. Requires these GitHub secrets:

Secret	Description
`TESTNET_RPC_URL`	RPC endpoint for the target testnet
`DEPLOYER_PRIVATE_KEY`	Private key for contract deployment

GitLab CI

Generate Config

dokrypt ci generate --provider gitlab

This creates .gitlab-ci.yml:

stages:
  - test

variables:
  DOKRYPT_VERSION: "latest"

test:
  stage: test
  image: node:20
  services:
    - docker:dind
  variables:
    DOCKER_HOST: tcp://docker:2375
    DOCKER_TLS_CERTDIR: ""
  before_script:
    - npm install -g dokrypt@${DOKRYPT_VERSION}
    - dokrypt doctor
  script:
    - dokrypt up --detach --fresh
    - dokrypt status --wait --timeout 60s
    - dokrypt test run --json > test-results.json
    - dokrypt down --volumes
  artifacts:
    when: always
    paths:
      - test-results.json

GitLab CI requires Docker-in-Docker (docker:dind) as a service since Dokrypt uses Docker to run blockchain nodes.

JSON Test Output

All CI workflows use --json output. The format:

{
  "total": 4,
  "passed": 4,
  "failed": 0,
  "skipped": 0,
  "duration": "44ms",
  "suites": [
    {
      "name": "contracts",
      "tests": [
        {
          "name": "test_increment",
          "status": "passed",
          "duration": "12ms"
        }
      ]
    }
  ],
  "gas_report": {
    "entries": [
      {
        "contract": "Counter",
        "function": "increment",
        "avg_gas": 26432,
        "min_gas": 26432,
        "max_gas": 26432
      }
    ]
  }
}

Use this output to:

Fail builds on test failures (exit code is non-zero)
Track gas usage over time by comparing gas_report across commits
Generate reports in your CI dashboard

Validate Workflow

Check that your CI workflow file has the required steps:

dokrypt ci validate

Found GitHub Actions workflow: .github/workflows/dokrypt.yml
  Environment startup      ok
  Test execution           ok
  Environment cleanup      ok
  Code checkout            ok
Workflow is valid

Custom Pipelines

For CI systems not directly supported, use these commands in your pipeline:

# 1. Install
npm install -g dokrypt

# 2. Verify
dokrypt doctor

# 3. Start environment
dokrypt up --detach --fresh

# 4. Wait for readiness
dokrypt status --wait --timeout 60s

# 5. Run tests
dokrypt test run --json --gas-report > results.json

# 6. Cleanup (always run, even on failure)
dokrypt down --volumes

Requirements

Requirement	Why
Docker	Dokrypt runs blockchain nodes as containers
Node.js 18+	For `npm install -g dokrypt`
4GB+ RAM	Blockchain nodes need memory

Most CI runners (GitHub Actions ubuntu-latest, GitLab shared runners) have Docker pre-installed. If yours doesn’t, use a Docker-in-Docker setup.

Gas Tracking Across Commits

Compare gas usage between commits by saving the JSON output:

# In CI, after tests pass:
dokrypt test run --json --gas-report > gas-report-$GITHUB_SHA.json

Upload as an artifact to track gas changes over time. If gas increases significantly on a PR, it may indicate an optimization regression.

Getting Started

Core Concepts

Features

Advanced

CI/CD Integration

Overview

Quick Start

GitHub Actions

Generate Workflow

What It Does

With Deployment

GitLab CI

Generate Config

JSON Test Output

Validate Workflow

Custom Pipelines

Requirements

Gas Tracking Across Commits

​Overview

​Quick Start

​GitHub Actions

​Generate Workflow

​What It Does

​With Deployment

​GitLab CI

​Generate Config

​JSON Test Output

​Validate Workflow

​Custom Pipelines

​Requirements

​Gas Tracking Across Commits

Overview

Quick Start

GitHub Actions

Generate Workflow

What It Does

With Deployment

GitLab CI

Generate Config

JSON Test Output

Validate Workflow

Custom Pipelines

Requirements

Gas Tracking Across Commits