CI/CD Pipeline Setup

How to configure the signageOS CLI for automated pipelines (GitLab CI, GitHub Actions, and other CI/CD tools) where interactive login is not possible.

Overview

On a local development machine, you authenticate by running sos login, which interactively prompts for your username and password, generates a personal API security token, and stores it in ~/.sosrc.

In a CI/CD pipeline, there is no interactive terminal. Instead, you generate a long-lived API security token ahead of time and provide it to the pipeline via the ~/.sosrc configuration file or environment variables.

Step 1: Generate an API Security Token

Before configuring your pipeline, generate a personal API security token:

1. Log in to signageOS Box
2. Navigate to Settings → Profile → API Tokens
3. Create a new token (account-wide or organization-scoped, depending on your needs)
4. Copy the Token ID (identification) and Token secret values — you will need both

Step 2: Configure Authentication

You have two options — choose whichever fits your pipeline best.

Option A: Configuration File (~/.sosrc)

Create the ~/.sosrc file in the CI runner's home directory with your credentials in INI format:

apiUrl=https://api.signageos.io
identification=527f75f50ce2f3cxxxxx
apiSecurityToken=7dc58dc275c87283cddf78bc41755cb5f7fxxxxx

The file supports the following fields:

Field	Required	Description
apiUrl	Yes	signageOS API endpoint (typically https://api.signageos.io)
identification	Yes	Token ID from your security token
apiSecurityToken	Yes	The security token secret
defaultOrganizationUid	No	Default organization UID for commands that require one

Security: The CLI writes this file with permissions 0600 (owner read/write only). Make sure your pipeline step preserves these permissions.

Option B: Environment Variables

Instead of writing a file, you can set environment variables that override ~/.sosrc values:

Environment Variable	Overrides
SOS_API_URL	apiUrl
SOS_API_IDENTIFICATION	identification
SOS_API_SECURITY_TOKEN	apiSecurityToken
SOS_ORGANIZATION_UID	defaultOrganizationUid

Environment variables take precedence over the configuration file, so you can combine both approaches (e.g., a base .sosrc with env var overrides for specific jobs).

Pipeline Examples

GitLab CI

Store your credentials as CI/CD variables in your project or group settings (masked and protected).

# .gitlab-ci.yml

variables:
  SOS_API_URL: "https://api.signageos.io"

stages:
  - deploy

deploy-applet:
  stage: deploy
  image: node:20
  before_script:
    - npm install -g @signageos/cli
    # Write ~/.sosrc from CI/CD variables
    - |
      cat > ~/.sosrc <<EOF
      apiUrl=${SOS_API_URL}
      identification=${SOS_API_IDENTIFICATION}
      apiSecurityToken=${SOS_API_SECURITY_TOKEN}
      EOF
    - chmod 600 ~/.sosrc
  script:
    - sos applet upload

Alternatively, using only environment variables (no file needed):

deploy-applet:
  stage: deploy
  image: node:20
  variables:
    SOS_API_URL: "https://api.signageos.io"
    # SOS_API_IDENTIFICATION and SOS_API_SECURITY_TOKEN come from CI/CD settings
  before_script:
    - npm install -g @signageos/cli
  script:
    - sos applet upload

GitHub Actions

Store your credentials as repository secrets.

# .github/workflows/deploy.yml

name: Deploy Applet

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install signageOS CLI
        run: npm install -g @signageos/cli

      - name: Configure signageOS credentials
        run: |
          cat > ~/.sosrc <<EOF
          apiUrl=https://api.signageos.io
          identification=${{ secrets.SOS_API_IDENTIFICATION }}
          apiSecurityToken=${{ secrets.SOS_API_SECURITY_TOKEN }}
          EOF
          chmod 600 ~/.sosrc

      - name: Deploy applet
        run: sos applet upload

Or using environment variables:

      - name: Deploy applet
        env:
          SOS_API_URL: "https://api.signageos.io"
          SOS_API_IDENTIFICATION: ${{ secrets.SOS_API_IDENTIFICATION }}
          SOS_API_SECURITY_TOKEN: ${{ secrets.SOS_API_SECURITY_TOKEN }}
        run: sos applet upload

Using Profiles in CI/CD

If your pipeline needs to operate against multiple signageOS environments (e.g., staging and production), use profiles (see sos login documentation):

[profile staging]
apiUrl=https://api.staging.signageos.io
identification=xxxxxxxxxxxxxxxxxxxx
apiSecurityToken=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

[profile production]
apiUrl=https://api.signageos.io
identification=yyyyyyyyyyyyyyyyyyyy
apiSecurityToken=yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy

Then target a specific profile per job:

# Deploy to staging
sos --profile staging applet upload

# Deploy to production
sos --profile production applet upload

You can also select a profile via the SOS_PROFILE environment variable:

export SOS_PROFILE=production
sos applet upload

Setting a Default Organization

Some CLI commands operate on a specific organization. To avoid interactive prompts in CI/CD, set the default organization:

In ~/.sosrc:

apiUrl=https://api.signageos.io
identification=527f75f50ce2f3cxxxxx
apiSecurityToken=7dc58dc275c87283cddf78bc41755cb5f7fxxxxx
defaultOrganizationUid=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Or via environment variable:

export SOS_ORGANIZATION_UID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Troubleshooting

"Identification or token is missing"

The CLI cannot find valid credentials. Verify that:

• The ~/.sosrc file exists and contains both identification and apiSecurityToken
• Or the SOS_API_IDENTIFICATION and SOS_API_SECURITY_TOKEN environment variables are set
• The token has not expired or been revoked

"No API URL is defined"

The CLI needs an API URL. Ensure either:

• apiUrl is set in ~/.sosrc
• Or SOS_API_URL environment variable is defined

"Your authentication token is outdated"

The identification value does not match the expected format (20-character hex string). Regenerate the token via signageOS Box or re-run sos login on your local machine and copy the new values.

Security Best Practices

• Never commit credentials to your repository. Use CI/CD secret variables or a secrets manager.
• Use masked variables in GitLab CI / GitHub Actions so tokens don't appear in job logs.
• Scope tokens appropriately — prefer organization-scoped tokens when your pipeline only needs access to a single organization.
• Rotate tokens periodically and revoke unused ones via signageOS Box settings.

See Also

• sos login — Interactive authentication for local development
• Global Options — --profile and --api-url flags