User Guide Overview

This guide explains how to deploy cicd-sensor into CI/CD pipelines and use it for runtime detection, recording, and verification.

The first decision is the runner environment you want to protect.

What to read

Usage models

GitHub-hosted runner

On GitHub-hosted runners, add cicd-sensor/cicd-sensor-action to the workflow. The agent starts inside the job and observes runtime activity from the following steps.

flowchart LR
    JOB["GitHub Actions Job"]
    ACTION["cicd-sensor Action"]
    AGENT["cicd-sensor Agent"]
    ARTIFACTS["Job artifacts<br/>Graphical report / Attestation"]

    JOB --> ACTION --> AGENT --> ARTIFACTS

    classDef cicdSensor fill:#ecfdf5,stroke:#0f766e,color:#134e4a,stroke-width:1.5px;
    class ACTION,AGENT cicdSensor

When a manager is configured, GitHub-hosted runners can also deliver Summary Logs, Detection Logs, and Runtime Event Logs to cloud-side outputs. The job can still produce report and attestation artifacts.

Self-hosted runner with Manager

For Self-hosted Machine Runners and GitLab Runner fleets, install the cicd-sensor Agent and Docker proxy on the runner host, then use the manager for config, rules, and log delivery.

flowchart LR
    AGENT["cicd-sensor Agent"]
    MANAGER["cicd-sensor-manager"]
    CLOUD["Cloud Outputs<br/>S3 / GCS / Pub/Sub"]
    SIEM["SIEM"]

    MANAGER -->|"Config / Rules"| AGENT
    AGENT -->|"Summary / Detection / Runtime Event Logs"| MANAGER
    MANAGER -->|"Store / Stream"| CLOUD
    CLOUD --> SIEM

    classDef cicdSensor fill:#ecfdf5,stroke:#0f766e,color:#134e4a,stroke-width:1.5px;
    class AGENT,MANAGER cicdSensor

In self-hosted deployments, config and rules come from the manager, not from the local repository.

Platform support

GitLab-hosted runners are not supported today because cicd-sensor cannot install the Agent on the runner host.