How to Use the Discord to Linear Automation

This automation automatically creates Linear tickets when team members react to Discord messages with the 🧿 emoji. It's perfect for capturing important discussions, bug reports, feature requests, or any message that needs to become a trackable task.

In your Val Town environment, set these three required variables:

1. DISCORD_BOT_TOKEN

   • Go to Discord Developer Portal
   • Create a new application → Bot
   • Copy the bot token
   • Required permissions: "Read Message History" and "Add Reactions"

2. LINEAR_API_KEY

   • Go to Linear → Settings → API
   • Create a Personal API key
   • Copy the key

3. LINEAR_TEAM_ID

   • Use the setup dashboard to find your team ID
   • Or check Linear's URL when viewing your team

1. In Discord Developer Portal, go to OAuth2 → URL Generator
2. Select "bot" scope
3. Select permissions: "Read Message History", "Add Reactions"
4. Use the generated URL to add the bot to your server

1. Open the setup dashboard (/setup-dashboard.ts)
2. Check that all environment variables show as "Set"
3. Use the test form to create a ticket from any Discord message
4. Verify the ticket appears in Linear

1. Find a message in Discord that needs to become a Linear ticket
2. React with 🧿 (the charmaine emoji)
3. Wait a moment - the automation will:
   • Fetch the full message content
   • Create a Linear ticket with a descriptive title
   • Include the message content and a link back to Discord
   • Add the "discord-import" label

The Linear ticket will contain:

• Title: First 100 characters of the Discord message
• Description:
  • Link to the original Discord message
  • Author information
  • Full message content
  • Any attachments or embeds
• Label: "discord-import" (automatically created)
• Priority: Medium (configurable)

Edit /backend/config.ts to customize:

export const CONFIG = {
  TARGET_EMOJI: "🧿",           // Change the trigger emoji
  LINEAR_LABEL_NAME: "discord-import",  // Change the label name
  LINEAR_PRIORITY: 3,           // 1=Urgent, 2=High, 3=Medium, 4=Low
  MAX_TITLE_LENGTH: 100,        // Maximum characters in ticket title
} as const;

✅ Good use cases:

• Bug reports from users
• Feature requests
• Important discussions that need follow-up
• Action items from meetings
• Customer feedback
• Technical issues

❌ Avoid for:

• Casual conversations
• Already resolved issues
• Duplicate reports (check Linear first)

For best results, ensure Discord messages:

• Have clear, descriptive content
• Include relevant context
• Mention specific steps or requirements
• Include screenshots/attachments when helpful

1. Anyone can trigger: Any team member can react with 🧿
2. Review tickets: Regularly review "discord-import" labeled tickets
3. Triage and assign: Move tickets to appropriate projects/assignees
4. Update status: Remove the "discord-import" label once triaged

"Environment variable not set" error:

• Check that all three environment variables are configured
• Verify there are no extra spaces in the values

"Discord API error" messages:

• Verify the bot token is correct
• Ensure the bot is in the Discord server
• Check bot permissions include "Read Message History"

"Linear API error" messages:

• Verify the Linear API key is valid
• Check that the team ID exists and you have access
• Ensure the API key has permission to create issues

Tickets not being created:

• Check the automation logs for errors
• Verify you're using the exact 🧿 emoji
• Test with the setup dashboard first

1. Check the setup dashboard for configuration status
2. Use the test form to isolate issues
3. Check Val Town logs for detailed error messages
4. Verify permissions in both Discord and Linear

• Monitor the "discord-import" label in Linear
• Review automation logs in Val Town
• Check for any failed ticket creations

• The automation typically creates tickets within 5-10 seconds
• Failed attempts are logged with detailed error messages
• No rate limiting issues under normal usage

1. Train your team on when and how to use the 🧿 reaction
2. Set up Linear workflows to handle imported tickets
3. Regular cleanup of the "discord-import" label
4. Monitor for duplicates before reacting to messages
5. Use descriptive Discord messages for better ticket titles

Need help? Check the setup dashboard or review the automation logs in Val Town for detailed error information.