Deviera Docs

#Getting Started

#What is Deviera?

Deviera is an engineering intelligence platform that monitors your GitHub and GitLab repositories in real time, detects friction events (CI failures, stale PRs, flaky tests, deployment failures, Sentry alerts, and more), and automatically routes them through configurable automation rules.

The core loop is: event arrives → automation rule evaluates → action executes (create issue, post to Slack, comment on PR) → signal recorded. All signals feed into your Friction Score and intelligence dashboards — giving your team a single, continuous view of engineering health.

#Quick start (5 min)

1. 1Sign up at deviera.dev — free 14-day Pro trial, no credit card required.
2. 2Install the Deviera GitHub App on your organisation (or connect GitLab via OAuth).
3. 3Select the repositories you want Deviera to monitor.
4. 4Connect Linear, Jira, ClickUp, or any combination for automatic issue creation.
5. 5Enable one of the 107 built-in automation presets (e.g. "CI Failure → Linear Issue").
6. 6Trigger a CI failure or open a PR — your first signal appears within seconds.

#Connect GitHub

Deviera uses a GitHub App (not a personal access token) for secure, granular permissions. The app requests read access to code, metadata, checks, pull requests, and issues — plus write access to issues and pull-request comments for write-back actions.

1. 1Go to Dashboard → Integrations → GitHub.
2. 2Click "Install GitHub App". You'll be redirected to GitHub.
3. 3Choose the organisation or personal account, then select which repositories to grant access.
4. 4After installation, return to the dashboard — Deviera begins listening for webhook events immediately.
5. 5Open Dashboard → Integrations → GitHub → Monitored Repositories to select which repos to actively process.

#Your first automation

Navigate to Dashboard → Automations → New. You can build automations in two ways: the Visual Builder (drag-and-drop trigger/action picker) or the Describe It tab (type what you want in plain English and the AI generates the rule for you — Team+).

#GitHub Integration

#GitHub App install

The Deviera GitHub App is installed at the organisation or user level. Once installed, GitHub delivers webhook events to Deviera for every repository you've granted access to. Each installation gets its own webhook secret for HMAC-SHA256 signature verification. You can update repository access at any time from your GitHub App settings page.

#Webhook events

All webhooks are verified using per-installation HMAC-SHA256 signatures before processing. Supported events:

#Monitored repositories

After installing the GitHub App, go to Dashboard → Integrations → GitHub → Monitored Repositories. Check or uncheck repos to control which ones Deviera actively processes. Unchecked repos receive webhooks from GitHub but events are silently discarded — no signals, no automation runs, no billing impact.

#GitHub write-back

All plans support GitHub write-back. Automations can post directly back into GitHub:

• Create a GitHub Issue when CI failure exceeds a streak threshold
• Close a GitHub Issue when CI passes again (auto-resolution)
• Post a comment on a PR when it goes stale or when CI recovers
• Mirror issues from Linear / Jira to GitHub Issues
• Create a GitHub Issue when a Vercel deployment fails

#Automations

#How automations work

An automation is a trigger → condition → action pipeline stored in the database and evaluated every time a matching event arrives. Automations run asynchronously via a BullMQ job queue — webhook responses always return in <50ms regardless of action complexity.

Each event delivered to Deviera is fanned out to every enabled automation in the workspace that matches the trigger type. Conditions are evaluated in order; all must pass for the action to execute. Matching automations run in parallel — a single CI failure can simultaneously create a Linear issue, post to Slack, and open a GitHub issue if you have three separate rules.

#Triggers

Deviera supports 32 trigger types across GitHub, GitLab, Vercel, and Sentry:

#Conditions

Conditions are optional filters applied after a trigger fires. All conditions in a rule must pass for the action to execute.

#Actions

Deviera supports 24 action types. Each automation has a primary action and an optional second action that fires on success.

#Natural Language Builder

On Team+, the automation builder includes a Describe It tab. Type what you want in plain English — for example: "When CI fails on main, create a Linear issue and post to Slack" — and Deviera's AI parses your description and pre-fills the trigger, conditions, and actions. You can then review and save, or edit any field before saving.

#Presets & templates

Deviera ships 107 built-in automation presets organised by destination (Linear, Jira, GitLab Issues, ClickUp, Slack, GitHub write-back, MR comments, Sentry). Access them at Dashboard → Automations → Templates. The For You tab surfaces presets relevant to your connected integrations. Presets can be enabled as-is or cloned and customised.

#Cooldowns & deduplication

Every automation has a configurable cooldown window (default: 60 minutes). If the same automation fires again within the cooldown, the action is skipped and the event is logged as deduplicated. This prevents alert storms from a single flapping CI build.

Cross-provider title deduplication prevents two different automations from creating duplicate issues across Linear, Jira, GitLab, and ClickUp for the same root cause within a 3-day window. The dedup block is automatically lifted when the issue is closed or resolved in the external tracker — so if a problem recurs after being fixed, a fresh ticket is created immediately.

#Conflict detection

When you save a new automation, Deviera checks for conflicts with existing rules that share the same trigger and action type. If a conflict is detected, you are shown the overlapping automation names and can choose to proceed or adjust your rule. This keeps your automation list clean and prevents duplicate actions from different rules.

#Signal Feed

#What is a signal?

A signal is an AutomationEvent record created every time an automation fires. It captures the trigger type, the action taken, the outcome (e.g. Linear issue URL, Slack confirmation), the severity level, minutes saved, and a dedup key for correlation. Signals are the foundation of your Friction Score, Value Dashboard, and all intelligence dashboards.

The Signal Feed at Dashboard → Signals → Signal Feed shows all signals in reverse-chronological order with severity badges, source repo, trigger type, and linked outcomes. You can filter by severity, trigger type, date range, and automation name.

#Severity levels

#Public Signal Wall

The Signal Wall is a public, read-only view of your workspace's recent signal activity. Enable it in Dashboard → Workspace Settings, set a custom slug, and share the URL with stakeholders or embed it in your team wiki — no login required for viewers.

#Value Dashboard

The Value Dashboard at Dashboard → Signals → Value Dashboard aggregates ROI metrics across your automations — total signals, minutes saved, issues created per provider, and trends over time. Use the date range picker and automation filter to drill into specific windows and rules. A bar chart shows which automations generated the most value.

#Friction Score

#How it is computed

The Friction Score is a 0–100 composite metric computed from signal activity in the last 30 days. Lower is better. It gives your team a single number to track engineering health over time.

FrictionScore = (
  (critical_signals × 4)
  + (high_signals × 2)
  + (medium_signals × 1)
) / maxExpected × 100

Signals are weighted by severity — critical×4, high×2, medium×1. Low-severity signals are excluded from the score calculation. The score is capped at 100 and normalised against maxExpected, a dynamic baseline derived from the total signal volume in the window.

#Interpreting your score

#Time-saving baselines

In Dashboard → Workspace Settings → Trigger Baselines you can configure the number of minutes saved per trigger type. These values feed the Value Dashboard's "minutes saved" metric and ROI calculations. Default values are pre-set for every trigger (e.g. CI failure = 8 min, stale PR = 12 min, deployment failure = 10 min) and can be adjusted to match your team's actual context-switching costs.

#Intelligence Dashboards

All intelligence dashboards live under Dashboard → Intelligence. They are powered by the same AutomationEvent data as the Signal Feed — no additional setup required once your integrations are connected.

#CI Intelligence

CI Intelligence (Dashboard → Intelligence → CI Intelligence) provides pattern detection across your CI pipelines — identifying flaky tests, chronically failing workflows, and failure trends per repository and branch. Available on Pro+.

• Per-repo and per-workflow failure rate charts
• Flaky test detection — workflows alternating pass/fail within a window
• Failure streak tracking — how many consecutive runs failed before recovery
• Timeline view of CI events across all monitored repositories

#Repo Health

Repo Health (Dashboard → Intelligence → Repo Health) gives a multi-repo overview of CI health and signal density. Each repository shows its CI pass rate, signal count by severity, and last-seen event. Available on Pro+.

#DORA Metrics

The DORA Metrics dashboard (Dashboard → Intelligence → DORA Metrics) computes the four DORA indicators from your existing event data — no separate instrumentation required:

Each metric is benchmarked against the 2025 State of DevOps report thresholds (Elite / High / Medium / Low). Available on Pro+.

#PR Cycle Time

PR Cycle Time (Dashboard → Intelligence → PR Cycle Time) tracks the median and P75 time from PR open to merge across all monitored repositories. Available on Pro+. Use it to identify whether your bottleneck is review lag, post-approval delay, or PR size.

#Team Flow

Team Flow (Dashboard → Intelligence → Team Flow) tracks PR review wait time and work-in-progress (WIP) breaches per repository. It surfaces which repos have PRs sitting unreviewed longest, helping you identify team bottlenecks before they become friction signals.

#Engineering Health Score

Engineering Health Score (Dashboard → Intelligence → Health Score) gives your team a single composite 0–100 score with an A–F grade representing overall delivery health. It is a weighted roll-up of three sub-scores: DORA performance (40%), PR Cycle Time (35%), and Bottleneck load — the share of opened PRs that never merged (25%). A trend chip shows the delta vs. the previous equivalent period so you can see whether health is improving or degrading. Available on Pro+.

#PR Bottlenecks

PR Bottlenecks (Dashboard → Intelligence → PR Bottlenecks) shows currently-open pull requests that are stalled, oversized, or missing reviewers — fetched live from GitHub across all monitored repositories. Each PR is flagged with the reason it is blocked so your team can act immediately rather than discovering bottlenecks in a weekly retro. Available on Pro+.

#Investment Distribution

Investment Distribution (Dashboard → Intelligence → Investment Distribution) answers the question: where is your engineering effort actually going? It categorises every automation event into one of four buckets — Growth & Innovation, Reliability & Scalability, Maintenance & Tech Debt, and Customer Support & Bugs — derived automatically from trigger type, severity, and PR labels. No extra instrumentation required. Available on Pro+.

#AI Features

Deviera's AI features use your own API key (BYOK — Bring Your Own Key). Connect your key at Dashboard → Integrations → AI / LLM. Supported providers: Anthropic (Claude), OpenAI (GPT-4o), and Google Gemini.

#Connecting an AI provider

1. 1Go to Dashboard → Integrations → AI / LLM.
2. 2Select your provider: Anthropic, OpenAI, or Google Gemini.
3. 3Choose a model (e.g. Claude Sonnet 4.6, GPT-4o, Gemini 2.0 Flash).
4. 4Paste your API key — it is stored encrypted and never logged.
5. 5Toggle the AI features you want to enable (see below).

#Issue enrichment

When enabled, Deviera passes the raw signal context to your AI model and appends a structured root-cause hypothesis and suggested fix to the Linear / Jira / ClickUp issue description before creation. Available on Pro+.

#Signal summary

Generates a plain-English summary of the last 24 hours of signals on the overview page. Useful for standups and async updates. Available on Pro+.

#Root-cause analysis

On demand, ask Deviera to analyse a cluster of signals and identify the likely root cause. The AI looks at trigger type, repository, branch, timing, and signal sequence to surface a hypothesis. Available on Team+.

#AI PR comments

When enabled, Deviera posts an AI-generated review comment on PRs that trigger a stale or CI-failure rule — summarising the issue and suggesting next steps for the author. Available on Team+.

#Natural Language automation builder

Describe any automation in plain English and Deviera's AI converts it to a fully configured trigger + action rule. Available on Team+ via the Dashboard → Automations → New → Describe It tab.

#AI Assistant

The AI Assistant (Dashboard → Intelligence → AI Assistant) is a streaming chat interface connected to your workspace signal data. Ask it questions like:

• "What were the biggest friction sources last week?"
• "Which repos have the worst CI health?"
• "How does our deployment frequency compare to last month?"
• "What were the most critical incidents in the last 7 days?"

#AI Impact

AI Impact (Dashboard → Intelligence → AI Impact) measures your team's AI coding tool adoption by analysing commit messages for signatures from GitHub Copilot, Claude / Claude Code, Cursor, and Sourcegraph Cody. It shows overall adoption %, daily trend, tool breakdown, and per-repo adoption — without requiring any additional integrations.

#Integrations

Deviera connects to 8 external services. All OAuth integrations are connected per workspace — members share the workspace token. Tokens are stored encrypted and automatically refreshed. A daily health sweep at 08:00 UTC probes all tokens and marks broken connections with a "Needs Reconnect" banner so you catch stale tokens before they affect automations.

#Linear

Linear connects via OAuth 2.0. Once connected, automations can create issues in any team you have access to, with configurable priority, labels, and title/description templates. Auto-resolution is supported — paired Linear issues are closed automatically when CI passes or a PR merges.

1. 1Go to Dashboard → Integrations → Linear.
2. 2Click "Connect Linear" — redirected to Linear's OAuth consent screen.
3. 3Grant access to your Linear workspace.
4. 4Return to Deviera and select a default team for issue creation.
5. 5Labels and priorities are automatically fetched from your Linear workspace.

#Jira

Jira connects via Atlassian's OAuth 2.0 flow (cloud instances only). Once connected, automations can create structured Jira issues with project mapping, issue type, priority, labels, and description templates. Token refresh is handled automatically.

1. 1Go to Dashboard → Integrations → Jira.
2. 2Click "Connect Jira" — redirected to Atlassian's OAuth consent screen.
3. 3Authorise access to your Atlassian Cloud site.
4. 4Return to Deviera and select a default project for issue creation.
5. 5Issue types and priorities are fetched automatically from your Jira instance.

#ClickUp

ClickUp connects via OAuth 2.0. Once connected, automations can create tasks in any space and list you have access to, with configurable priority, title, and description templates. Auto-resolution closes tasks when the triggering issue resolves.

1. 1Go to Dashboard → Integrations → ClickUp.
2. 2Click "Connect ClickUp" — redirected to ClickUp's OAuth consent screen.
3. 3Authorise access to your ClickUp workspace.
4. 4Return to Deviera and select a default space and list for task creation.
5. 5Spaces and lists are fetched automatically from your ClickUp workspace.

#GitLab

GitLab integrates via OAuth 2.0, supporting both GitLab.com and self-hosted instances. Once connected, Deviera registers webhooks on your groups and projects to receive pipeline, merge request, and push events — the same signal detection engine as GitHub.

1. 1Go to Dashboard → Integrations → GitLab.
2. 2Click "Connect GitLab" — redirected to GitLab's OAuth consent screen.
3. 3Authorise access to your GitLab groups and projects.
4. 4Return to Deviera — groups and projects are listed automatically.
5. 5Deviera registers webhooks on connected projects to receive events immediately.

#Slack

Slack integration uses an Incoming Webhook URL — no OAuth or app installation required. The webhook URL is validated before saving by sending a test ping message.

1. 1Create an Incoming Webhook in your Slack workspace at api.slack.com/apps.
2. 2Copy the webhook URL from the Slack app configuration.
3. 3Go to Dashboard → Integrations → Slack and paste the URL.
4. 4Click "Save" — Deviera sends a test ping to verify the connection.

#Vercel

The Vercel integration captures deployment events (created, ready, failed) via your Vercel API token. Deviera polls the Vercel API every 5 minutes and surfaces deployment events as signals and automation triggers — no inbound webhook configuration required on Vercel's side.

1. 1Go to Dashboard → Integrations → Vercel.
2. 2Generate an API token at vercel.com/account/tokens (read-only scope is sufficient).
3. 3Paste the token into Deviera and save.
4. 4Deviera lists your Vercel projects and begins capturing deployment events within 5 minutes.

#Sentry

Sentry connects via OAuth 2.0. Once connected, Deviera receives error alert and issue spike webhooks from your Sentry organisation and routes them through your automation rules. Sentry signals appear in the same Signal Feed as GitHub and GitLab events.

1. 1Go to Dashboard → Integrations → Sentry.
2. 2Click "Connect Sentry" — redirected to Sentry to authorise Deviera.
3. 3Select the Sentry organisation you want to connect.
4. 4Deviera registers a webhook on your Sentry organisation automatically.
5. 5Triggers sentry_error_detected and sentry_alert_triggered are now active.

#Workspace & Settings

#Workspace settings

Workspace settings are at Dashboard → Workspace. Owners and admins can:

• Rename the workspace and set a description
• Invite members by email — accepted via a unique invite link
• Assign member roles: Owner, Admin, or Member
• Remove members from the workspace
• Enable or disable the Public Signal Wall and configure its slug and title
• Configure trigger baselines (minutes saved per trigger type) for the Value Dashboard

#Member roles

#Account settings

Personal account settings are at Dashboard → Settings → Account. You can:

• Update your display name
• Enable or disable Multi-Factor Authentication (TOTP via authenticator app)
• Generate and download MFA backup codes
• Export your account data
• Delete your account — requires password confirmation

#Multi-Factor Authentication (MFA)

Deviera supports TOTP-based MFA using any standard authenticator app (Google Authenticator, Authy, 1Password, etc.). When enabled, MFA is required at every sign-in. Backup codes are generated at setup time — download and store them securely. Backup codes are single-use.

1. 1Go to Dashboard → Settings → Account → Security.
2. 2Click "Enable MFA" — a QR code is displayed.
3. 3Scan the QR code with your authenticator app.
4. 4Enter the 6-digit code from your app to verify.
5. 5Download your backup codes and store them safely.

#API Keys

API keys for the Deviera REST API are managed at Dashboard → Settings → API Keys. Keys are prefixed dvr_ and shown once at creation — Deviera stores only a SHA-256 hash. Revoke and regenerate from the same page if a key is lost or compromised. Plan limits: Free (1 key), Pro (5 keys), Team (20 keys), Enterprise (unlimited).

#API Reference

#Authentication

All API requests must include a Deviera API key in the Authorization header. Generate keys at Dashboard → Settings → API Keys.

curl https://deviera.dev/api/automation-events \
  -H "Authorization: Bearer dvr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

#Scopes

Each API key is issued with one or more scopes that limit what it can access. Session-authenticated requests (browser) have full access. API key requests are restricted to granted scopes.

#Endpoints

#Rate limits

The API is rate-limited to 100 requests per minute, applied per client IP address and the same on every plan. There is no separate daily quota.

#Event retention

How long signal / event history is queryable depends on your plan:

#Billing & Plans

#Plans overview

See the full feature comparison on the pricing page.

#Free trial

All new workspaces start on a 14-day free Pro trial — no credit card required. At the end of the trial, the workspace downgrades to Free unless a paid plan is activated. Upgrade at any time from Dashboard → Billing.

#Cancel subscription

Cancel at any time from Dashboard → Billing → Cancel Subscription. Your workspace retains paid-plan features until the end of the current billing period, then downgrades to Free. All data is retained indefinitely — nothing is deleted on downgrade.

#Team seat billing

The Team plan is per-seat with a minimum of 5 seats. Seats are billed at the workspace level — you purchase a seat count and all members share the workspace. Adding members beyond your purchased seat count will prompt an upgrade. Seats can be adjusted from Dashboard → Billing.

#Security

#Security overview

Deviera is designed for engineering teams that need audit-grade visibility with enterprise-level security practices.

• All OAuth tokens are stored AES-encrypted with key rotation support
• GitHub webhooks verified via per-installation HMAC-SHA256 signatures
• Sentry webhook payloads verified with Sentry's internal token scheme
• MFA / TOTP enforced per user with backup codes
• Idle auto-logout with multi-tab BroadcastChannel sync
• Brute-force detection: ≥5 failed sign-ins in 15 min triggers a SecurityIncident
• Rate-limit storm detection: ≥10 rate-limit hits in 15 min triggers a SecurityIncident
• All admin routes protected by ADMIN_EMAILS allowlist

#Audit log

The Audit Log is an Enterprise+ feature that records every user action in the workspace — automation creates/edits/deletes, integration connects/disconnects, member role changes, and billing events. Accessible at Dashboard → Admin → Audit(admin only).

#Token encryption & rotation

OAuth tokens are encrypted with TOKEN_ENCRYPTION_KEY using AES-256. Key rotation is supported via the TOKEN_ENCRYPTION_KEY_PREVIOUS environment variable — tokens encrypted with the previous key are automatically re-encrypted on first read. Encrypted tokens are prefixed with v1: to distinguish from legacy unencrypted rows.

#Free Tools

Deviera ships standalone, no-login-required calculators you can use to benchmark your engineering metrics against DORA standards — before connecting any integrations.

#CI Health Score Calculator

Enter five CI metrics and get an instant letter grade (A–F) with a detailed breakdown across three dimensions benchmarked against DORA Elite / High / Medium / Low thresholds.

No account required. deviera.dev/tools/ci-health-score

#PR Cycle Time Benchmark Tool

Enter four PR velocity metrics — median cycle time, review lag, post-approval delay, and average PR size — and see whether your team ranks as DORA Elite, High, Medium, or Low. The tool pinpoints your specific bottleneck.

No account required. deviera.dev/tools/pr-cycle-time

#DORA Calculator

The DORA Calculator at deviera.dev/tools/dora-calculator lets you input all four DORA metric values and instantly see your performance band across all dimensions with actionable improvement guidance. No login required.

#Onboarding

New workspaces are guided through a step-by-step onboarding wizard at Dashboard → Onboarding. The wizard validates each step live and only advances when the connection is confirmed.

1. 1Tell Deviera what your team uses — GitHub, GitLab, issue trackers, deployment platforms.
2. 2Install the GitHub App or connect GitLab via OAuth.
3. 3Connect your issue tracker — Linear, Jira, or ClickUp.
4. 4Connect Slack (optional) for real-time alerts.
5. 5Enable your first automation preset.
6. 6Trigger a test event to verify signals are flowing.

You can return to the onboarding wizard at any time. Completed steps are marked with a green checkmark. The wizard does not re-run completed steps — skip directly to any incomplete step.

#MCP — Connect AI Agents to Deviera

Deviera exposes a Model Context Protocol (MCP) endpoint at POST https://deviera.dev/api/mcp. Any MCP-compatible AI client — Claude Desktop, Cursor, Windsurf, ChatGPT, and others — can connect to it and query your engineering data in natural language. No extra infrastructure required.

#Connect to Claude Desktop

Open your Claude Desktop config file and add the Deviera server under mcpServers:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "deviera": {
      "type": "http",
      "url": "https://deviera.dev/api/mcp",
      "headers": {
        "Authorization": "Bearer dvr_YOUR_API_KEY"
      }
    }
  }
}

Restart Claude Desktop after saving. You should see a deviera server listed in the MCP servers panel. Ask Claude things like:

• "What is our engineering friction score this week?"
• "Show me the last 10 critical signals from the signal feed"
• "What are our DORA metrics for the past 30 days?"
• "Which repos have the slowest PR cycle times?"

#Connect to Cursor

In Cursor, open Settings → MCP and add a new server entry:

{
  "deviera": {
    "url": "https://deviera.dev/api/mcp",
    "headers": {
      "Authorization": "Bearer dvr_YOUR_API_KEY"
    }
  }
}

#Connect to other clients

Any client that supports the MCP streamable-HTTP transport can connect using:

#Available tools

The following tools are exposed by the Deviera MCP server:

#Authentication

All MCP requests are authenticated with a Deviera API key passed as a Bearer token. Generate a key at Settings → API Keys. The key must have at least the scopes required by the tools you intend to call: