> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sureops.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Adopt: connect your stack

> The 5-step guide to connecting your own infrastructure

This guide walks you through connecting sureops to your real infrastructure. By the end, sureops agents will be watching your services, diagnosing incidents from your telemetry, and proposing code fixes as pull requests in your GitHub repos.

<Note>
  You are in early access. A sureops field engineer is available to help with any step. Click **Need help?** in the onboarding wizard, or message the support channel — response time during business hours is under one hour.
</Note>

## Before you start

Have these ready before beginning:

| Item                                                                          | Why                                                                                                           |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| **Prometheus URL + auth token**, or a **Grafana URL + service account token** | sureops queries your observability data to discover services and diagnose incidents                           |
| **GitHub org admin permissions**                                              | Required for the OAuth installation that lets sureops read repos and open fix PRs                             |
| **Slack workspace admin** (or permission to install apps)                     | Required to create incident war-rooms and post agent updates                                                  |
| **`kube-state-metrics` with pod-label allowlist** (recommended)               | Improves service discovery fidelity — sureops correlates deployments to services via `app.kubernetes.io/name` |
| **OTel collector with `servicegraph` connector** (recommended)                | Generates `traces_service_graph_request_total` so sureops can derive your service call graph                  |

## The five steps

<Steps>
  <Step title="Create your environment">
    The onboarding wizard starts here. An environment is the scope for everything sureops does — telemetry connections, incident history, agent configuration, and alert routing are all tied to one environment.

    1. Go to **Settings → Environments → New environment**
    2. Give it a name that matches your deployment context (e.g., `production`, `staging`)
    3. Click **Create**

    You can create multiple environments under one organization. A common pattern is to start with `staging` or a non-production cluster before connecting `production`.
  </Step>

  <Step title="Connect your observability stack">
    sureops needs access to your observability data to discover services, understand topology, and diagnose incidents.

    **Option A — Prometheus (direct)**

    1. Go to **Settings → Integrations → Prometheus → Connect**
    2. Paste your Prometheus URL and bearer token
    3. Click **Verify** — sureops runs a test query to confirm connectivity
    4. Once verified, click **Sync landscape** to run the initial service discovery

    **Option B — Grafana (proxy)**
    Use this if your Prometheus is not directly internet-reachable. sureops can query through your Grafana instance instead.

    1. Go to **Settings → Integrations → Grafana → Connect**
    2. Paste your Grafana URL and a service account token with `query` permissions
    3. Click **Verify**, then **Sync landscape**

    **What "done" looks like:** Settings → Environment → Landscape shows your service nodes and deployments. The onboarding step ticks complete.

    **Common issues:**

    * `401 Unauthorized` — check that your token has the right scope
    * `Connection timed out` — your Prometheus may not be internet-reachable; switch to the Grafana proxy option
    * `0 services discovered` — enable the `kube-state-metrics` pod-label allowlist (`kubeStateMetrics.metricLabelsAllowlist: [pods=[*]]` in your `kube-prometheus-stack` values) and re-sync
  </Step>

  <Step title="Connect Slack">
    sureops creates a dedicated Slack channel for every incident, posts agent updates there, and routes approval requests to your on-call team.

    1. Go to **Settings → Integrations → Slack → Connect with Slack**
    2. Authorize the sureops Slack app on your workspace
    3. Choose a default channel prefix — sureops creates channels named `#incident-{id}` by default
    4. Optionally configure which Slack user groups to notify for P1 vs. P2 incidents

    **What "done" looks like:** The Slack step in the onboarding wizard ticks complete. When the next incident fires, sureops creates a channel and posts the initial alert context automatically.
  </Step>

  <Step title="Connect GitHub">
    GitHub integration enables two things: sureops reads your `.sureops/` service contract from your repos, and the resolution agent opens draft fix PRs against your services.

    1. Go to **Settings → Integrations → GitHub → Connect with GitHub**
    2. Install the sureops GitHub App on your org — select the repositories you want sureops to have access to
    3. Tag any repo you want sureops to actively watch with the GitHub topic `sureops-managed`

    **What "done" looks like:** Settings → Integrations → GitHub shows "Connected". The GitHub step in the wizard ticks complete.

    **Common issues:**

    * `Installation not found` — you approved the app install on the wrong org. Re-run the install and select the correct org.
    * `No repos with sureops-managed topic` — add the topic to at least one repository and run **Re-sync** in Settings.
  </Step>

  <Step title="Add your .sureops/ service contract">
    The service contract is a YAML file that tells sureops what you know about your services that telemetry alone cannot infer: who owns each service, what tier it is, and where its runbook lives. Agents read this contract before every incident to understand blast radius and who to involve.

    **Auto-generate (recommended for getting started):**

    1. Go to **Settings → Environment → Landscape → Generate starter contract**
    2. sureops reads your observed services, deployments, and GitHub CODEOWNERS, then opens a draft PR against your repo with a pre-filled `.sureops/services.yaml`
    3. Review the PR — check owners, tiers, and runbook paths — and merge

    **Hand-author:**
    Create `.sureops/services.yaml` in the root of your primary repo. The minimal schema per service is:

    ```yaml theme={null}
    services:
      - name: checkout-service
        owner: payments-team
        tier: 1
        runbook: docs/runbooks/checkout-service.md
        dependsOn:
          - payment-service
          - inventory-service
    ```

    **What "done" looks like:** At least one service in Settings → Environment → Landscape shows provenance `Customer contract`.
  </Step>
</Steps>

## After you connect

Once all five steps are complete:

1. **Route your alerts to sureops** — add a webhook receiver in your Alertmanager pointing at the endpoint shown in Settings → Integrations → Alertmanager. When an alert fires, sureops opens an incident automatically.
2. **Trigger a test incident** — scale a non-production service to zero replicas and watch the full lifecycle run.
3. **Review routing and escalation** — configure who receives P1 HITL approval requests in Settings → Routing.

## Trust and data principles

Your raw observability data — logs, traces, and metrics — never leaves your cluster. sureops stores only derived structure: service names, dependency edges, and ownership. Agents pull raw telemetry on demand during an incident and discard it afterward.

Your authored service contract always overrides anything sureops infers from telemetry. If you declare `tier: 1` for a service, that wins over any automatic classification.

## Getting help

If you get stuck:

1. Click **Need help?** in the onboarding wizard — this opens a support thread pre-populated with your environment context
2. Message the shared Slack support channel with your org name, which step you are on, and what you are seeing
3. A sureops field engineer will respond within one business hour during business hours

Early-access onboarding is treated as a co-implementation. We will hop into your environment (with your permission) to help debug anything that is not working.