Skip to main content

Authentication

Skylos Cloud currently has three real auth paths:

Auth pathBest forMain command
Browser loginHumans linking a repo to a projectskylos login
API keyCI, headless systems, explicit manual controlskylos sync connect <token> or SKYLOS_TOKEN=...
GitHub OIDCSecretless GitHub Actions uploadsskylos . --upload with id-token: write

Quick Start​

skylos . --upload

On the first interactive run, Skylos will:

  1. open the browser
  2. let you sign in and choose or create a project
  3. verify the returned token
  4. store the repo link
  5. upload the scan

If you want to connect before running a scan, use:

skylos login

Browser Authentication​

skylos login is the preferred human workflow.

skylos login

What it does:

  1. opens skylos.dev/cli/connect
  2. signs you in with GitHub if needed
  3. lets you select or create a project
  4. verifies the token with /api/sync/whoami
  5. stores the saved credentials and repo link

Files written:

  • ~/.skylos/credentials.json
  • <repo>/.skylos/link.json

After a repo is linked, plain skylos . will auto-enable upload unless you pass --no-upload.

skylos .
skylos . --no-upload

Switching or inspecting the linked project​

Useful commands:

skylos project status
skylos project list
skylos project use
skylos project unlink
skylos sync status

Re-running skylos login opens the chooser again. If you complete the flow with a different project, the repo link is updated. If you close the browser flow, the current project is kept.

Manual API Keys​

Use API keys when you want explicit, non-browser auth.

Get the key from:

  • Dashboard -> Settings -> choose project -> API key

The current UI behavior is:

  • a newly created key is only shown once
  • rotating the key revokes the old one immediately

Save the key to the current repo​

skylos sync connect sk_live_xxx...

Or run without an argument and paste it interactively:

skylos sync connect

Use the key for a single run​

SKYLOS_TOKEN=sk_live_xxx... skylos . --upload

Best use cases for API keys​

  • GitLab, CircleCI, Jenkins, and other non-GitHub CI
  • headless servers
  • scripted uploads
  • temporary override of the repo-linked project

GitHub Actions OIDC​

OIDC is the secretless GitHub Actions path.

Preconditions:

  1. your Skylos project has a unique repo_url that matches the GitHub repository
  2. your workflow has id-token: write
name: Skylos Scan
on: [pull_request]

permissions:
  contents: read
  id-token: write

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: pip install skylos
      - run: skylos . --danger --upload

How it works:

  1. GitHub Actions issues a short-lived OIDC token
  2. Skylos verifies the token against GitHub's OIDC issuer
  3. Skylos resolves the project by matching the GitHub repository claim to the project's repo_url
  4. the scan uploads with no SKYLOS_TOKEN secret

Important repo-binding rule​

OIDC uploads only work when one GitHub repo maps to one Skylos project.

If no project matches the repo URL, upload fails. If multiple projects match the same repo URL, upload also fails.

Token Resolution Order​

The current CLI token lookup order is:

  1. SKYLOS_TOKEN
  2. GitHub Actions OIDC
  3. the current repo link plus ~/.skylos/credentials.json
  4. the legacy default saved token
  5. system keyring fallback

That means SKYLOS_TOKEN is the cleanest way to override the linked project for one run.

Upload Attribution​

Skylos Cloud records upload attribution from the server-side auth path.

Upload pathAttribution source
Browser loginlinked user and project credential
API keyresolved project key identity
GitHub OIDCverified GitHub OIDC claims and matched project binding

If two people upload from different machines to the same project, Skylos does not rely only on a client-supplied name. Cloud records the resolved project, auth path, repo/project-root context, branch, commit metadata, and upload time.

For enterprise security review, see Enterprise Trust.

Headless and Remote Environments​

If browser auth is unavailable, Skylos falls back to manual token entry.

Use one of these:

skylos sync connect

or:

SKYLOS_TOKEN=sk_live_xxx... skylos . --upload

Troubleshooting​

skylos . --upload opens a browser unexpectedly​

The CLI could not find a usable token and is trying to connect interactively.

OIDC fails even though id-token: write is set​

Check the project's repo URL in the dashboard. OIDC resolution depends on that binding.

OIDC says the repo is ambiguous​

More than one project has the same repo_url. Remove the duplicate binding.

A token stopped working​

The key may have been rotated or revoked. Generate a new one in dashboard settings and update your CI secrets.

I need to move this repo to a different cloud project​

skylos project unlink
skylos login