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, and summary
ai: true              # true (default) or false — requires Pro plan

# 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]

Top-level options

`integration`

Controls whether inbound emails create Issues or Discussions.

Value	Description
`issue`	Creates GitHub Issues (default)
`discussion`	Creates GitHub Discussions

integration: discussion

Info

When using discussion, make sure GitHub Discussions is enabled on your repository (Settings → General → Features → Discussions).

`ai`

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

Value	Description
`true`	Enable AI analysis (default)
`false`	Disable AI analysis

ai: false

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.

Default	Type
`docs`	string

docs:
  path: documentation  # Use a different folder name

`docs.title`

The site title displayed in the header and browser tab.

Default	Type
Repository name	string

`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.

Value	Description
`default`	Standard layout with sidebar, TOC, and clean typography
`minimal`	Centered layout without sidebar, serif typography
`corporate`	Branded header with primary color, wider sidebar

`docs.color`

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

Default	Type
`#4F46E5` (indigo)	Hex color string

`docs.navigation`

How the sidebar navigation is generated.

Value	Description
`auto`	Generated from file structure (default)
`manual`	Uses the `sidebar` configuration

`docs.search`

Enable or disable client-side search.

Default	Type
`true`	boolean

`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.

Value	Description
`cards`	Card-grid help center layout with category cards and featured articles (default)
`classic`	Standard article layout rendering the root `index.md` content

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.

Value	Description
`footer`	Full-width form at the bottom of each page
`article-bottom`	Form at the end of article content (before related articles)
`sidebar`	Compact form at the bottom of the sidebar navigation
`floating`	Floating action button (FAB) in the bottom-right corner

You can combine multiple placements:

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

`docs.contact.title`

Title shown above the contact form.

Default	Type
`"Can't find what you're looking for?"`	string

`docs.contact.description`

Description shown below the title.

Default	Type
`"Send us a message and we'll get back to you."`	string

`docs.contact.turnstile_site_key`

Cloudflare Turnstile site key for spam prevention. When omitted, the Scitor-provided default key is used. You only need to set this if you want to use your own Turnstile widget.

Default	Type
Scitor-provided key	string

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)

Key	Type	Default	Description
`auto_assign`	boolean	`true`	When enabled, AI triage automatically assigns priority based on content analysis
`default`	string	`medium`	Default priority level. One of: `urgent`, `high`, `medium`, `low`

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: 30m
    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.

Priority	Default	Format
`urgent`	`1h`	Duration string (`30m`, `4h`, `1d`, `1w`, or combinations like `1d 4h`)
`high`	`4h`
`medium`	`8h`
`low`	`24h`

`sla.resolution`

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

Priority	Default	Format
`urgent`	`4h`	Duration string
`high`	`1d`
`medium`	`3d`
`low`	`7d`

`sla.business_hours`

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

Field	Description	Example
`timezone`	IANA timezone name	`America/New_York`, `Europe/London`, `UTC`
`start`	Business day start time (24h format)	`"09:00"`
`end`	Business day end time (24h format)	`"17:00"`
`days`	Working days	`[mon, tue, wed, thu, fri]`

`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:

Field	Type	Description
`label`	string	Label to apply to the issue
`assign`	string	GitHub username or team slug to assign

`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.

Default	Type
`0.8`	number (between 0 and 1, exclusive)

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`

Field	Description	Default
`enabled`	Enable auto follow-ups	`false`
`waiting_on_customer`	Time before first auto follow-up	`3d`
`waiting_on_agent`	Reminder if agent hasn’t replied	`1d`
`max_follow_ups`	Maximum number of auto follow-ups	`3`
`auto_close_after`	Auto-close after all follow-ups exhausted	(disabled)

`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.

Field	Description
`first`	First follow-up message
`second`	Subsequent follow-up messages
`final`	Message when auto-closing

See Scheduled Follow-ups for full details.

CSAT Configuration

Configure customer satisfaction surveys. Requires Pro plan.

csat:
  enabled: true
  delay: 1h
  scale: 5
  exclude_labels:
    - "spam"
    - "duplicate"
    - "internal"

Options

Field	Description	Default
`enabled`	Enable CSAT surveys	`false`
`delay`	Delay before sending survey after ticket close	`1h`
`scale`	Rating scale: `5` (stars) or `2` (thumbs)	`5`
`exclude_labels`	Labels that prevent surveys	`["spam", "spam:high", "spam:medium", "duplicate", "internal"]`

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

Field	Description	Default
`path`	Folder in repo containing reply Markdown files	`.github/scitor/replies`
`ai_suggest`	Suggest matching replies after AI triage (Pro)	`true`
`ai_suggest_threshold`	Confidence threshold for suggestions (0–1)	`0.75`

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

Field	Description	Default
`auto_create`	Automatically create contacts from inbound emails	`true`
`auto_company`	Auto-detect company from email domain	`true`
`show_context`	Post customer context comment on new tickets	`true`
`vip_domains`	List of domains to auto-tag contacts as `vip`	`[]`
`company_domains`	Map of domains to company names (overrides auto-detection)	`{}`

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

Field	Description	Default
`auto_assign`	Automatically assign tickets on inbound triage	`false`
`rules`	Routing rules evaluated in order; first match wins	`[]`

`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.

Field	Type	Description
`category`	string	AI-detected category to match (e.g. `billing`, `bug-report`). Case-insensitive.
`label`	string	Label name to match (e.g. `priority:urgent`)
`assignees`	string[]	GitHub usernames or team slugs to assign. Leading `@` is stripped automatically.

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

scitor.yaml Reference

Full example

Top-level options

integration

ai

Docs configuration

docs.path

docs.title

docs.logo

docs.favicon

docs.domain

docs.theme

docs.color

docs.navigation

docs.search

docs.footer

docs.analytics

docs.sidebar

docs.versions

docs.homepage

docs.contact

docs.contact.placement

docs.contact.title

docs.contact.description

docs.contact.turnstile_site_key

Priority configuration

SLA configuration

Full SLA example

sla.first_response

sla.resolution

sla.business_hours

sla.escalation

sla.warning_threshold

Follow-up configuration

Full follow-up example

follow_up.auto

follow_up.templates

CSAT Configuration

Options

Replies configuration

Options

Contacts configuration

Options

Routing configuration

Options

routing.rules

Can't find what you're looking for?

`integration`

`ai`

`docs.path`

`docs.title`

`docs.logo`

`docs.favicon`

`docs.domain`

`docs.theme`

`docs.color`

`docs.navigation`

`docs.search`

`docs.footer`

`docs.analytics`

`docs.sidebar`

`docs.versions`

`docs.homepage`

`docs.contact`

`docs.contact.placement`

`docs.contact.title`

`docs.contact.description`

`docs.contact.turnstile_site_key`

`sla.first_response`

`sla.resolution`

`sla.business_hours`

`sla.escalation`

`sla.warning_threshold`

`follow_up.auto`

`follow_up.templates`

`routing.rules`