CI/CD pipelines

Pull request reviews through the GitHub, GitLab, or Bitbucket integration do not need a CI job. Add a CLI job only when you want scans that your pipeline controls.

How `vidoc ci` works

vidoc ci runs without questions. It does these steps:

It uploads the new and changed files of the current folder to Vidoc, as vidoc scan does.
It finds the default branch from the origin remote. If the CLI cannot read the remote, it uses origin/main, or origin/master if only that branch exists.
It finds the files that the commits of the current branch changed, compared with the default branch (from the merge base). Uncommitted changes are not included.
It scans only these files and waits until the scan is complete.
It prints the validated issues that Vidoc has for the branch, and a summary by severity.

On the default branch, there are no changes to compare. vidoc ci prints “No scannable files matched the selected scope in the current directory.” and ends without a scan. The list in step 5 contains all validated issues of the branch, not only the issues in the changed files. The CLI does not filter the list by status.

Requirements for the CI job

Full Git history. vidoc ci needs the default branch and the merge base. Use a full clone (for example fetch-depth: 0 on GitHub Actions).
A branch name. Many CI systems check out a detached HEAD. Without a branch name, Vidoc uses the commit SHA as the branch name. Run git checkout -B "<branch name>" before vidoc ci.
Network access. The runner must reach the Vidoc API. On a self-hosted installation, runners that your CI provider hosts (for example GitHub-hosted runners or Bitbucket Pipelines) run outside your network.
Credentials. Keep the API key in the secret store of your CI system as VIDOC_TOKEN. For a self-hosted installation, also set VIDOC_API_URL to https://api.<your-domain>. On Vidoc Cloud, VIDOC_API_URL is optional. The default is https://api.vidoc.dev.

For all environment variables, refer to Configuration.

Options

vidoc ci accepts the same options as vidoc scan: -f, --only-indexing, -p, --api-url, --token, -c, and --debug. Refer to Scanning options. In CI, use environment variables for the key, not --token, so that the key does not show in the job log.

Exit codes

Code	Meaning
`0`	`vidoc ci` ended. This includes these cases: the scan found issues, the scan failed (“Scan did not complete successfully”), or there were no changes to scan.
`1`	The CLI stopped with an error, for example a configuration error, an authentication error, a network error, or an API error.

vidoc ci does not fail the job when it finds issues. To fail the job, refer to Fail a pipeline on issues.

Examples

The pipeline files below are examples. Change them for your pipelines and test them before you use them.

GitHub Actions
GitLab CI
Bitbucket Pipelines

Go to Settings > Secrets and variables > Actions in the repository.
Add VIDOC_TOKEN as a repository secret.
Self-hosted only: add VIDOC_API_URL as a repository variable.
Add a workflow, for example .github/workflows/vidoc.yml:

name: Vidoc scan
on:
  pull_request:

jobs:
  vidoc-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: git checkout -B "$GITHUB_HEAD_REF"
      - run: npm install -g @vidocsecurity/cli@0.1.21
      - run: vidoc ci
        env:
          VIDOC_TOKEN: ${{ secrets.VIDOC_TOKEN }}
          # Self-hosted only. Remove this line for Vidoc Cloud.
          VIDOC_API_URL: ${{ vars.VIDOC_API_URL }}

On pull_request events, GitHub Actions checks out a detached HEAD. $GITHUB_HEAD_REF is the name of the PR source branch.

On GitHub Actions, vidoc ci can print “No Github token provided. Skipping comment.” You can ignore this message. PR comments come from the GitHub integration.

Go to Settings > CI/CD > Variables in the project.
Add VIDOC_TOKEN as a masked variable.
Self-hosted only: add VIDOC_API_URL.
Add this job to .gitlab-ci.yml:

vidoc-scan:
  image: node:20
  stage: test
  variables:
    GIT_DEPTH: 0
  script:
    - git checkout -B "$CI_COMMIT_REF_NAME"
    - npm install -g @vidocsecurity/cli@0.1.21
    - vidoc ci
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

GitLab runners check out a detached HEAD. $CI_COMMIT_REF_NAME is the name of the merge request (MR) source branch. GIT_DEPTH: 0 gets the full history.

Bitbucket Pipelines is a function of Bitbucket Cloud. On Bitbucket Data Center, use your CI server with the same steps.

Go to Repository settings > Repository variables.
Add VIDOC_TOKEN as a secured variable.
Self-hosted only: add VIDOC_API_URL.
Add this pipeline to bitbucket-pipelines.yml:

image: node:20

clone:
  depth: full

pipelines:
  pull-requests:
    '**':
      - step:
          name: Vidoc scan
          script:
            - git checkout -B "$BITBUCKET_BRANCH"
            - npm install -g @vidocsecurity/cli@0.1.21
            - vidoc ci

$BITBUCKET_BRANCH is the name of the PR source branch. The git checkout -B line makes sure that the scan uses this name, also when the pipeline checks out a detached HEAD.

Fail a pipeline on issues

vidoc ci can return exit code 0 even when a scan fails. To enforce a rule, replace the vidoc ci step with the script below. Run the script with Bash after the checkout and CLI installation steps. Before you run it:

Set VIDOC_TOKEN, VIDOC_API_URL, and VIDOC_CODEBASE_ID in CI. Set the API URL explicitly for both Cloud and self-hosted jobs. Refer to API addresses.
Get the repository ID with GET /v1/codebase.
Check out the intended commit on a named branch, as in the pipeline examples above. Use a clean checkout and install curl and jq.
Run only one scan at a time for this repository and branch while the gate runs. Issue results are the current branch state, not an immutable snapshot of a scan.

The script captures the ID printed by this CLI run and checks that exact scan. It fails if no scan starts, if the scan is not complete, if an API request or response is invalid, or if the API reports open critical or high findings on the branch. It includes known open findings in unchanged files and respects the issue visibility policy described in List issues.

set -euo pipefail

: "${VIDOC_API_URL:?Set the API URL of your deployment}"
: "${VIDOC_TOKEN:?Set the API key in your CI secret store}"
: "${VIDOC_CODEBASE_ID:?Set the repository ID}"
API="${VIDOC_API_URL%/}"
BRANCH=$(git symbolic-ref --quiet --short HEAD)
SCAN_LOG=$(mktemp)
trap 'rm -f "$SCAN_LOG"' EXIT

# 1. Run the scan and capture its ID. Do not select the latest branch scan.
vidoc ci 2>&1 | tee "$SCAN_LOG"
SCAN_ID=$(sed -nE 's/.*Scan started with ID: ([0-9a-fA-F-]{36}).*/\1/p' "$SCAN_LOG")
if [[ ! "$SCAN_ID" =~ ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ ]]; then
  echo "Vidoc did not return one scan ID. Check the CLI output."
  exit 1
fi

# 2. This scan must be complete and belong to the expected repository and branch.
SCAN=$(curl --fail-with-body --silent --show-error \
  "$API/v1/scan-workflows/$SCAN_ID/status" \
  -H "x-vidoc-token: $VIDOC_TOKEN")
printf '%s' "$SCAN" | jq -es \
  --arg id "$SCAN_ID" --arg codebase "$VIDOC_CODEBASE_ID" --arg branch "$BRANCH" \
  'length == 1 and (.[0] | type == "object" and
   .id == $id and .status == "completed" and
   .codebaseId == $codebase and .branch == $branch)' > /dev/null

# 3. Reject missing or invalid counts before applying the severity rule.
TOTAL=$(curl --fail-with-body --silent --show-error -G "$API/v1/issues" \
  -H "x-vidoc-token: $VIDOC_TOKEN" \
  --data-urlencode "codebaseId=$VIDOC_CODEBASE_ID" \
  --data-urlencode "branch=$BRANCH" \
  --data-urlencode "status=open" \
  --data-urlencode "severity=critical,high" \
  --data-urlencode "limit=1" | jq -ers '
    if length == 1 then .[0] else error("Expected one response") end |
    .total | if type == "number" then
      if . >= 0 and . == floor then . else error("Invalid issue count") end
    else error("Missing or invalid issue count") end')

if [ "$TOTAL" != "0" ]; then
  echo "Vidoc found $TOTAL open critical or high issues on $BRANCH."
  exit 1
fi

echo "Vidoc scan $SCAN_ID completed with no open critical or high issues on $BRANCH."

This example reads the Scan started with ID: message from CLI 0.1.21. Pin the CLI version for a required CI check, and verify this message when you upgrade. A run with no scannable changes returns no scan ID, so this gate fails. Define an explicit skip rule in your CI if your team permits that case. Manual and CLI scans can have no commit SHA in the API. The scan ID ties the completion check to this invocation; it does not certify a commit snapshot. To change the finding rule, change severity and status. Refer to List issues.

Configuration

Environment variables and precedence.

Issues API

Read and filter issues.

Get started

Deployment

Integrations

Pull request reviews

Web app

CLI

API reference

Reference

CI/CD pipelines

How `vidoc ci` works

Requirements for the CI job

Options

Exit codes

Examples

Fail a pipeline on issues

Configuration

Issues API

​How vidoc ci works

​Requirements for the CI job

​Options

​Exit codes

​Examples

​Fail a pipeline on issues

​Related pages

Configuration

Issues API

How `vidoc ci` works

Requirements for the CI job

Options

Exit codes

Examples

Fail a pipeline on issues

Related pages