CI/CD integration¶

Integrating ONEKEY into your development lifecycle let's you automatically analyze firmware as part of your continuous integration and deployment processes. By incorporating firmware analysis into your CI/CD pipelines, you can:

Automatically test builds and identify security issues early.
Detect and report security regressions before deployment.
Enforce security policies and compliance requirements.
Generate security reports as part of your build artifacts.
Block deployments with critical security vulnerabilities.

There are many ways to integrate ONEKEY depending on your use cases, processes, and requirements. This guide covers recommended approaches and best practices.

Prerequisites¶

Installation¶

Install the ONEKEY Python client in your CI/CD environment:

pip install onekey-client

For comprehensive client documentation and command details, see ONEKEY Python client.

Authentication¶

Provide credentials via API tokens:

export ONEKEY_TOKEN="your-api-token"
export ONEKEY_TENANT_NAME="your-tenant"

Secure credential storage

Never hardcode credentials in pipeline configuration files or commit them to version control. Use your CI/CD platform's secret management features (e.g., GitLab CI/CD variables, GitHub Secrets, Jenkins credentials).

CI/CD workflow¶

A typical CI/CD integration follows this pattern:

Build firmware - Compile your firmware as part of the build stage.
Upload firmware - Use onekey upload-firmware to upload the firmware binary.
Wait for analysis and check results - Use onekey ci-result to poll analysis status, compare with previous firmware, and fail the build if new issues are found.
Generate reports - Create JUnit XML reports for CI/CD integration.

Basic example

#!/bin/bash
set -e

# Upload firmware
FIRMWARE_ID=$(onekey upload-firmware \
  --product "MyDevice" \
  --vendor "MyCompany" \
  --version "1.0" \
  firmware.bin)

echo "Uploaded firmware: $FIRMWARE_ID"

# Wait for analysis and check results
onekey ci-result \
  --firmware-id "$FIRMWARE_ID" \
  --junit-path ./test-results/security.xml \
  --exit-code-on-new-finding 1

echo "Analysis passed - no new security findings"

The onekey ci-result command automatically:

Polls firmware analysis status until completion.
Locates the previous firmware for comparison.
Reports new and resolved security issues.
Generates JUnit XML reports for CI/CD integration.
Exits with configurable status code on new findings.

Best practices¶

Version identification¶

Use meaningful version identifiers that link back to your build system:

# Git commit SHA
--version "$CI_COMMIT_SHA"

# Semantic version + build number
--version "1.2.3-build${BUILD_NUMBER}"

# Branch + timestamp
--version "main-$(date +%Y%m%d-%H%M%S)"

# Tag name for releases
--version "$CI_COMMIT_TAG"

Conditional analysis¶

Run analysis only on specific branches or events:

# GitLab - only on main and MRs
only:
  - main
  - merge_requests

# GitHub - only on push to main and PRs
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

Parallel builds¶

If you build multiple firmware variants, analyze them in parallel:

security-analysis:
  stage: security
  parallel:
    matrix:
      - VARIANT: [standard, debug, minimal]
  script:
    - |
      onekey upload-firmware \
        --product "MyProduct-${VARIANT}" \
        --vendor "MyCompany" \
        --version "$CI_COMMIT_SHA" \
        "build/firmware-${VARIANT}.bin"

Failure policies¶

Decide when to fail the build:

# Fail on any new findings (strict)
--exit-code-on-new-finding 1

# Never fail, just report (informational)
--exit-code-on-new-finding 0

For custom policies (e.g., fail only on high severity), use the GraphQL API directly. See REST and GraphQL APIs for advanced use cases.

Timeout configuration¶

Adjust timeouts based on firmware size and analysis complexity:

# Large firmware or comprehensive analysis
onekey ci-result \
  --firmware-id "$FIRMWARE_ID" \
  --check-interval 120 \
  --retry-count 30

# Quick analysis for small firmware
onekey ci-result \
  --firmware-id "$FIRMWARE_ID" \
  --check-interval 30 \
  --retry-count 10

Single job vs. separate jobs¶

Decide whether to run single or separate jobs.

Single job

Pros:
- Simpler to implement
- No need to pass firmware ID between jobs
Cons:
- Longer overall job execution time
- Single point of failure
Separate jobs

Pros:
- Better parallelization and resource utilization
- Allows upload to complete quickly while analysis runs
- More granular error handling and retry logic
Cons:
- Requires passing firmware ID between jobs
- Harder to implement

Typically, a single job is easier to implement as it avoids the need to pass the firmware ID between jobs. However, for better granularity, error handling, and resource efficiency, separate jobs are recommended.

Troubleshooting¶

Authentication failures¶

Symptom: 401 Unauthorized errors

Solutions:

Verify credentials are correctly set in CI/CD secrets.
Check that environment variable names match exactly (ONEKEY_EMAIL, not ONEKEY_USER).
Ensure password doesn't contain special characters that need escaping.
Verify tenant name is correct.

Upload failures¶

Symptom: Upload fails or times out

Solutions:

Check firmware file size and network bandwidth.
Verify you have Upload permission on the product group.
Ensure firmware file path is correct and readable.
Check CI/CD runner has internet access to ONEKEY API.
Increase timeout values if uploading large files.

Analysis timeout¶

Symptom: ci-result command times out waiting for analysis

Solutions:

Increase --check-interval and --retry-count values.
Check analysis status on ONEKEY web interface.
Verify firmware was uploaded successfully.
Contact support if analysis is stuck in pending state.

Missing previous firmware¶

Symptom: No comparison performed, only current results shown

Solutions:

Ensure consistent product name across uploads.
Verify at least one previous firmware exists for the product.
Check that previous upload completed successfully.
Use web interface to verify product contains multiple firmwares.

JUnit report issues¶

Symptom: JUnit report not generated or not recognized by CI/CD

Solutions:

Verify --junit-path directory exists or create it first.
Use relative paths from job working directory.
Ensure CI/CD job artifacts configuration includes the report path.
Check file permissions allow writing to the specified path.