CI Integration

Push code graphs from GitHub Actions, GitLab CI, or Jenkins

Run the code graph push on every merge to the default branch. The extractor is fast (seconds, even on large repos), the push is skipped when nothing changed, and every integration below is fail-open — a graph problem must never break a build.

Getting a token

CI authenticates with a dstl8_ API token:

1. In the portal, go to Org Settings → API Tokens and create a token (it's shown once — store it immediately in your CI secret store).

2. Or mint a service token via the API (org admin required):

curl -fsS -X POST "https://acme.app.dstl8.ai/api/tokens/service" \
  -H "Authorization: Bearer <your-access-token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"GitHub Actions CI","service_name":"github-actions","role":"user","expires_in":"365d","scopes":["*"]}'

The same token works for the events action — one secret covers both integrations.

Two rules apply everywhere:

• Default branch only. The server tracks one lineage per repo. Pushes from other branches are reported as a skip and exit 0, so a mis-wired trigger warns instead of failing.

• Add a weekly cron. Snapshot retention follows your log-data retention; a scheduled push keeps low-traffic repos inside the window. When nothing changed it's nearly free — the client skips the upload if the server copy is fresh, and the server just renews an aging identical snapshot.

GitHub Actions

The dstl8-codegraph action installs a pinned CLI release (checksum-verified against the release's SHA256SUMS) and runs dstl8 graph push.

# .github/workflows/codegraph.yml
name: dstl8 code graph
on:
  push:
    branches: [main]        # default branch only — the server rejects others
  schedule:
    - cron: "17 6 * * 1"    # weekly refresh keeps low-traffic repos current
jobs:
  codegraph:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 50    # enough history to diff against the last push
      - uses: control-theory/dstl8/.github/actions/dstl8-codegraph@main
        with:
          api-url: ${{ vars.DSTL8_EVENT_API_URL }}   # e.g. https://acme.app.dstl8.ai
          token: ${{ secrets.DSTL8_EVENT_TOKEN }}

Inputs:

Input	Required	Default	Description
api-url	yes		Org API base URL (e.g. https://acme.app.dstl8.ai)
token	yes		dstl8_ API token
version	no	latest	dstl8 CLI version to pin (e.g. v1.9.0); latest resolves the newest release
path	no	.	Directory to extract (for monorepos where the graph root isn't the repo root)
extra-args	no		Extra arguments appended to dstl8 graph push (e.g. --exclude 'gen/**' or --service checkout='cmd/checkout/**')

Fail-open semantics: every failure mode — unsupported runner architecture, CLI download failure, checksum mismatch, push error — emits a ::warning:: annotation and exits 0. The calling job always succeeds. Check the workflow's annotations if graphs stop arriving.

Checkout depth: fetch-depth: 0 is not required. The diff against the previously pushed snapshot needs that snapshot's commit to exist locally, so fetch-depth: 50 covers typical push cadence. A too-shallow clone degrades gracefully — the snapshot pushes without a diff.

Pair it with a deploy marker: dstl8-codegraph on merge to main tells Dstl8 what the code looks like; a deploy event with the commit SHA at deploy time tells it when that code shipped. Together they give Möbius the full what-changed picture.

GitLab CI

Plain CLI + env auth. allow_failure: true gives you the fail-open behavior; GIT_DEPTH: "50" covers the diff.

# .gitlab-ci.yml
dstl8-codegraph:
  stage: build
  allow_failure: true
  rules:
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
  variables:
    GIT_DEPTH: "50"
  script:
    - curl -fsSL https://install.dstl8.ai/script/dstl8-cli | sh
    - dstl8 graph push --json

Set DSTL8_API_TOKEN (masked) and DSTL8_API_URL as CI/CD variables — the CLI authenticates from the environment alone, no profile or login step. Add a scheduled pipeline on the default branch for the weekly refresh.

Jenkins

stage('dstl8 code graph') {
  when { branch 'main' }
  environment {
    DSTL8_API_TOKEN = credentials('dstl8-api-token')
    DSTL8_API_URL   = 'https://acme.app.dstl8.ai'
  }
  steps {
    // fail-open: never break the build over a graph push
    sh 'curl -fsSL https://install.dstl8.ai/script/dstl8-cli | sh && dstl8 graph push --json || true'
  }
}

Any other CI

The whole integration is one authenticated command from the repo checkout:

DSTL8_API_TOKEN="dstl8_…" DSTL8_API_URL="https://acme.app.dstl8.ai" dstl8 graph push --json

Gate it to the default branch, tolerate failure, and prefer a checkout with ~50 commits of history. In checkouts without a usable .git (source exports), pass the identity flags — see gitless environments in the CLI reference.