Arnica Dependency Scan – GitHub Action

The same scanner is available as a GitHub Action (composite) and as an npm CLI for Azure DevOps, Bitbucket Pipelines, and GitLab CI (npx @arnica-io/dependency-scan).

Extend Arnica’s security scanning into complex build environments that pull dependencies from multiple sources or compile packages from source. When real-time checks aren’t enough, post-build scanning validates SBOMs directly from your CI/CD pipelines via API, returning pass/fail results to enforce security gates before merges or deployments. Ensure consistent policy enforcement and centralized visibility in Arnica’s dashboard, even for environments with intricate dependency resolution.

Pipeline Examples

Reference pipeline files with comments and secret/path notes:

• GitHub Action: examples/github-action.yml
• Azure DevOps: examples/azure-devops.yml
• Bitbucket Pipelines: examples/bitbucket-pipelines.yml
• GitLab CI: examples/gitlab-ci.yml

Quickstart

Add a workflow that runs on PR events and merges to SLA branches for complete security coverage.

name: Arnica Dependency Security Scan
on:
  pull_request:
    types: [opened, synchronize]
  push:
    branches: [main, develop, staging, production] # Add your SLA branches
  workflow_dispatch:

jobs:
  security-scan:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - name: Checkout repository
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd #v6.0.2
        with:
          persist-credentials: false

      - name: Dependency Security Scan with Arnica
        id: arnica
        uses: arnica-io/dependency-scan@6b1377a3d111170de80632696039f658f59940e1 # v1.0.31
        env:
          ARNICA_API_TOKEN: ${{ secrets.ARNICA_API_TOKEN }}
        with:
          repository-url: ${{ github.server_url }}/${{ github.repository }}
          branch: ${{ github.head_ref | github.ref_name }} # Uses the PR source branch for pull requests, or the current branch for pushes
          scan-path: .

      - name: Print scan results
        run: |
          echo "Scan ID: ${{ steps.arnica.outputs['scan-id'] }}"
          echo "Status: ${{ steps.arnica.outputs.status }}"

Pinning to a Commit SHA

While Arnica's action tags are immutable, as a general best practice we recommend pinning all GitHub Actions to a full commit SHA rather than a tag. SHA pinning ensures your workflows are deterministic and aligned with GitHub's security hardening guidelines.

# Best practice – pinned to commit SHA
uses: arnica-io/dependency-scan@6b1377a3d111170de80632696039f658f59940e1 # v1.0.31

The SHA for each release is listed on the Releases page. This README is automatically updated with the latest SHA on every release.

Package Integrity

All npm packages are published with SLSA provenance, providing cryptographic proof that each build originated from this repository. npm versions are immutable — once published, they cannot be modified or overwritten.

Recommended Workflow Triggers

For complete security coverage and accurate issue lifecycle tracking:

• Pull Requests: opened, synchronize - Catches issues before merge
• Main/Release Branches: push to main, develop, staging, production
• Build Pipelines: Add to any workflow where code is built or deployed
• Manual Runs: workflow_dispatch for on-demand scans

Where to View Reports

Security scan results appear in multiple locations:

1. GitHub Step Summary: Detailed findings report in the workflow run
2. Arnica Dashboard: Full vulnerability management at https://app.arnica.io
3. Workflow Logs: Console output with scan details
4. PR Comments (if configured): Summary posted to pull requests

Inputs

| Name | Required | Default | Description | | ---------------------- | :------: | --------------------------- | -------------------------------------------------------------------------- | | repository-url | Yes | | Repository URL associated with the scan | | branch | Yes | main | Branch to associate with the scan | | scan-path | No | . | Directory path to scan and generate SBOM for (e.g., . or services/api) | | api-base-url | No | https://api.app.arnica.io | Arnica API base URL | | api-token | No | | Arnica API token; prefer secret env ARNICA_API_TOKEN | | scan-timeout-seconds | No | 900 | Timeout (seconds) to wait for scan completion | | on-findings | No | fail | Behavior when findings are detected: fail, alert, or pass |

Outputs

• scan-id: Arnica scan identifier.
• status: Final status, one of Success, Failure, Error, Skipped, or Timeout.

CLI Environment Variables (All Platforms)

Use these env vars when running the scanner via npx @arnica-io/dependency-scan (Azure DevOps, Bitbucket Pipelines, and similar CI).

| Name | Required | Default | Description | | ----------------------------- | :------: | --------------------------- | ---------------------------------------- | | ARNICA_API_TOKEN | Yes | | Arnica API token | | ARNICA_API_BASE_URL | No | https://api.app.arnica.io | Arnica API base URL | | ARNICA_REPOSITORY_URL | No | auto-detected | Repository URL override | | ARNICA_BRANCH | No | auto-detected | Branch override | | ARNICA_SCAN_PATH | No | . | Directory path to scan | | ARNICA_SCAN_TIMEOUT_SECONDS | No | 900 | Scan wait timeout in seconds | | ARNICA_ON_FINDINGS | No | fail | fail, alert, or pass | | ARNICA_DEBUG | No | false | Verbose API debug logs when set to true|

Generic DEBUG is intentionally ignored so unrelated tools that set DEBUG=true do not enable Arnica verbose logging.

Auto-detection sources when ARNICA_REPOSITORY_URL / ARNICA_BRANCH are not provided:

• GitHub: GITHUB_SERVER_URL, GITHUB_REPOSITORY, GITHUB_HEAD_REF / GITHUB_REF_NAME
• Azure DevOps: BUILD_REPOSITORY_URI, BUILD_SOURCEBRANCHNAME
• Bitbucket Cloud/Server: BITBUCKET_GIT_HTTP_ORIGIN, BITBUCKET_GIT_SSH_ORIGIN, BITBUCKET_REPO_FULL_NAME, BITBUCKET_WORKSPACE, BITBUCKET_REPO_OWNER, BITBUCKET_REPO_SLUG, BITBUCKET_BRANCH, BITBUCKET_PR_SOURCE_BRANCH, BITBUCKET_SOURCE_BRANCH, BITBUCKET_BRANCH_NAME
• Bitbucket Server (HTTPS clone URL synthesis): BITBUCKET_SERVER_URL or BITBUCKET_BASE_URL with BITBUCKET_REPO_FULL_NAME; optional BITBUCKET_SERVER_SCM_PREFIX (default scm) when the Git HTTP path is not /scm/...
• GitLab CI: CI_REPOSITORY_URL (credentials are stripped automatically), CI_PROJECT_URL, CI_COMMIT_BRANCH, CI_MERGE_REQUEST_SOURCE_BRANCH_NAME, CI_COMMIT_REF_NAME (skipped when CI_COMMIT_TAG is set to avoid reporting tags as branches), CI_DEFAULT_BRANCH (used as fallback in tag pipelines)

Permissions

This action does not require repository write permissions. For least privilege, set:

permissions:
  contents: read

Examples

Scan a subdirectory and alert (do not fail) on policy violations:

- name: Generate SBOM and scan with Arnica
  id: arnica
  uses: arnica-io/dependency-scan@6b1377a3d111170de80632696039f658f59940e1 # v1.0.31
  env:
    ARNICA_API_TOKEN: ${{ secrets.ARNICA_API_TOKEN }}
  with:
    repository-url: https://github.com/owner/repo
    branch: ${{ github.ref_name }}
    scan-path: services/payments
    on-findings: alert

Prerequisites

• Sign in to Arnica with a privileged admin account. Sign in at https://app.arnica.io.

API key and permissions

Create an Arnica API key with only the SBOM scopes:

1. Navigate to Admin → API.
2. Create a new API key.
3. Select scopes: sbom-api:read and sbom-api:write only.
4. Store the token as a repository secret named ARNICA_API_TOKEN.

Azure DevOps Pipelines

Use the published npm package from the registry (npx). You only need checkout: self and a Node task—no extra GitHub service connection for the default flow.

Prerequisites

1. ARNICA_API_TOKEN: Store in a Variable Group (e.g. arnica-secrets under Pipelines → Library) as a secret.
2. Node.js 24+ on the agent (NodeTool@0).

Example pipeline

trigger:
  branches:
    include:
      - main

pool:
  vmImage: ubuntu-latest

variables:
  - group: arnica-secrets

steps:
  - checkout: self

  - task: NodeTool@0
    inputs:
      versionSpec: "24.x"
    displayName: Use Node 24

  - script: |
      set -euo pipefail
      cd "$(Build.SourcesDirectory)"
      npx --yes "@arnica-io/[email protected]"
    displayName: Arnica dependency scan
    env:
      ARNICA_API_TOKEN: $(ARNICA_API_TOKEN)

Pin the version in the npx argument (@x.y.z). This README is updated with current pins on each release.

Self-hosted agent note (npm.pkg.github.com / 401)

If your Azure DevOps self-hosted agent has a global/user .npmrc that maps @arnica-io to GitHub Packages, npx may fail with 401 Unauthorized against npm.pkg.github.com.

Force npmjs for this step:

  - script: |
      set -euo pipefail
      cd "$(Build.SourcesDirectory)"
      npm config set registry "https://registry.npmjs.org/"
      npm config delete @arnica-io:registry || true
      npx --registry "https://registry.npmjs.org/" --yes "@arnica-io/[email protected]"
    displayName: Arnica dependency scan

Advanced: build from a git checkout (lockfile-pinned)

If you want transitives fixed to this repo’s pnpm-lock.yaml, add a GitHub service connection, check out arnica-io/dependency-scan at a release tag, then corepack prepare [email protected] --activate, pnpm install --frozen-lockfile, pnpm run build, and run node dist/cli.js with PATH including that checkout’s node_modules/.bin. Use the same CLI env vars (ARNICA_API_TOKEN, ARNICA_REPOSITORY_URL, ARNICA_BRANCH, ARNICA_SCAN_PATH, ARNICA_ON_FINDINGS, etc.) from $(Build.SourcesDirectory) for the project you are scanning (checkout: self).

Environment variables are documented once in CLI Environment Variables (All Platforms) above.

Example: scan a subdirectory, alert only

Add to the same env block as the main example:

      ARNICA_SCAN_PATH: "services/payments"
      ARNICA_ON_FINDINGS: alert

Where to View Reports (Azure DevOps)

1. Pipeline Extensions Tab: Scan summary is uploaded as a task summary attachment
2. Arnica Dashboard: Full vulnerability management at https://app.arnica.io
3. Pipeline Logs: Console output with scan details

Bitbucket Pipelines

Use the published npm package with npx, same as Azure DevOps.

• Bitbucket Cloud: auto-detects from BITBUCKET_GIT_HTTP_ORIGIN and BITBUCKET_BRANCH.
• Bitbucket Server/Data Center runners: also supports BITBUCKET_GIT_SSH_ORIGIN and derives a repository URL from BITBUCKET_SERVER_URL + BITBUCKET_REPO_FULL_NAME when needed.

You can always override detection with ARNICA_REPOSITORY_URL and ARNICA_BRANCH.

Bitbucket Server URL shape: Auto-derived URLs use {BITBUCKET_SERVER_URL}/{BITBUCKET_SERVER_SCM_PREFIX}/{BITBUCKET_REPO_FULL_NAME}.git with prefix defaulting to scm (common for Atlassian Bitbucket Server). Some installations use a different path segment (for example git); set BITBUCKET_SERVER_SCM_PREFIX to match yours. Project-key layouts, HTTP(S) proxies, or non-standard Git HTTP paths may still require setting REPOSITORY_URL explicitly.

Prerequisites

1. ARNICA_API_TOKEN: Store as a secured repository variable (Repository settings → Pipelines → Repository variables).
2. Node.js 24+ on the step image (for example node:24).

Example pipeline

image: node:24

pipelines:
  default:
    - step:
        name: Arnica dependency scan
        script:
          - cd "$BITBUCKET_CLONE_DIR"
          - npx --yes "@arnica-io/[email protected]"
        artifacts:
          - arnica-scan-summary.md
          - .arnica-scan-outputs.env

Pin the version in the npx argument (@x.y.z). This README is updated with current pins on each release.

Advanced: test scanner from source before npm publish

If you want to validate unreleased changes, clone the scanner source in the pipeline, build it, and run it from source.

image: node:24

pipelines:
  default:
    - step:
        name: Arnica dependency scan (from source)
        script:
          - set -euo pipefail
          - test -n "${ARNICA_API_TOKEN:-}" || (echo "ARNICA_API_TOKEN is required" && exit 1)
          - test -n "${ARNICA_SCAN_REPO_URL:-}" || (echo "ARNICA_SCAN_REPO_URL is required" && exit 1)
          - git clone --depth 1 --branch "${ARNICA_SCAN_REF:-main}" "${ARNICA_SCAN_REPO_URL}" /tmp/dependency-scan-src
          - cd /tmp/dependency-scan-src
          - corepack enable
          - corepack prepare [email protected] --activate
          - pnpm install --frozen-lockfile
          - pnpm run build
          - pnpm run scan
        artifacts:
          - arnica-scan-summary.md
          - .arnica-scan-outputs.env

Required variables for this mode:

• ARNICA_API_TOKEN (secured)
• ARNICA_SCAN_REPO_URL (git URL to your private/public dependency-scan fork)
• ARNICA_SCAN_REF (optional branch/tag/commit; defaults to main)

Outputs and summary

Bitbucket Pipelines does not expose GitHub-style step outputs or Azure ##vso variables. This integration:

• Logs lines ARNICA_OUTPUT <name>=<value> for visibility in the build log.
• Appends name=value lines to .arnica-scan-outputs.env under the clone directory (optional source in a later step, or keep via artifacts).
• Writes arnica-scan-summary.md in the clone directory; list both files under artifacts if you want to download them.

Environment variables are documented once in CLI Environment Variables (All Platforms) above.

Repository URL detection fallback order:

1. BITBUCKET_GIT_HTTP_ORIGIN
2. BITBUCKET_GIT_SSH_ORIGIN
3. BITBUCKET_SERVER_URL (or BITBUCKET_BASE_URL) + BITBUCKET_REPO_FULL_NAME
4. https://bitbucket.org/<BITBUCKET_REPO_FULL_NAME>

Branch detection fallback order:

1. BITBUCKET_BRANCH
2. BITBUCKET_PR_SOURCE_BRANCH
3. BITBUCKET_SOURCE_BRANCH
4. BITBUCKET_BRANCH_NAME

Example: scan a subdirectory, alert only

Add to the same script or export env before npx:

        script:
          - export ARNICA_SCAN_PATH="services/payments"
          - export ARNICA_ON_FINDINGS="alert"
          - cd "$BITBUCKET_CLONE_DIR"
          - npx --yes "@arnica-io/[email protected]"

Where to View Reports (Bitbucket)

1. Build logs: ARNICA_OUTPUT lines and scan progress
2. Artifacts: arnica-scan-summary.md if declared under artifacts
3. Arnica Dashboard: Full vulnerability management at https://app.arnica.io

Troubleshooting (Bitbucket)

• Repository URL is missing
  • Set ARNICA_REPOSITORY_URL explicitly in the step environment.
  • Verify your runner exports one of: BITBUCKET_GIT_HTTP_ORIGIN, BITBUCKET_GIT_SSH_ORIGIN, or (BITBUCKET_SERVER_URL + BITBUCKET_REPO_FULL_NAME).
• Unexpected branch value in PR pipelines
  • PR pipelines may expose multiple branch variables depending on runner type.
  • Set ARNICA_BRANCH explicitly if you need strict source-branch mapping.
• No summary/output artifacts visible
  • Make sure arnica-scan-summary.md and .arnica-scan-outputs.env are listed under artifacts.

GitLab CI

Use the published npm package with npx, same as Azure DevOps and Bitbucket.

• Auto-detects repository URL from CI_REPOSITORY_URL or CI_PROJECT_URL (embedded CI job tokens are stripped automatically).
• Auto-detects branch from CI_COMMIT_BRANCH, CI_MERGE_REQUEST_SOURCE_BRANCH_NAME, or CI_COMMIT_REF_NAME (tag pipelines are handled — CI_COMMIT_REF_NAME is skipped when CI_COMMIT_TAG is set).

You can always override detection with ARNICA_REPOSITORY_URL and ARNICA_BRANCH.

Prerequisites

1. ARNICA_API_TOKEN: Store as a masked CI/CD variable (Settings → CI/CD → Variables).
2. Node.js 24+ on the job image (for example node:24).

Example pipeline

stages:
  - scan

dependency-scan:
  stage: scan
  image: node:24
  script:
    - cd "${CI_PROJECT_DIR}"
    - npx --yes "@arnica-io/[email protected]"
  artifacts:
    paths:
      - arnica-scan-summary.md
      - .arnica-scan-outputs.env
    reports:
      dotenv: .arnica-scan-outputs.env
    when: always
    expire_in: 7 days

Pin the version in the npx argument (@x.y.z). This README is updated with current pins on each release.

Advanced: test scanner from source before npm publish

If you want to validate unreleased changes, clone the scanner source in the pipeline, build it, and run it from source.

stages:
  - scan

dependency-scan:
  stage: scan
  image: node:24
  script:
    - set -euo pipefail
    - test -n "${ARNICA_API_TOKEN:-}" || (echo "ARNICA_API_TOKEN is required" && exit 1)
    - git clone --depth 1 --branch "${ARNICA_SCAN_REF:-main}" "${ARNICA_SCAN_REPO_URL}" /tmp/dependency-scan-src
    - cd /tmp/dependency-scan-src
    - corepack enable
    - corepack prepare [email protected] --activate
    - pnpm install --frozen-lockfile
    - pnpm run build
    - cd "${CI_PROJECT_DIR}"
    - export PATH="/tmp/dependency-scan-src/node_modules/.bin:${PATH}"
    - node /tmp/dependency-scan-src/dist/cli.js
  artifacts:
    paths:
      - arnica-scan-summary.md
      - .arnica-scan-outputs.env
    reports:
      dotenv: .arnica-scan-outputs.env
    when: always
    expire_in: 7 days

Required variables for this mode:

• ARNICA_API_TOKEN (masked)
• ARNICA_SCAN_REPO_URL (git URL to your private/public dependency-scan fork)
• ARNICA_SCAN_REF (optional branch/tag/commit; defaults to main)

Outputs and summary

GitLab CI does not expose GitHub-style step outputs or Azure ##vso variables. This integration:

• Logs lines ARNICA_OUTPUT <name>=<value> for visibility in the job log.
• Appends name=value lines to .arnica-scan-outputs.env under the project directory. Declare it as a dotenv report artifact so downstream jobs can consume the variables.
• Writes arnica-scan-summary.md in the project directory; list it under artifacts: paths to download from the pipeline UI.

Environment variables are documented once in CLI Environment Variables (All Platforms) above.

Repository URL detection fallback order:

1. CI_REPOSITORY_URL (embedded credentials stripped)
2. CI_PROJECT_URL

Branch detection fallback order:

1. CI_COMMIT_BRANCH
2. CI_MERGE_REQUEST_SOURCE_BRANCH_NAME
3. CI_COMMIT_REF_NAME (skipped when CI_COMMIT_TAG is set)
4. CI_DEFAULT_BRANCH (the project's default branch; used automatically in tag pipelines)

Example: scan a subdirectory, alert only

Add a variables block to the job:

  variables:
    ARNICA_SCAN_PATH: "services/payments"
    ARNICA_ON_FINDINGS: "alert"

Where to View Reports (GitLab)

1. Job logs: ARNICA_OUTPUT lines and scan progress
2. Artifacts: arnica-scan-summary.md downloadable from the pipeline UI
3. Downstream variables: .arnica-scan-outputs.env as a dotenv report artifact
4. Arnica Dashboard: Full vulnerability management at https://app.arnica.io

Troubleshooting (GitLab)

• Repository URL is missing
  • Set ARNICA_REPOSITORY_URL explicitly in the job variables.
  • Verify your runner exports CI_REPOSITORY_URL or CI_PROJECT_URL.
• Branch shows tag name instead of branch
  • In tag pipelines, CI_COMMIT_BRANCH is unset and CI_COMMIT_REF_NAME contains the tag. The scanner detects CI_COMMIT_TAG and skips CI_COMMIT_REF_NAME, falling back to CI_DEFAULT_BRANCH (if set by the runner) then main. Set ARNICA_BRANCH explicitly if you need a specific value.
• No summary/output artifacts visible
  • Make sure arnica-scan-summary.md and .arnica-scan-outputs.env are listed under artifacts: paths, and .arnica-scan-outputs.env is declared under artifacts: reports: dotenv.
• Workspace path warning (CI_PROJECT_DIR is unavailable)
  • Ensure the job runs inside a proper GitLab CI runner. Custom Docker executors must export CI_PROJECT_DIR.

Contributing

See CONTRIBUTING.md for development, testing, and release guidance. Please open an Issue first for substantial changes.

Code of Conduct

This project adheres to a Code of Conduct. By participating, you agree to uphold it. See CODE_OF_CONDUCT.md.

License

MIT — see LICENSE.md.

Support

Questions or issues? Open a GitHub Issue. You can also propose enhancements via a feature request Issue or PR.