Skip to main content

ORT Server Client CLI (osc)

The ORT Server Client CLI (osc) is a command-line interface designed to interact with the ORT Server. It provides essential functionality for managing ORT runs and retrieving results.

Installation

The latest version of osc can be obtained from the GitHub releases page.

macOS

When using the CLI on macOS, Apple's Gatekeeper restrictions may prevent the application from running. To bypass this, the quarantine attribute from the osc binary needs to be removed. This can be done by running the following command:

xattr -d com.apple.quarantine /path/to/osc

Usage in GitHub Actions

When using osc in a GitHub action, the setup-osc action can be used to install osc and authenticate with an ORT Server instance.

The following example demonstrates how to integrate osc in a GitHub Actions workflow to start an ORT run, retrieve the created reports, and store them as workflow artifacts:

jobs:
run-osc:
runs-on: ubuntu-latest
steps:
- name: Setup OSC
uses: eclipse-apoapsis/setup-osc@main
with:
osc-version: 0.1.0-RC16
base-url: https://ort-server.example.com
token-url: https://auth.example.com/realms/prod/protocol/openid-connect/token
client-id: ort-server-prod
username: user
password: ${{ secrets.ORT_SERVER_PASSWORD }}

- name: Start ORT run
run: |
osc runs start --parameters '{
"revision": "${{ github.head_ref || github.ref_name }}",
"jobConfigs": {
"analyzer": {},
"advisor": {},
"evaluator": {},
"scanner": {},
"reporter": {},
"notifier": {}
}
}'
env:
OSC_REPOSITORY_ID: 42
OSC_RUNS_START_WAIT: true # Block the runner until the ORT Server run is finished.

- name: Download Reports
run: |
osc runs download reports
env:
OSC_DOWNLOAD_REPORTS_FILE_NAMES: 'scan-report-web-app.html'
OSC_DOWNLOAD_REPORTS_OUTPUT_DIR: './reports'

- name: Upload reports
id: upload
uses: actions/upload-artifact@v4
with:
name: reports
path: reports/

All available settings for setup-osc can be found in the Repository of the action.

Usage

Authentication

Most operations require authentication with your ORT Server instance. The following command-line arguments are used for authentication:

osc auth login \
--base-url <ORT_SERVER_URL> \
--token-url <TOKEN_URL> \
--client-id <CLIENT_ID> \
--username <USERNAME> \
--password <PASSWORD>

Basic Operations

Starting an ORT Run

A basic ORT run can be started using:

osc runs start --repository-id <REPOSITORY_ID> --parameters '{
"jobConfigs": {},
"revision": "main"
}'

Monitoring Run Status

To check the status of the previously started run:

osc runs info

Downloading Reports

To retrieve reports from a completed ORT run, execute:

osc runs download reports --file-names scan-report-web-app.html --output-dir /tmp

Environment Variables

For automated environments like CI/CD pipelines, all command-line arguments can be configured using environment variables.
For example, to authenticate:

export OSC_ORT_SERVER_BASE_URL="<ORT_SERVER_URL>"
export OSC_ORT_SERVER_TOKEN_URL="<TOKEN_URL>"
export OSC_ORT_SERVER_CLIENT_ID="<CLIENT_ID>"
export OSC_ORT_SERVER_USERNAME="<USERNAME>"
export OSC_ORT_SERVER_PASSWORD="<PASSWORD>"

osc auth login

Command Documentation

For detailed information about available commands and their options:

osc --help

Each subcommand also provides specific help documentation when invoked with the --help flag.