scitor.yaml Reference

The scitor.yaml file lives at .github/scitor.yaml in your repository. All fields are optional — Scitor uses sensible defaults when a field is not specified.

Full example

# .github/scitor.yaml

# Integration type: where to create support tickets
integration: issue    # "issue" (default) or "discussion"

# AI analysis: sentiment, category, summary, and language detection
ai:
  language_detection: true  # detect lang and apply lang:<code> label (Pro, default: true)
# To disable all AI: ai: false

# Priority configuration
priority:
  auto_assign: true     # AI auto-assigns priority (default: true)
  default: medium       # Fallback priority (default: medium)

# SLA tracking (Pro plan)
sla:
  first_response:
    urgent: 1h
    high: 4h
    medium: 8h
    low: 24h
  resolution:
    urgent: 4h
    high: 1d
    medium: 3d
    low: 7d
  business_hours:
    timezone: America/New_York
    start: "09:00"
    end: "17:00"
    days: [mon, tue, wed, thu, fri]

# Documentation site configuration
docs:
  path: docs                           # Folder containing docs (default: "docs")
  title: "Acme Support Docs"           # Site title
  logo: images/logo.png                # Logo image path (relative to repo root)
  favicon: images/favicon.ico          # Favicon path
  domain: support.acme.com             # Custom domain (optional)
  theme: default                       # "default", "minimal", or "corporate"
  color: "#4F46E5"                     # Primary brand color (hex)
  navigation: auto                     # "auto" or "manual"
  search: true                         # Enable client-side search
  footer: "© 2026 Acme Inc."           # Footer text
  homepage: cards                      # "cards" (default) or "classic"

  analytics:
    google: G-XXXXXXXXXX               # Google Analytics measurement ID
    plausible: acme.com                # Plausible Analytics domain

  contact:                              # Docs contact form (optional)
    placement: [footer, floating]       # Where to show the form
    title: "Need help?"                 # Custom form title
    description: "Send us a message."   # Custom form description

  sidebar:                              # Manual navigation (when navigation: manual)
    - title: Getting Started
      path: /getting-started
    - title: API Reference
      path: /api

  versions:                             # Documentation versioning
    - label: "v2.0 (Latest)"
      ref: main
    - label: "v1.0"
      ref: v1-stable

# Routing / auto-assignment
routing:
  auto_assign: true                    # Auto-assign on inbound triage (default: false)
  rules:
    - category: billing                # Match AI-detected category
      assignees: [alice, bob]          # GitHub usernames or team slugs
    - label: "priority:urgent"         # Match label name
      assignees: [oncall-team]

# Suggestion Board (Pro plan) — collect & vote on feature ideas
suggestions:
  enabled: true
  project_title: "Suggestion Board"    # Project board name
  placement: sidebar                   # "sidebar" (default), "footer", or "nav"

# AI Chatbot (Enterprise plan) — embeddable chat widget answering from your docs
chatbot:
  enabled: true
  locale: en                           # Widget UI language: en, nl, de, fr
  color: "#4F46E5"                     # Widget color (defaults to docs.color)
  position: right                      # "right" (default) or "left"
  title: "Support"                     # Widget header title
  escalation: true                     # Allow raising a ticket from the chat

Top-level options

integration

Controls whether inbound emails create Issues or Discussions.

integration: discussion

ai

Enable or disable AI analysis of inbound emails and form submissions.

Scalar form (enable/disable all AI):

ai: false

Object form (fine-grained control):

ai:
  language_detection: true    # Detect language and apply lang:<code> labels (default: true)

Requires the Pro plan. On the Free plan, AI analysis is not performed regardless of this setting.

Docs configuration

All docs settings are nested under the docs: key.

docs.path

The folder in your repository containing documentation markdown files.

docs:
  path: documentation  # Use a different folder name

docs.title

The site title displayed in the header and browser tab.

docs.logo

Path to a logo image, relative to the repository root. Displayed in the site header next to the title.

docs.favicon

Path to a favicon file, relative to the repository root.

docs.domain

Custom domain for your documentation site. When set, Scitor automatically registers the domain and serves your docs at https://your-domain.com (instead of docs.scitor.io/{owner}/{repo}). You must also create a CNAME DNS record pointing to docs.scitor.io.

docs:
  domain: support.yourcompany.com

See the Knowledge Base page for detailed setup instructions. Requires the Pro plan.

docs.theme

Visual theme for the documentation site.

docs.color

Primary brand color used throughout the site (links, active states, accents).

docs.navigation

How the sidebar navigation is generated.

docs.search

Enable or disable client-side search.

docs.footer

Custom text displayed in the page footer.

docs.analytics

Third-party analytics integration.

docs:
  analytics:
    google: G-XXXXXXXXXX    # Google Analytics 4 measurement ID
    plausible: yourdomain.com # Plausible Analytics domain

docs.sidebar

Manual navigation structure. Only used when navigation: manual.

docs:
  navigation: manual
  sidebar:
    - title: Introduction
      path: /intro
    - title: Guides
      path: /guides
    - title: API
      path: /api

docs.versions

Version configuration for multi-version documentation.

docs:
  versions:
    - label: "v2.0 (Latest)"
      ref: main            # Git branch or tag
    - label: "v1.0"
      ref: v1-stable

A version dropdown appears in the header when versions are configured.

docs.homepage

Controls the homepage layout of the documentation site.

docs:
  homepage: classic  # Use the classic article layout for the homepage

The cards layout automatically generates category cards from your top-level folders (using their index.md title, description, and icon) and shows articles marked with featured: true in a “Suggested Articles” section. See Knowledge Base for details.

docs.contact

Contact form configuration for the documentation site. When configured with at least one placement, a contact form is embedded in your docs. The form is automatically created and managed by Scitor — no /create-form command needed.

docs:
  contact:
    placement: [footer, floating]
    title: "Need help?"
    description: "Drop us a message and we'll get back to you."

docs.contact.placement

An array of locations where the contact form should appear. If empty or omitted, no contact form is shown.

You can combine multiple placements:

docs:
  contact:
    placement: [footer, floating]  # Show in both locations

docs.contact.title

Title shown above the contact form.

docs.contact.description

Description shown below the title.

docs.feedback

“Was this article helpful?” feedback widget configuration. The widget is shown on every article by default with no configuration needed.

docs:
  feedback:
    enabled: true                       # default: true
    require_comment_on_negative: false  # default: false
    placement: article-bottom           # only supported value

See Article Feedback Widget for the full reference.

Suggestions configuration

Configure the Suggestion Board — a /suggestions page on your docs site where visitors can submit and vote on feature ideas. Each suggestion becomes a GitHub Issue on an auto-created Project board. Settings are nested under the suggestions: key. Requires the Pro plan.

suggestions:
  enabled: true
  project_title: "Feature Requests"       # Project board name (default: "Suggestion Board")
  categories:                              # Categories shown in the submit form
    - "Bug fix"
    - "New feature"
    - "Improvement"
  moderation: false                        # Hide new suggestions until reviewed (default: false)
  placement: sidebar                       # Link placement: sidebar | footer | nav (default: sidebar)

See Suggestion Board for full details.

Priority configuration

Priority settings are nested under the priority: key. All fields are optional.

priority:
  auto_assign: true     # Let AI assign priority based on content (default: true)
  default: medium       # Fallback priority when AI is unavailable (default: medium)

Priority rules (when AI assigns):

• urgent — System down, security breach, data loss
• high — Major feature broken, blocking issue
• medium — Bugs with workarounds, partial issues
• low — Questions, feature requests, general inquiries

Priority integrates with SLA tracking — each priority level maps to different response and resolution time targets.

SLA configuration

All SLA settings are nested under the sla: key. SLA tracking requires the Pro plan.

Full SLA example

sla:
  first_response:
    urgent: 1h
    high: 4h
    medium: 8h
    low: 24h
  resolution:
    urgent: 4h
    high: 1d
    medium: 3d
    low: 7d
  business_hours:
    timezone: America/New_York
    start: "09:00"
    end: "17:00"
    days: [mon, tue, wed, thu, fri]
  escalation:
    on_breach:
      - label: "sla:breached"
      - assign: oncall-team           # Assign to a user or team on breach
    on_warning:
      - label: "sla:warning"
  warning_threshold: 0.8              # Fraction of SLA time to trigger warning (default: 0.8)

sla.first_response

Maximum time allowed before the first reply via /send. Defined per priority level.

sla.resolution

Maximum time allowed to close/resolve the issue. Defined per priority level.

sla.business_hours

When configured, SLA timers only count time during business hours. Omit this section for 24/7 SLA tracking.

sla.escalation

Actions taken when SLA targets are at risk or breached.

sla:
  escalation:
    on_warning:
      - label: "sla:warning"        # Applied at warning threshold (default: 80% of SLA time)
    on_breach:
      - label: "sla:breached"       # Applied when SLA is exceeded
      - assign: oncall-team         # Assign to a user or team

Each escalation action can include a label to apply, an assign to assign a user or team, or both:

sla.warning_threshold

The fraction of SLA time at which a warning is triggered. For example, 0.8 means the warning fires at 80% of the SLA target time.

sla:
  warning_threshold: 0.75  # Trigger warning at 75% of SLA time

See SLA Tracking for full details on how SLA tracking works.

Follow-up configuration

All follow-up settings are nested under the follow_up: key. Auto follow-ups require the Pro plan.

Full follow-up example

follow_up:
  auto:
    enabled: true
    waiting_on_customer: 3d
    waiting_on_agent: 1d
    max_follow_ups: 3
    auto_close_after: 14d
  templates:
    first: "Hi, just checking in — were you able to resolve this?"
    second: "Following up — if we don't hear back soon, we'll close this ticket."
    final: "Closing this ticket due to inactivity. Feel free to reopen anytime!"

follow_up.auto

follow_up.templates

Customize the messages sent for automated follow-ups. Templates support the {{customer_name}} placeholder, which is replaced with the customer’s name.

See Scheduled Follow-ups for full details.

CSAT Configuration

Configure customer satisfaction surveys. Requires Pro plan.

csat:
  enabled: true
  type: csat              # csat | nps | thumbs | ces (default: csat)
  delay: 1h
  scale: 5
  include_comment: true   # Allow optional free-text comment (default: true)
  exclude_labels:         # Tickets with any of these labels are not surveyed
    - "spam"
    - "spam:high"
    - "spam:medium"
    - "duplicate"
    - "internal"

Options

See Customer Satisfaction (CSAT) for full details.

Replies configuration

Configure saved reply templates. See Saved Replies for full details.

replies:
  path: .github/scitor/replies
  ai_suggest: true
  ai_suggest_threshold: 0.75

Options

Contacts configuration

Configure the contact database and customer history features. Requires the Enterprise plan.

contacts:
  auto_create: true
  auto_company: true
  show_context: true
  vip_domains:
    - acme.com
    - bigcorp.io
  company_domains:
    acme.com: Acme Inc
    bigcorp.io: BigCorp International

Options

See Contact Database and Customer History for full details.

Routing configuration

Configure automatic ticket routing and assignment. Requires the Pro plan.

routing:
  auto_assign: true
  rules:
    - category: billing
      assignees: [alice, bob]
    - category: bug-report
      assignees: [engineering-team]
    - label: "priority:urgent"
      assignees: [oncall-team]

Options

routing.rules

Each routing rule maps a condition (category or label) to a set of assignees. Rules are evaluated in order and the first matching rule wins.

A rule must have at least one of category or label, and at least one assignee, to be valid. Invalid rules are silently ignored.

routing:
  auto_assign: true
  rules:
    # Route billing issues to the finance team
    - category: billing
      assignees: [alice, finance-team]

    # Route urgent tickets to on-call
    - label: "priority:urgent"
      assignees: [oncall-team]

    # Match both category and label (both must match)
    - category: bug-report
      label: "priority:high"
      assignees: ["@bob", engineering-team]  # Leading @ is stripped

Public Ticket Portal configuration

Opt in to the Public Ticket Portal so that outbound emails carry a footer linking to a per-customer web page where the conversation can be viewed and replied to.

portal:
  enabled: true
  allow_reply: true
  retention_after_close: 30d

Options

The portal is fully opt-in: with portal: absent or enabled: false, no footer is appended and no portal data is written. Spam protection (CAPTCHA) is built in and managed by Scitor — no setup required.

Chatbot configuration

Opt in to the AI Chatbot — an embeddable chat widget that answers visitor questions from your knowledge base and escalates to a ticket when needed. Requires the Enterprise plan and a published knowledge base.

chatbot:
  enabled: true
  locale: nl
  color: "#22C55E"
  position: left
  title: "Helpdesk"
  escalation: true
  suggestedQuestions:
    - Hoe reset ik mijn wachtwoord?
    - Wat zit er in het Pro-abonnement?
  instructions: |
    Antwoord beknopt en gebruik een informele toon.
  allowedOrigins:
    - acme.com
    - support.acme.com
  strings:
    greeting: "Hoi! Waarmee kan ik je helpen?"

Options

The chatbot is fully opt-in and answers exclusively from your knowledge base. Rate limiting, usage limits, and abuse protection are built in and managed by Scitor — see Limits & Quotas. Use allowedOrigins if you want to restrict which sites may embed the widget.

Inbound configuration

Controls how Scitor handles incoming customer emails — reopening closed tickets on reply, rate limiting per sender, and deduplicating follow-ups onto existing tickets.

inbound:
  reopen_on_reply: true            # See features/reopen-on-reply
  rate_limit:
    max_per_minute: 5              # 0 disables this bound
    max_per_hour: 30               # 0 disables this bound
  dedup:
    enabled: true                  # See features/deduplication
    window: 7d                     # How far back to look for an existing thread

Options

The whole inbound: section is optional — defaults are applied when keys are missing.