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

# Semaphore

> Connect Rootly AI to Semaphore CI/CD — pipelines, job logs, and workflow context during incident investigations.

## Overview

Connecting **Semaphore** lets Rootly AI query your CI/CD pipeline history during investigations. When an incident correlates with a recent deploy or a suspicious pipeline change, Rootly AI can pull the pipeline, job logs, and workflow context automatically — no need for a responder to jump between Semaphore and Rootly manually.

Every query is **read-only**. Rootly AI can inspect pipelines and jobs but cannot trigger, cancel, or modify them.

***

## Before You Start

* **A Semaphore account** with permission to create API tokens.
* **A Semaphore API token** with read access to the pipelines and projects you want Rootly AI to see.
* **Your Semaphore organization URL** (e.g., `https://your-org.semaphoreci.com`).

***

## Setup

<Steps>
  <Step title="Open the Semaphore connector card">
    Go to **Configuration → AI → Connectors** and click **Connect** on the **Semaphore** card.
  </Step>

  <Step title="Enter your organization URL">
    Paste your Semaphore organization URL — the base URL you sign in to (e.g., `https://your-org.semaphoreci.com`).
  </Step>

  <Step title="Paste your API token">
    Generate a Semaphore API token from your account settings and paste it into Rootly. Only tokens with read access to pipelines are needed.
  </Step>

  <Step title="Save">
    Rootly runs a quick check to confirm it can reach Semaphore. If the check passes the card flips to **Connected**.
  </Step>
</Steps>

***

## What Rootly AI Can Read

* **Pipelines** — pipeline runs, status, timing, associated commits and branches.
* **Jobs** — job status, exit codes, timing per step.
* **Job logs** — log output for individual jobs, useful when a build failure precedes an incident.
* **Workflows** — workflow structure and the projects they belong to.

<Tip>
  Rootly AI reaches for CI/CD data when a question is about *"what changed?"* or *"did the deploy fail?"* If your incident isn't deploy-related, the Semaphore connector may not come up in the investigation — that's expected.
</Tip>

***

## Best Practices

* **Scope the token to read-only.** Rootly AI never needs to write to Semaphore. Use the narrowest-permission token that covers the pipelines you care about.
* **Rotate the token on a cadence.** Rotate on the same schedule as your other CI credentials (quarterly is common). After rotating, paste the new token into Rootly's Configure screen.
* **Pair with GitHub.** Semaphore tells you the pipeline result; GitHub tells you what changed in the code. The two together give Rootly AI the strongest "what caused this?" signal.

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Save fails with 'unable to authenticate'" icon="key">
    The API token is invalid, expired, or lacks permission. Regenerate it in Semaphore, confirm it can read pipelines using the Semaphore API directly, then paste the new token into Rootly.
  </Accordion>

  <Accordion title="Card shows Connected but Rootly AI can't find recent pipelines" icon="magnifying-glass">
    The token's scope is too narrow. Confirm it can read the projects containing the pipelines you're asking about. Semaphore tokens can be restricted to specific projects or organizations.
  </Accordion>

  <Accordion title="Job logs are missing from Rootly AI's citations" icon="scroll">
    Semaphore retains job logs for a limited window; older logs may have been purged upstream. Rootly AI can only read what Semaphore still stores.
  </Accordion>
</AccordionGroup>

***

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Does Rootly AI trigger or cancel Semaphore pipelines?" icon="lock">
    No. Every connector is read-only. Rootly AI can read pipeline data but never invoke pipeline actions.
  </Accordion>

  <Accordion title="Can I limit which projects Rootly AI sees?" icon="filter">
    Yes — through the Semaphore API token's own scope. Create a token that only grants access to the projects you want Rootly AI to be able to reach.
  </Accordion>

  <Accordion title="Does Rootly cache pipeline data?" icon="floppy-disk">
    No. Rootly AI queries Semaphore at investigation time; nothing is persistently cached.
  </Accordion>
</AccordionGroup>

***

## Related Pages

<CardGroup cols={3}>
  <Card title="Connectors Overview" icon="sparkles" href="/ai/connectors/overview">
    All connectors and how they fit together.
  </Card>

  <Card title="GitHub" href="/ai/connectors/overview#one-click-providers" icon="github">
    Pair Semaphore with GitHub for the strongest "what changed?" signal.
  </Card>

  <Card title="Data Privacy for Rootly AI" icon="shield" href="/ai/data-privacy-for-rootly-ai">
    What Rootly AI sees, retention, and model training controls.
  </Card>
</CardGroup>