DEV Community

Cover image for How to Run Apidog CLI API Tests in Drone CI
Hassann
Hassann

Posted on • Originally published at apidog.com

How to Run Apidog CLI API Tests in Drone CI

Run Apidog CLI API tests in Drone CI by adding a Docker pipeline step that uses a Node image, installs apidog-cli, and runs apidog run against an Apidog environment. Store your Apidog access token as a Drone secret and inject it with from_secret. This guide gives you a copy-paste .drone.yml, secret setup, branch/event gating, and report handling for Drone’s lack of built-in artifact storage.

Try Apidog today

What Drone CI Is and How It Works

Drone is an open-source, container-native CI/CD platform, now part of Harness. CI/CD stands for continuous integration and continuous delivery: automatically building and testing code on every change. If you need a refresher, see what is CI/CD.

Drone’s main design choice is that every pipeline step runs in its own Docker container. Instead of relying on a shared build agent with pre-installed tools, you choose the image for each step and Drone executes your commands inside it.

You define a Drone pipeline in .drone.yml at the root of your repository. A Docker pipeline uses three top-level keys:

kind: pipeline
type: docker
name: api-tests
Enter fullscreen mode Exit fullscreen mode

Steps go under steps. Each step typically has:

  • name
  • image
  • commands

Minimal example:

kind: pipeline
type: docker
name: api-tests

steps:
  - name: greeting
    image: alpine
    commands:
      - echo hello
      - echo world
Enter fullscreen mode Exit fullscreen mode

Drone runs the commands as a shell script with set -e and set -x, so the build stops on the first non-zero exit code and prints each command before executing it. The working directory is your repository root.

Why Run API Tests in a Container Step

API tests catch contract drift before it reaches users. If a backend change modifies a response field, status code, or error shape, downstream clients can break even if the service still “works.”

Apidog fits Drone’s container model because you can:

  1. Build and maintain API test scenarios visually in Apidog.
  2. Run those same scenarios from CI with the Apidog CLI.
  3. Fail the Drone build when the API behavior does not match expectations.

For broader CI guidance, see CI/CD best practices for API testing.

Apidog is an all-in-one API platform for design, debugging, testing, mocking, and documentation. In this workflow, the CLI is the execution layer that turns saved test scenarios into a repeatable CI command.

The Apidog CLI Command You Will Run

Install the CLI with npm, then run a saved test scenario:

npm install -g apidog-cli
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli
Enter fullscreen mode Exit fullscreen mode

Replace:

  • 1234567 with your Apidog test scenario ID
  • 89012 with your Apidog environment ID

Flag breakdown:

Flag Purpose
--access-token Passes your Apidog access token. There is no short form.
-t Test scenario ID to run.
-e Environment ID. Required. Selects base URL and environment variables.
-r Reporter list. Valid values include cli, html, json, and junit.

Useful optional flags:

# Run the scenario multiple times
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -n 3 -r cli

# Run with data from a CSV or JSON file
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -d ./data.csv -r cli

# Write reports to a custom directory
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli,html --out-dir reports

# Upload a report overview to Apidog cloud
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli --upload-report
Enter fullscreen mode Exit fullscreen mode

Other useful options include:

  • --on-error continue|end|ignore
  • --project <id>
  • --branch <name>

For more CLI details, see the Apidog CLI complete guide and the guide to testing a REST API from the command line.

A Complete .drone.yml for Apidog Tests

Add this file to the root of your repository:

kind: pipeline
type: docker
name: apidog-api-tests

steps:
  - name: run-api-tests
    image: node:20-alpine
    environment:
      APIDOG_ACCESS_TOKEN:
        from_secret: apidog_access_token
    commands:
      - npm install -g apidog-cli
      - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli

trigger:
  branch:
    - main
  event:
    - push
    - pull_request
Enter fullscreen mode Exit fullscreen mode

Update these values:

-t 1234567
-e 89012
Enter fullscreen mode Exit fullscreen mode

Use the test scenario ID and environment ID from your Apidog project.

This pipeline does four things:

  1. Starts a Docker pipeline.
  2. Uses node:20-alpine as the execution environment.
  3. Installs apidog-cli.
  4. Runs the Apidog scenario and prints results to the Drone build log.

Because the command uses -r cli, the pass/fail output is visible directly in Drone logs.

Storing Secrets in Drone CI

Do not commit API tokens to .drone.yml. Store the Apidog token as a Drone secret and inject it at runtime.

Reference the secret in a step’s environment block:

environment:
  APIDOG_ACCESS_TOKEN:
    from_secret: apidog_access_token
Enter fullscreen mode Exit fullscreen mode

Here:

  • APIDOG_ACCESS_TOKEN is the environment variable available inside the container.
  • apidog_access_token is the Drone secret name.
  • The token value never appears in the repository.

Option 1: Add the Secret in the Drone UI

In Drone:

  1. Open your repository.
  2. Go to Settings.
  3. Open Secrets.
  4. Add a secret named apidog_access_token.
  5. Paste your Apidog access token as the value.

Option 2: Add the Secret with the Drone CLI

Example:

drone secret add \
  --repository your-org/your-repo \
  --name apidog_access_token \
  --data your-apidog-token
Enter fullscreen mode Exit fullscreen mode

Check the Drone CLI documentation for your installed version because flags can differ between releases.

Drone also supports encrypted in-repo secrets using drone encrypt, but repository secrets created through the UI or drone secret add are the simpler starting point for most teams.

For more about CLI credential handling, see Apidog CLI authentication.

Gating Runs by Branch and Event

Drone gives you two ways to control when tests run:

  • trigger at the pipeline level
  • when at the step level

Gate the Entire Pipeline with trigger

This runs the whole pipeline only for pushes and pull requests on main:

trigger:
  branch:
    - main
  event:
    - push
    - pull_request
Enter fullscreen mode Exit fullscreen mode

Use this when API tests should not run outside selected branches or events.

Gate One Step with when

Use when when the pipeline should run broadly, but the Apidog test step should run only in specific cases:

steps:
  - name: run-api-tests
    image: node:20-alpine
    environment:
      APIDOG_ACCESS_TOKEN:
        from_secret: apidog_access_token
    commands:
      - npm install -g apidog-cli
      - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli
    when:
      branch:
        - main
      event:
        - push
Enter fullscreen mode Exit fullscreen mode

Supported event types include:

  • push
  • pull_request
  • tag
  • promote
  • rollback
  • cron
  • custom

Both trigger and when support glob patterns and include/exclude sub-keys.

Exposing Test Reports Without an Artifact Store

Drone does not provide native artifact hosting. You have two practical options for Apidog reports.

Option 1: Print Results to the Build Log

Use the cli reporter:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli
Enter fullscreen mode Exit fullscreen mode

This is the simplest setup. Results appear directly in the Drone logs, including pass/fail details.

Option 2: Generate HTML and Upload to S3

If you need a durable report, generate an HTML report and upload it to S3 or an S3-compatible store with Drone’s plugins/s3.

Example:

kind: pipeline
type: docker
name: apidog-api-tests

steps:
  - name: run-api-tests
    image: node:20-alpine
    environment:
      APIDOG_ACCESS_TOKEN:
        from_secret: apidog_access_token
    commands:
      - npm install -g apidog-cli
      - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli,html --out-dir reports

  - name: upload-report
    image: plugins/s3
    settings:
      bucket: my-bucket
      region: us-east-1
      source: reports/**/*
      target: /apidog-reports
      access_key:
        from_secret: aws_access_key
      secret_key:
        from_secret: aws_secret_key
Enter fullscreen mode Exit fullscreen mode

The S3 plugin uses the same from_secret pattern:

access_key:
  from_secret: aws_access_key
secret_key:
  from_secret: aws_secret_key
Enter fullscreen mode Exit fullscreen mode

In the upload step:

  • source is the file glob to upload.
  • target is the destination prefix in the bucket.
  • AWS credentials are injected from Drone secrets.

For more on report contents, see Apidog CLI test reports.

Adding Data-Driven Runs

Use data-driven testing when the same scenario should run against multiple inputs, such as user IDs, payload variants, or edge cases.

The Apidog CLI supports data files with -d:

commands:
  - npm install -g apidog-cli
  - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -d ./data.csv -r cli
Enter fullscreen mode Exit fullscreen mode

Each row in data.csv becomes one iteration. Column values are bound to variables in your Apidog scenario.

You can also pass a JSON file path or a stored data-set ID.

Example with a custom report directory:

commands:
  - npm install -g apidog-cli
  - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -d ./data.csv -r cli,html --out-dir reports
Enter fullscreen mode Exit fullscreen mode

For the full pattern, see Apidog CLI data-driven testing.

How This Compares to Other CI Tools

The Drone setup is the same basic pattern used in most CI systems:

  1. Start a clean container or runner.
  2. Install apidog-cli.
  3. Inject the Apidog token from a secret store.
  4. Run apidog run.
  5. Fail the build on test failure.

The wrapper syntax changes between CI platforms, but the Apidog command stays mostly the same.

If you also use other CI tools, see the Apidog walkthroughs for GitHub Actions and Azure Pipelines.

One scope note: the Apidog CLI runs functional and contract tests. It is not a high-scale load-testing tool. If you need thousands of concurrent virtual users, use a dedicated load-testing tool. For verifying API behavior on every commit, running the CLI in a Drone step is the right fit.

Build the Tests Visually, Run Them With One Command

A practical Apidog + Drone workflow looks like this:

  1. Design endpoints in Apidog.
  2. Create test scenarios visually.
  3. Add assertions for status codes, response fields, and business rules.
  4. Reuse Apidog environment variables for base URLs and credentials.
  5. Run the same scenario in Drone with apidog run.

When a teammate updates a scenario in Apidog, the next Drone build runs the updated version. You do not need to maintain a second test suite in the repository.

Download Apidog for free to build your first test scenario, then add the .drone.yml above to run it on every push.

Frequently Asked Questions

What is Drone CI?

Drone is an open-source, container-native CI/CD platform, now part of Harness. It runs every pipeline step inside its own Docker container, with pipelines defined in a .drone.yml file. This keeps builds reproducible and avoids relying on pre-installed tools on shared build agents.

Is Drone CI free?

The core Drone project is open source and free to self-host. After the Harness acquisition, Drone became Harness CI Community Edition, with paid enterprise tiers available. For many teams, the self-hosted open-source version is enough to run API tests like the pipeline in this guide.

Is Drone CI open source?

Yes. Drone is one of the original container-native CI tools and remains open source. Harness acquired Drone in 2020 and committed to keeping the project open source.

How is Drone CI used?

Teams use Drone to build, test, and deliver code automatically on pushes, pull requests, tags, cron events, and other triggers. You commit a .drone.yml file, Drone reads it, and each step runs inside a container. Common steps include compiling code, running unit tests, running API tests, building images, and uploading reports to external storage.

How do you store secrets in Drone CI?

Add secrets in the Drone UI under the repository’s Settings > Secrets, or use drone secret add from the CLI. Reference secrets in a step’s environment block or a plugin’s settings block with from_secret. The value you write in YAML is the secret name, not the secret value.

Example:

environment:
  APIDOG_ACCESS_TOKEN:
    from_secret: apidog_access_token
Enter fullscreen mode Exit fullscreen mode

Can I run Apidog tests in CI without writing scripts?

Yes. Build test scenarios visually in Apidog, then run them in CI with one command:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli
Enter fullscreen mode Exit fullscreen mode

In Drone, you only need a Node image, npm install -g apidog-cli, and the apidog run command pointed at your scenario and environment IDs.

Top comments (0)