Migrating from Zendesk

Scitor handles the core functions of a helpdesk — inbound email, reply, triage, knowledge base, CSAT — but everything lives in GitHub instead of a dedicated SaaS tool. This guide maps Zendesk concepts to their Scitor equivalents and walks through the cutover.

The same steps apply if you’re migrating from Help Scout, Intercom, Freshdesk, or a similar tool — the concepts are the same.

Conceptual mapping

What you need to migrate

You don’t need to import historical tickets — Zendesk stays accessible as a read-only archive. Most teams keep Zendesk alive for a few months, then let the subscription lapse.

What actually needs migrating:

• Active open tickets — anything currently in progress
• Macros / canned responses → saved replies
• Knowledge base articles → Markdown docs
• Team access → GitHub collaborators

Step 1: Install Scitor and test in parallel

Install Scitor on your support repository and set up email forwarding. Don’t switch your production email yet — run both systems in parallel and test with a personal email address first.

Once an email to your support address arrives as a GitHub Issue and you can reply with /send, you’re ready for the next steps.

Step 2: Convert macros to saved replies

Zendesk macros become files in .github/scitor/replies/. Create one .md file per macro you want to keep:

---
name: closing-resolved
description: Closing a resolved ticket
---

Hi {{customer_name}},

Glad we could help. I'll close this ticket now — if anything else comes up, just reply to this email.

{{agent_name}}

Available variables:

Use /reply closing-resolved on any issue to insert the template. See Saved replies for the full reference.

Step 3: Migrate your knowledge base

Zendesk Help Center articles map directly to Markdown files. The structure:

• Category → a subdirectory under docs/ (e.g. docs/billing/)
• Article → a .md file with frontmatter

A Zendesk article:

Title: How to reset your password
Section: Account
Body: Click “Forgot password” on the login page to receive a reset email…

Becomes docs/account/reset-password.md:

---
title: How to reset your password
description: Recover access to your account via the password reset flow.
---

# How to reset your password

Click **Forgot password** on the login page to receive a reset email...

Push the docs folder to your repository and enable the knowledge base in scitor.yaml:

docs:
  path: docs
  title: "Your Product Help"

Scitor builds and deploys the site automatically on the next push.

Step 4: Add your team

Add your support agents as GitHub collaborators on the support repository. See Team Management for the required permission levels — agents who reply need Write, queue managers can use Triage.

In Zendesk: Admin → People → Agents
In Scitor: GitHub repository → Settings → Collaborators and teams

Step 5: Cut over email

When you’re ready:

1. Change the forwarding rule on your support email address from Zendesk’s inbound address to your Scitor inbound address
2. New emails now arrive as GitHub Issues
3. Existing open tickets in Zendesk remain there until resolved

That’s the cutover. Customers see no change — they’re still emailing support@yourco.com.

Step 6: Handle open tickets

For active Zendesk tickets still in progress, two options:

Option A (recommended): Close them out in Zendesk. Stop new tickets arriving in Zendesk, finish the open ones there, and let Zendesk become read-only. Most teams finish existing tickets within a week.

Option B: Forward priority tickets manually. For critical tickets mid-resolution, paste the context into a new GitHub Issue and continue. Only practical for a small number of high-priority cases.

What Scitor doesn’t cover

Before migrating, confirm these aren’t blockers for your team:

• Voice / phone — Scitor is email and web forms only
• Live agent chat — The AI chatbot handles common questions automatically, but there’s no real-time agent chat
• Ticket merging — Not supported; link related tickets using GitHub’s #issue-number reference syntax
• Multi-brand from one installation — One Scitor installation per repository; multiple brands need multiple repositories

Migration timeline

A typical migration takes 1–2 weeks end-to-end: