OSC CLI in CI Pipelines

This guide covers using the OSC CLI (@osaas/cli) inside automated CI/CD environments such as GitHub Actions. It documents the authentication model, environment selection, workspace scoping, and the full set of available subcommands. All facts were verified against @osaas/cli v4.33.1 on 2026-09-01.

If you are new to the CLI and want a general introduction, start with the OSC CLI user guide. This guide is focused specifically on non-interactive use in pipelines.

Installation

Install a pinned version in your pipeline to keep behavior predictable:

npm install -g @osaas/cli@4.33.1

If you prefer to avoid a global install, you can run commands via npx without installing:

npx @osaas/cli@4.33.1 list eyevinn-test-adserver

CI Authentication

The CLI supports two separate authentication tokens, each scoped to a different command set.

Personal Access Token (OSC_ACCESS_TOKEN)

All user-facing commands require a Personal Access Token (PAT). This covers everything you would normally do as a workspace member: creating and removing service instances, managing My Apps, reading logs, and so on.

export OSC_ACCESS_TOKEN=<your-pat>

You obtain a PAT from Settings / API in the OSC web console. In a GitHub Actions workflow, store it as a repository secret (OSC_PAT) and expose it to the step:

env:
  OSC_ACCESS_TOKEN: ${{ secrets.OSC_PAT }}

No interactive login is required. Exporting this variable is the only setup step needed before running any osc command in a pipeline.

Admin API Key (OSC_API_KEY)

A separate key is required for osc admin sync-fork and other admin-only subcommands. It is not interchangeable with OSC_ACCESS_TOKEN. Standard workspace users do not need this key.

export OSC_API_KEY=<your-admin-key>

Environment Selection

The CLI targets the production environment by default. To target a different environment, set the ENVIRONMENT variable or pass the --env flag.

# Using env var (applies to all commands in the session)
export ENVIRONMENT=dev
osc list eyevinn-test-adserver

# Using flag (per-command override)
osc --env dev list eyevinn-test-adserver

The ENVIRONMENT variable name is exact: it must be spelled ENVIRONMENT, not OSC_ENV. Omitting it is equivalent to ENVIRONMENT=prod.

Workspace and Tenant Selection

The workspace (tenant) is determined entirely by the PAT token itself. There is no separate flag or variable for switching workspaces. The token you export as OSC_ACCESS_TOKEN scopes every command to the workspace that token belongs to. If you manage multiple workspaces, use a different PAT for each.

My Apps Subcommands

My Apps are custom applications deployed from a git repository. The osc myapp group manages them.

List My Apps

osc myapp list

Returns all My Apps in the current workspace.

Create a My App

osc myapp create <name> <type> <gitHubUrl>

By default, the command blocks until the deployment is ready (up to five minutes). Use --no-wait to return immediately without blocking:

osc myapp create myservice web-runner https://github.com/myorg/myrepo --no-wait

The --no-wait flag is useful when downstream steps do not immediately depend on the app being ready, or when you want to trigger the create and poll separately.

Describe a My App

osc myapp describe <appId>

Returns the current state, URL, and configuration of the named app.

Remove a My App

osc myapp remove <appId>

Prompts for confirmation interactively. To suppress the prompt in a pipeline, pass -y:

osc myapp remove myservice -y

Restart: not available for My Apps

There is no osc myapp restart subcommand. If you need to restart a My App, you can remove and recreate it, or trigger a redeploy from the web console. Do not rely on a restart command in pipelines targeting My Apps.

Service Instance Subcommands

Service instances are running deployments of catalog services (for example, a MariaDB database or a test ad server). These commands use the service's ID from the OSC catalog.

List instances

osc list <serviceId>

Example:

osc list linuxserver-docker-mariadb

Create an instance

osc create <serviceId> <name> [-o key=val ...]

Pass configuration options with -o. Each option is a key-value pair specific to the service schema.

osc create linuxserver-docker-mariadb mydb -o RootPassword=hunter2

The command blocks until the instance is running.

Describe an instance

osc describe <serviceId> <name>

Returns the instance URL and all configuration fields.

osc describe linuxserver-docker-mariadb mydb

Restart an instance

osc restart <serviceId> <name>

Restarts a running service instance. Note that osc restart applies to catalog service instances, not to My Apps (see above).

Remove an instance

osc remove <serviceId> <name>

Prompts for confirmation. Use -y to skip the prompt in a pipeline.

Get logs

osc logs <serviceId> <name>

Retrieves recent log output from the running instance.

Admin: Sync Fork

The osc admin sync-fork command re-syncs the OSC-managed fork of a service repository and rebuilds its image. It requires OSC_API_KEY, not OSC_ACCESS_TOKEN.

export OSC_API_KEY=<admin-key>
osc admin sync-fork <serviceId>

By default, the command returns immediately after submitting the sync request. Pass -w (or --wait) to block until the sync is complete. The flag polls at a five-second interval:

osc admin sync-fork eyevinn-test-adserver -w

Use -w in pipelines where subsequent steps depend on the updated image being available.

Async Polling Patterns

Some commands are synchronous by default (they block until the operation finishes) and some are fire-and-forget by default. The table below summarizes the behavior:

Command	Default behavior	Override
osc myapp create	Blocks up to 5 min	--no-wait to return immediately
osc create	Blocks until running	No override
osc admin sync-fork	Returns immediately	-w to block until complete

When you need the output of one step (for example, the instance URL from osc describe) before proceeding, use the blocking form. When triggering a create in parallel with other pipeline steps, --no-wait avoids holding up the runner.

Full GitHub Actions Example

The following workflow shows a complete, working pattern for using the OSC CLI in a GitHub Actions pipeline. It creates a service instance, retrieves its URL, runs a test against it, and removes the instance on completion.

name: Integration test

on:
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Set up Node
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install OSC CLI
        run: npm install -g @osaas/cli@4.33.1

      - name: Create test service instance
        env:
          OSC_ACCESS_TOKEN: ${{ secrets.OSC_PAT }}
          ENVIRONMENT: dev
        run: |
          osc create eyevinn-test-adserver ci-adserver

      - name: Get instance URL
        id: describe
        env:
          OSC_ACCESS_TOKEN: ${{ secrets.OSC_PAT }}
          ENVIRONMENT: dev
        run: |
          url=$(osc describe eyevinn-test-adserver ci-adserver | grep '^url:' | awk '{print $2}')
          echo "instance_url=$url" >> "$GITHUB_OUTPUT"

      - name: Run integration tests
        env:
          SERVICE_URL: ${{ steps.describe.outputs.instance_url }}
        run: npm test

      - name: Remove test instance
        if: always()
        env:
          OSC_ACCESS_TOKEN: ${{ secrets.OSC_PAT }}
          ENVIRONMENT: dev
        run: |
          osc remove eyevinn-test-adserver ci-adserver -y

The if: always() condition on the removal step ensures the instance is cleaned up even when earlier steps fail.

Common Traps

Using OSC_API_KEY for regular commands. OSC_API_KEY only works for osc admin commands. For everything else, the variable is ignored. If your commands fail with an authentication error, check that OSC_ACCESS_TOKEN is set.

Calling osc myapp restart. This subcommand does not exist. Automation that calls it will fail with an unknown command error. Use the web console or remove-then-recreate the app instead.

Spelling ENVIRONMENT as OSC_ENV. The variable OSC_ENV is not recognized by the CLI. The correct variable is ENVIRONMENT. Commands will silently target production if the variable is misspelled.

Forgetting -y on remove. The osc remove and osc myapp remove commands prompt for confirmation when run interactively. In a pipeline there is no TTY to answer the prompt, so the command will stall. Always pass -y in automated contexts.

Triggering prod deploy to the wrong workspace. The workspace is determined by the PAT. If you use the same step for multiple environments or workspaces, verify that the correct secret is bound to OSC_ACCESS_TOKEN for each job. Accidentally using a production PAT in a dev pipeline step will create or remove real production resources.

Running osc admin sync-fork without -w when subsequent steps need the updated image. The command returns after submitting the request, not after the build finishes. If a downstream step creates an instance that depends on the freshly built image, add -w to the sync step.