Overview

Decern is the decision register for engineering teams. It helps you document, share and enforce architectural decisions (ADRs) across your entire software delivery lifecycle.

Every significant technical choice, from database migrations to infrastructure changes, gets recorded as a decision. Decisions flow through a clear lifecycle (proposed → approved → superseded / rejected) and can be enforced automatically in your CI/CD pipeline via Decision Gate.

How Decern fits your workflow

Core components

• Decern App - the web dashboard where you manage workspaces, projects, decisions and team members.
• Decision Gate (decern-gate) - a CLI you run in CI to enforce decision policies on high-impact changes.
• Protocol (@decern/protocol) - a stateless TypeScript library with shared domain logic (ADR parsing, validation, policies).

Getting Started

Get up and running in under five minutes.

1. Create an account

Sign up at app.decern.dev. A default workspace is created automatically for you.

2. Create your first project

From the dashboard, go to Projects → New project. Give it a name (e.g. your repository name) and optionally link a GitHub repository to enable ADR sync.

3. Record your first decision

Open the project and click New decision. Fill in:

• Title - a short summary (e.g. "Adopt PostgreSQL for user data").
• Context - the problem or requirement that prompted this decision.
• Options considered - the alternatives you evaluated.
• Decision - what you chose and why.
• Consequences - positive and negative impacts of this choice.

The decision starts in proposed status. An approver can move it to approved.

4. Connect your CI (optional)

To enforce decisions on pull requests, install decern-gate in your pipeline. See the CI Integration section below.

Workspaces

A workspace is the top-level container where your team collaborates. It holds projects, decisions, members, and policies.

When you sign up, a default workspace is automatically created. Depending on your plan you can create additional workspaces.

Members

Invite team members via email from Workspace → Members. Each member has a workspace access role (admin or member). On the Business plan, members also receive a decision role, see Roles & Permissions.

CI Token

To use Decision Gate, the workspace owner generates a CI Token from Workspace → Token CI (Decision Gate). The token is shown only once, store it in your CI secrets as DECERN_CI_TOKEN.

Projects

Projects live inside a workspace and group related decisions together, usually one project per repository or service.

When creating a project you can optionally link a GitHub repository. This enables:

• Two-way ADR sync - decisions are committed as markdown files in your repo.
• Pull request URLs are automatically linked to decisions.

Plan limits

Decisions

Decisions are the core entity of Decern. Each decision is an Architectural Decision Record (ADR) that captures the context, options, outcome, and consequences of a technical choice.

Decision fields

• Title - short summary of the decision.
• Status - proposed, approved, superseded, or rejected.
• Context - the problem or requirement.
• Options - alternatives considered (one per line).
• Decision - what was chosen and why.
• Consequences - positive and negative impacts.
• Tags - free-form labels for categorization.
• External links - references to RFCs, design docs, etc.
• Pull request URLs - linked PRs implementing this decision.
• ADR ref - an optional identifier like ADR-001 used for GitHub sync and CI references.
• Linked decision - reference to a superseded decision.

Decision lifecycle

A decision starts as proposed. Team members with the appropriate role can approve or reject it. An approved decision can later be superseded by a new one, and the old decision links to its replacement.

AI generation

Decern can generate a decision draft from a plain-text description using AI. Paste your thoughts and click Generate with AI, and the system produces a structured ADR you can review and edit before saving. This feature is available on all plans under fair-use limits.

CSV export

Export all decisions in a project as CSV from Project → Export. Useful for audits and offline review.

CI Integration

Decern integrates into your CI/CD pipeline via decern-gate, a lightweight CLI that ensures high-impact changes are backed by an approved decision before they can be merged.

Quick setup

1. Generate a CI token in your workspace settings (see Workspaces).
2. Add DECERN_BASE_URL and DECERN_CI_TOKEN as secrets in your CI provider.
3. Add the gate step to your pipeline (see examples below).

GitHub Actions

name: Decern Gate
on:
  pull_request:
    branches: [main]

jobs:
  gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Decern gate
        env:
          DECERN_BASE_URL: ${{ secrets.DECERN_BASE_URL }}
          DECERN_CI_TOKEN: ${{ secrets.DECERN_CI_TOKEN }}
          CI_BASE_SHA: ${{ github.event.pull_request.base.sha }}
          CI_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
          CI_PR_TITLE: ${{ github.event.pull_request.title }}
          CI_PR_BODY: ${{ github.event.pull_request.body }}
        run: npx decern-gate

GitLab CI

decern-gate:
  script:
    - export CI_BASE_SHA=$CI_MERGE_REQUEST_DIFF_BASE_SHA
    - export CI_HEAD_SHA=$CI_COMMIT_SHA
    - export CI_PR_TITLE="$CI_MERGE_REQUEST_TITLE"
    - export CI_PR_BODY="$CI_MERGE_REQUEST_DESCRIPTION"
    - npx decern-gate
  variables:
    DECERN_BASE_URL: $DECERN_BASE_URL
    DECERN_CI_TOKEN: $DECERN_CI_TOKEN

Jenkins

export DECERN_BASE_URL="https://app.decern.dev"
export DECERN_CI_TOKEN="$(cat /run/secrets/decern_ci_token)"
export CI_BASE_SHA="${GIT_PREVIOUS_COMMIT:-origin/main}"
export CI_HEAD_SHA="${GIT_COMMIT}"
npx decern-gate

How to reference a decision in your PR

The gate extracts decision references from the PR title, body, or commit message. Use any of these formats:

• decern:<decision-id> - e.g. decern:550e8400-...
• DECERN-<id> - e.g. DECERN-550e8400
• A Decern URL containing /decisions/<id>
• An ADR ref - e.g. ADR-001

Decision Gate

Decision Gate is the core enforcement mechanism. When your PR touches files that match high-impact patterns, the gate requires a reference to an approved decision.

High-impact file patterns

The gate automatically detects changes to:

Custom patterns

Add extra patterns via the DECERN_GATE_EXTRA_PATTERNS environment variable. Comma-separated. Paths containing / match as substrings; otherwise they match the basename exactly.

DECERN_GATE_EXTRA_PATTERNS=internal/config/,secret.conf

Gate flow

1. Compute changed files via git diff --name-only base...head.
2. Check if any file matches a high-impact pattern.
3. If yes, extract decision references from PR title/body/commit message.
4. Call the validate endpoint to confirm the decision is approved.
5. If the LLM Judge is enabled, run the judge step.
6. Exit 0 (pass) or exit 1 (block).

Plan behavior

Environment variables

LLM Judge

The LLM-as-a-Judge is an optional step that runs after validation. It uses an LLM to verify that the actual code diff is consistent with the referenced decision.

How it works

1. After validate passes, the CLI builds the full git diff (with exclusions and a 2 MB cap).
2. Sends the diff + decision reference + your LLM config to the judge endpoint.
3. The backend calls the LLM with the decision content and diff, asking if they align.
4. Returns allowed: true/false with a confidence score and reason.

BYO LLM

The judge is Bring Your Own LLM. You provide the API credentials via environment variables, they are sent in the request body and never storedby the backend. Compatible with OpenAI and Anthropic APIs.

Diff exclusions

Before sending, the CLI automatically excludes:

• Images and heavy assets (.png, .jpg, .gif, .svg, .pdf, .woff2, etc.)
• Single files larger than 1 MB
• Total diff capped at 2 MB (truncated with a flag)

Advisory vs Blocking

On the Free plan the judge is always advisory, it logs warnings but never blocks the pipeline. On Team and Business, the judge can block if the workspace policy "Judge blocking" is enabled (on by default). When the backend returns advisory: true, the CLI passes even if allowed: false.

Confidence & tolerance

The judge returns a confidence score (0–1). You can set a minimum threshold via DECERN_JUDGE_MIN_CONFIDENCE - the gate blocks if the score is below, even when allowed: true. Workspace admins can also set a judge tolerance percentage in the workspace policies.

Policies

Workspace policies configure how Decision Gate behaves for your team. They are set in Workspace → Policies (Team+ plans).

GitHub Sync

Decern can sync decisions as ADR markdown files in your GitHub repository, and vice versa.

Setup

1. Connect your GitHub account from Settings → GitHub.
2. When creating a project, select the linked repository.
3. Decisions with an ADR ref (e.g. ADR-001) will be committed as markdown files.

ADR format

Synced files follow the standard ADR markdown format:

# ADR-001: Adopt PostgreSQL for user data

## Status
Approved

## Context
We need a reliable relational database for user data
that supports complex queries and strong consistency.

## Decision
We will use PostgreSQL as our primary database.

## Consequences
- Strong ACID compliance
- Rich ecosystem of tools and extensions
- Team already has PostgreSQL expertise

Webhook sync

Decern installs a GitHub webhook to detect when ADR files are pushed to the repository. Changes to ADR files in the repo are automatically synced back to the Decern dashboard.

Self Hosted

Decern is distributed as a Docker image for self-hosted deployments. The image includes all features (Decision Gate, Judge, GitHub Sync, AI generation, Roles, Policies) with unlimited members. You run the container on your infrastructure, and no source code is exposed.

Quick start

1. Contact support@decern.dev to get access to the container registry (ghcr.io/decernhq/decern).
2. Create a Supabase project (hosted at supabase.com or self-hosted).
3. Run the database migrations against your Supabase instance.
4. Create an .env file with your configuration (see below).
5. Start the container.

services:
  decern:
    image: ghcr.io/decernhq/decern:latest
    ports:
      - "3000:3000"
    env_file:
      - .env
    environment:
      - NEXT_PUBLIC_SELF_HOSTED=true
    restart: unless-stopped

docker compose up -d

Required environment variables

GitHub integration (recommended)

To enable ADR sync and repository linking, create a GitHub OAuth App and set these variables:

AI features

AI decision generation and the fair-use Judge fallback require an OpenAI-compatible API key.

Database migrations

The Supabase migrations are provided separately. Apply them to your Supabase instance using the Supabase CLI or by running the SQL files in order:

# With Supabase CLI (if using Supabase hosted)
supabase db push

# Or apply manually: run each file in supabase/migrations/ in order
# 00001_create_profiles.sql through 00038_projects_create_roles.sql

Plan & features

Licensed self-hosted instances automatically unlock the enterprise tier, all features are enabled with no limits. No Stripe setup is required unless you want to manage internal billing for your organization.

Updating

docker compose pull
docker compose up -d

For pricing, license inquiries, or dedicated support contact support@decern.dev.