How to Run Apidog CLI API Tests in Drone CI

You 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 environment. Your Apidog access token lives in a Drone secret and is injected through from_secret. This guide walks through a copy-paste .drone.yml, secret handling, branch gating, and how to expose the test report since Drone has no built-in artifact store.

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, the practice of building and testing code automatically on every change. If you want a refresher on the concept itself, see what is CI/CD.

The defining trait of Drone is simple: every pipeline step runs inside its own Docker container. There is no shared build agent with a sprawl of pre-installed tools. You pick an image for each step, and Drone runs your commands inside it. That makes builds reproducible and easy to reason about.

You define a pipeline in a .drone.yml file at the root of your repository. A Docker pipeline has three top-level keys: kind, type, and name. The work happens under steps, where each step declares a name, an image, and a list of commands.

kind: pipeline
type: docker
name: api-tests

steps:
  - name: greeting
    image: alpine
    commands:
      - echo hello
      - echo world

Drone runs the commands as a shell script with set -e and set -x, so the build fails fast on the first non-zero exit code and echoes each command before running it. Commands override the container entrypoint, and the working directory is your repository root.

Why Run API Tests in a Container Step

API tests guard against contract drift. A backend change that quietly alters a response shape or status code can break every client downstream. Running those tests on every push catches the regression before it ships.

Apidog fits this model well. You build and maintain your tests visually in the Apidog app, then run the exact same test scenarios from the command line with the Apidog CLI. No script rewriting, no separate test harness. For broader guidance on wiring API tests into pipelines, read CI/CD best practices for API testing.

Apidog is an all-in-one API platform for design, debugging, testing, mocking, and documentation. The CLI is the piece that turns your saved test scenarios into a single repeatable command, which is exactly what a Drone step needs.

The Apidog CLI Command You Will Run

Install the CLI with npm, then run a test scenario. In CI you point the run at a saved scenario with flags, so there is no local collection file to manage.

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

Here is what each flag does:

• --access-token passes your Apidog access token. There is no short form.
• -t is the test scenario ID you want to run.
• -e is the environment ID, and it is required. This selects which base URL and variables the run uses.
• -r lists the reporters. Valid values are cli, html, json, and junit.

You can add more flags as needed:

• -n or --iteration-count repeats the run a set number of times.
• -d or --iteration-data takes a CSV or JSON file path, or a numeric stored data-set ID, for data-driven runs.
• --out-dir sets the report output directory.
• --upload-report pushes a report overview to Apidog cloud, where you can view it in the app. You can use it as a bare flag.
• --on-error controls failure behavior with continue, end, or ignore.
• --project <id> and --branch <name> target a specific project branch.

For a full tour of the command and its options, see the Apidog CLI complete guide and the walkthrough on testing a REST API from the command line.

A Complete .drone.yml for Apidog Tests

Here is a working pipeline. It uses a Node image, installs the CLI, and runs your scenario. The token comes from a Drone secret rather than being hardcoded.

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

Replace 1234567 with your test scenario ID and 89012 with your environment ID. Both are visible in the Apidog app. Because the step uses the cli reporter, the full pass/fail breakdown prints straight into the Drone build log, where anyone reviewing the build can read it.

Storing Secrets in Drone CI

Never commit an API token to your repository. Drone keeps secrets out of the YAML and injects them at runtime.

You reference a secret inside a step’s environment block (or a plugin’s settings block) with from_secret. The value you write is the secret’s name, not the token itself.

environment:
  APIDOG_ACCESS_TOKEN:
    from_secret: apidog_access_token

There are two common ways to create the secret. The first is the Drone UI: open your repository, go to Settings, then Secrets, and add a secret named apidog_access_token with your token as the value. The second is the Drone command-line tool.

drone secret add \
  --repository your-org/your-repo \
  --name apidog_access_token \
  --data your-apidog-token

Confirm the exact flag names against the Drone CLI docs for your version, since CLI flags can change between releases. Drone also supports an in-repo encrypted-secret variant where drone encrypt produces an encrypted blob you embed as a separate kind: secret YAML document. For most teams, repo secrets added through the UI or drone secret add are simpler and the recommended starting point.

Keeping the token in a secret is the same discipline you would apply anywhere else. For more on how the CLI handles credentials, see the guide on Apidog CLI authentication.

Gating Runs by Branch and Event

Drone gives you two levers for controlling when work runs: trigger at the pipeline level and when at the step level.

A trigger block decides whether the whole pipeline runs. All conditions must evaluate true, so the example below runs only on pushes and pull requests targeting main.

trigger:
  branch:
    - main
  event:
    - push
    - pull_request

A when block sits inside a single step and gates just that step. This is useful when you want most of the pipeline to run everywhere but reserve a heavier test pass for one branch.

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

Both blocks support glob patterns and include/exclude sub-keys. Supported event types include push, pull_request, tag, promote, rollback, cron, and custom.

Exposing Test Reports Without an Artifact Store

Drone has no native artifact hosting. That changes how you handle reports, but you have two clean options.

The first is the simplest: use the cli reporter so results print into the build log. For most teams this is enough, since the log already shows which assertions passed and which failed.

The second option is to generate an HTML report and upload it somewhere durable. Drone publishes an official S3 plugin, plugins/s3, that uploads files to S3 or any S3-compatible store. Generate the report with the html reporter and --out-dir, then add an upload step.

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

The plugin reads its AWS credentials from secrets through from_secret, the same mechanism you used for the Apidog token. The source key is a glob of files to upload, and target is the destination prefix in the bucket.

If you want a deeper look at what the report contains and how to read it, see the breakdown of Apidog CLI test reports.

Adding Data-Driven Runs

Sometimes one scenario needs to run against many input rows: ten user IDs, a dozen payloads, a set of edge cases. The CLI handles this with -d, which accepts a CSV or JSON file path or a stored data-set ID.

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

Each row in data.csv becomes one iteration, with column values bound to your scenario variables. The full pattern is covered in Apidog CLI data-driven testing.

How This Compares to Other CI Tools

The Drone pattern, install the CLI in a clean container and run one command, carries over to nearly every CI system. The wrapper syntax differs, but the Apidog step is the same.

If you also run pipelines elsewhere, Apidog has matching walkthroughs for GitHub Actions and Azure Pipelines. The shared idea is that your tests live in Apidog and the CI tool simply triggers them.

One honest note on scope: the Apidog CLI runs functional and contract tests, not high-scale load testing. If you need thousands of concurrent virtual users to stress an endpoint, reach for a dedicated load-testing tool. For verifying that your API behaves correctly on every commit, the CLI in a Drone step does the job well.

Build the Tests Visually, Run Them With One Command

The workflow that makes this pleasant is the split between authoring and execution. You design endpoints and assemble test scenarios visually in Apidog, chaining requests, asserting on status codes and response fields, and reusing environment variables. No code required to build the suite.

Then CI runs that same suite with one CLI command inside a container step. When a teammate updates a test in the Apidog app, the next Drone build picks it up automatically. There is no second copy of the tests to keep in sync.

Download Apidog for free to build your first test scenario, then drop the .drone.yml above into your repository 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 the pre-installed-tool sprawl of traditional 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 most teams, the self-hosted open-source version covers running API tests like the ones in this guide.

Is Drone CI open source?

Yes. Drone is one of the original container-native CI tools and remains open source. When Harness acquired it in 2020, the company committed to keeping the project open source, and you can still self-host it.

How is Drone CI used?

Teams use Drone to automatically build, test, and deliver code on every push or pull request. You commit a .drone.yml to your repository, Drone reads it, and runs each step in a container. Common steps include compiling code, running unit tests, running API tests, and uploading artifacts to external storage.

How do you store secrets in Drone CI?

You add secrets through the repository’s Settings then Secrets screen in the Drone UI, or with drone secret add from the CLI. You then reference each secret inside a step’s environment or a plugin’s settings block using from_secret, where the value is the secret’s name. The token itself never appears in your YAML.

Can I run Apidog tests in CI without writing scripts?

Yes. You build test scenarios visually in the Apidog app, then run them in CI with a single apidog run command. The Drone step only needs a Node image, an npm install -g apidog-cli line, and the run command pointed at your scenario and environment IDs.