CI/CD Integration

Skylos fits into CI in three different ways. The right choice depends on whether you want local-only exit codes, cloud-managed policy, or GitHub-native hard enforcement.

Choose a CI Mode

Goal	Use this	Notes
Local-only CI gate	`skylos . --gate`	No cloud state required
Workflow security review	`skylos . --danger`	Scans `.github/workflows/*` and local action metadata
Cloud upload with dashboard policy	`skylos . --upload`	Uses project policy, suppressions, and cloud history
GitHub hard enforcement	`skylos . --upload` plus GitHub App and branch protection	Requires repo URL and cloud setup

GitHub Actions Workflow Security

skylos . --danger also scans GitHub Actions workflows and local action metadata. It flags CI/CD supply-chain risks such as privileged triggers, broad GITHUB_TOKEN permissions, unpinned actions, unsafe checkout credentials, template injection, secret overexposure, mutable containers, OIDC release risk, and missing timeouts on privileged jobs.

See GitHub Actions Security for setup guidance and the full scanner scope.

This workflow-configuration scanner is GitHub Actions-specific. GitLab CI, CircleCI, Jenkins, and other providers can still run Skylos as a CLI gate, but Skylos does not currently parse their CI configuration files for provider-level misconfiguration rules.

GitHub Actions with OIDC

OIDC is the cleanest GitHub Actions path because it avoids long-lived secrets.

Preconditions:

the Skylos project has a unique GitHub repo_url
the workflow has id-token: write

name: Skylos Quality Gate

on:
  pull_request:
    branches: [main, master]

permissions:
  contents: read
  id-token: write

jobs:
  skylos:
    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 --quality --upload

How OIDC works:

GitHub Actions issues a short-lived OIDC token
Skylos verifies it
Skylos resolves the target project by matching the workflow repository to the project's repo_url
the upload proceeds with no SKYLOS_TOKEN

OIDC failure modes

OIDC upload fails when:

no project has the matching repo URL
more than one project has the same repo URL
the workflow is missing id-token: write

GitHub Actions with `SKYLOS_TOKEN`

Use this when you want explicit secret management or are not ready to rely on OIDC.

name: Skylos Quality Gate

on:
  pull_request:
    branches: [main, master]

jobs:
  skylos:
    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
      - name: Run Skylos
        env:
          SKYLOS_TOKEN: ${{ secrets.SKYLOS_TOKEN }}
        run: skylos . --danger --quality --upload

Use SKYLOS_TOKEN for:

GitHub without OIDC
skylos sync pull in CI
fallback while migrating to OIDC

Advisory Quality Checks

When adopting standards-backed quality checks in an existing repository, run them as advisory first. The workflow should warn, annotate, and write a summary, but return exit code 0 until legacy findings are under control.

Recommended advisory bundle:

Ruff for Python lint policy
mypy or pyright for Python type-check policy
TypeScript compile/build scripts for packages with tsconfig.json
Rustfmt and Clippy for Rust crates
diff-aware Skylos scans using --diff-base and --diff

- name: Skylos advisory scan
  run: skylos . --danger --secrets --quality --diff-base origin/main --diff origin/main --json -o skylos-results.json

- name: Advisory quality summary
  if: always()
  run: skylos cicd gate --input skylos-results.json --summary --advisory

Use a hard gate later, after findings are diff-aware, baseline-aware, or low enough to enforce.

Pulling Policy in CI

If you want the CI runner to use the latest dashboard-managed thresholds and suppressions locally before the scan, add:

- name: Pull Skylos policy
  env:
    SKYLOS_TOKEN: ${{ secrets.SKYLOS_TOKEN }}
  run: skylos sync pull

That writes .skylos/config.yaml and .skylos/suppressions.json in the checkout.

Generated Workflow Helpers

`skylos cicd init`

Use skylos cicd init when you want Skylos to scaffold a workflow file.

Examples:

skylos cicd init
skylos cicd init --upload
skylos cicd init --defend
skylos cicd init --defend --upload

Important behavior today:

skylos cicd init --upload generates a token-based workflow
it does not generate an OIDC workflow for you

`skylos sync setup`

skylos sync setup is a token-driven scaffolding helper for optional hooks and workflow files.

Current behavior:

it asks for a token
it can scaffold pre-push hooks, pre-commit config, and a GitHub Actions workflow
its generated upload workflow expects SKYLOS_TOKEN
it is not the browser-based OIDC setup path

GitHub App Enforcement

The GitHub App is the GitHub-native enforcement layer.

Recommended order:

get uploads working first
save the exact GitHub repo URL on the project
install the GitHub App from Dashboard -> Settings
add branch protection that requires the Skylos status check

The project settings surface also includes an auto-configure toggle that can allow Skylos to update branch protection and open a workflow PR after install. That is a workspace-level GitHub automation choice, not a requirement for basic uploads.

Other CI Providers

GitLab CI

skylos:
  image: python:3.11
  script:
    - pip install skylos
    - skylos . --danger --quality --upload
  variables:
    SKYLOS_TOKEN: $SKYLOS_TOKEN

CircleCI

- run:
    name: Skylos Scan
    command: skylos . --danger --quality --upload
    environment:
      SKYLOS_TOKEN: $SKYLOS_TOKEN

Jenkins

stage('Skylos Scan') {
  environment {
    SKYLOS_TOKEN = credentials('skylos-token')
  }
  steps {
    sh 'pip install skylos'
    sh 'skylos . --danger --quality --upload'
  }
}

Local Gate vs Cloud Gate in CI

Local gate

skylos . --gate

Use this when you only want CLI exit codes from local config.

Cloud gate

skylos . --upload

Use this when you want the cloud project to evaluate:

dashboard policy
suppressions
baseline history
strict mode
AI assurance
PR-diff-aware new issue detection when available

Troubleshooting

OIDC upload says the repo is not linked

Set the exact GitHub repo URL on the Skylos project.

OIDC upload says the repo binding is ambiguous

Make sure only one project has that repo URL.

`skylos sync pull` fails in CI

sync pull needs SKYLOS_TOKEN. It does not use GitHub OIDC.

The workflow generated by `sync setup` still wants a token

That is expected today. sync setup and generated upload workflows are token-based helpers.

Upload works but there is no GitHub-native PR status

Basic upload is not the same thing as GitHub App enforcement. Save the repo URL, install the GitHub App, and configure branch protection.

Choose a CI Mode​

GitHub Actions Workflow Security​

GitHub Actions with OIDC​

OIDC failure modes​

GitHub Actions with SKYLOS_TOKEN​

Advisory Quality Checks​

Pulling Policy in CI​

Generated Workflow Helpers​

skylos cicd init​

skylos sync setup​

GitHub App Enforcement​

Other CI Providers​

GitLab CI​

CircleCI​

Jenkins​

Local Gate vs Cloud Gate in CI​

Local gate​

Cloud gate​

Troubleshooting​

OIDC upload says the repo is not linked​

OIDC upload says the repo binding is ambiguous​

skylos sync pull fails in CI​

The workflow generated by sync setup still wants a token​

Upload works but there is no GitHub-native PR status​

Related Docs​