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

Linking saves the project and credentials for future uploads. A plain skylos . scan does not upload; add --upload to send its report to Cloud.

skylos .
skylos . --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 authenticates default-branch uploads without a stored API key. Generate the full PR gate and upload workflow with skylos cicd init; see CI/CD Integration.

The generated onboarding workflow described here requires Skylos 4.46.0 or newer. Skylos 4.45.0 has the older workflow generator.

Preconditions:

  1. your Skylos project is bound to the GitHub repository
  2. the Skylos GitHub App is installed on that repository
  3. only the upload job has id-token: write

This upload-only example assumes one Cloud project for the repository and a default branch named main. Replace the branch name as needed. For multiple monorepo projects, use the App's per-root workflow described below.

name: Skylos Cloud upload

on:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  cloud-upload:
    if: github.event_name == 'push' && github.ref == format('refs/heads/{0}', github.event.repository.default_branch)
    runs-on: ubuntu-latest
    timeout-minutes: 15
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
        with:
          fetch-depth: 0
          persist-credentials: false
      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
        with:
          python-version: '3.12'
      - run: python -I -m pip install "skylos>=4.46.0"
      - run: skylos sync pull
      - run: skylos . --danger --secrets --quality --ai-defects --upload
        env:
          SKYLOS_COMMIT: ${{ github.sha }}
          SKYLOS_BRANCH: ${{ github.ref_name }}

Ordinary pull_request jobs scan code and run tests without OIDC or stored Cloud credentials. Adding id-token: write to one does not make its upload trusted. The GitHub App has a separate PR workflow that isolates scanning from its trusted policy and publishing jobs; use the App's generated workflow for Cloud-verified PR checks.

How it works:

  1. GitHub Actions issues a short-lived OIDC token
  2. Skylos verifies the token against GitHub's OIDC issuer
  3. Cloud verifies the repository identity and GitHub App binding, then resolves the project, using the project subpath when supplied
  4. the scan uploads with no SKYLOS_TOKEN secret

Important repo-binding rule​

OIDC requires a unique project for the verified repository and the supplied project subpath. A monorepo can have projects such as apps/api and apps/web; Cloud's generated App workflow sends each root separately.

If no project matches, upload fails. If multiple projects still match after subpath routing, or the request omits a subpath and matches several projects, Cloud rejects the ambiguous binding.

The CLI-generated workflow's --scan-path changes the scan directory, but its skylos sync pull step does not send a GitHub project-subpath header. Use the App's per-root workflow for Cloud policy sync in a monorepo with multiple projects.

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, the GitHub App installation, and the event. An ordinary upload job must run on a push to the default branch. Cloud also accepts its own isolated PR publishing workflow; an arbitrary pull_request job is not that workflow.

OIDC says the repo is ambiguous​

Check that the request identifies the intended project subpath and that only one project matches that repository and subpath. For monorepos, use the App-generated per-root workflow; --scan-path alone does not route CLI policy sync.

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