Jira & Linear Integration

Sync Verk with Jira or Linear to unify engineering workflows, keep issues aligned across platforms, and eliminate manual status updates.

Jira Integration

Quick Setup

Connect Verk to Jira Cloud or Jira Server:

1. Navigate to Integrations

• Go to Settings → Integrations
• Find Jira in available integrations
• Click Connect to Jira

2. Authorize Connection

• Select Jira Cloud or Jira Server
• Enter your Jira instance URL (e.g., yourcompany.atlassian.net)
• Sign in with Jira credentials
• Grant requested permissions
• Click Allow

3. Configure Project Mapping

• Map Verk projects to Jira projects
• Set default issue types
• Configure field mappings
• Choose sync direction
• Save configuration

4. Test Sync

• Create a task in Verk
• Verify it appears in Jira
• Update the Jira issue
• Confirm changes sync back to Verk

Jira Sync Features

What Syncs Bi-Directionally:

• Issue title ↔ Task title
• Issue description ↔ Task description
• Status ↔ Task status (with mapping)
• Priority ↔ Task priority
• Assignee ↔ Task assignee
• Due date ↔ Task due date
• Comments ↔ Task comments
• Attachments ↔ Task files
• Labels ↔ Task tags
• Custom fields (configurable)

Jira-Specific Fields:

• Story Points → Custom number field
• Sprint → Task label or custom field
• Epic → Verk project or parent task
• Components → Task tags
• Fix Versions → Milestone field

Status Mapping (Jira)

Map Jira workflow states to Verk statuses:

Default Mapping:

Jira Status   → Verk Status
─────────────────────────────────────
To Do    → To Do
Backlog    → To Do
In Progress   → In Progress
In Development  → In Progress
In Review   → In Progress
Done    → Done
Closed    → Done

Custom Mapping:

1. Go to Settings → Integrations → Jira
2. Click Status Mapping
3. For each Jira status, select corresponding Verk status
4. Create new Verk statuses if needed
5. Save mapping

Bi-Directional Sync:

• Changing Verk status updates Jira (respects workflow transitions)
• Changing Jira status updates Verk automatically
• Invalid transitions trigger warnings

Jira Sprints & Epics

Sprint Integration:

Jira Sprint → Verk Milestone
─────────────────────────────
Sprint tasks automatically tagged
Filter Verk tasks by sprint
Sprint burndown in both systems
Completion syncs to Jira

Enable Sprint Sync:

1. In integration settings, enable Sync Sprints
2. Map sprints to Verk milestones or tags
3. Choose sync strategy (milestone vs. tag)
4. Save configuration

Epic Sync:

Jira Epic → Verk Project or Parent Task
──────────────────────────────────────
Option 1: Epic → Separate Verk project
Option 2: Epic → Parent task with subtasks
Option 3: Epic → Task tag

Choose your epic strategy:

• Separate projects: Best for large epics with many issues
• Parent tasks: Good for smaller epics, maintains hierarchy
• Tags: Simplest, for loose epic grouping

Jira Automation Examples

Auto-Sync Development Issues:

Trigger: New issue created in Jira project "BACKEND"
Action: Create task in Verk "Backend Development" project
Assign: Based on Jira assignee
Labels: Add "From Jira" tag

Status Transition Automation:

Trigger: Verk task moved to "In Review"
Condition: Task has "Jira" tag
Action: Update Jira status to "Code Review"
Notify: Post to Slack #engineering

Release Management:

Trigger: Jira Fix Version set to "v2.0"
Action: Add Verk task to "Release 2.0" milestone
Update: Priority to High
Assign: Release manager

Linear Integration

Quick Setup

Connect Linear to Verk:

1. Navigate to Integrations

• Go to Settings → Integrations
• Find Linear in available integrations
• Click Connect to Linear

2. Authorize Linear

• Sign in to Linear
• Select workspace
• Review permissions
• Click Authorize

3. Configure Teams & Projects

• Map Linear teams to Verk projects
• Set field mappings
• Configure sync preferences
• Save setup

4. Test Integration

• Create task in Verk
• Check Linear for new issue
• Update issue priority in Linear
• Verify sync to Verk

Linear Sync Features

What Syncs Bi-Directionally:

• Issue title ↔ Task title
• Issue description ↔ Task description (markdown preserved)
• State ↔ Task status
• Priority ↔ Task priority
• Assignee ↔ Task assignee
• Due date ↔ Task due date
• Labels ↔ Task tags
• Comments ↔ Task comments
• Attachments ↔ Files

Linear-Specific Fields:

• Estimate → Task estimated time
• Cycle → Milestone or sprint tag
• Project → Verk project (configurable)
• Parent Issue → Parent task in Verk

Status Mapping (Linear)

Linear's workflow-based states map cleanly:

Default Mapping:

Linear State   → Verk Status
─────────────────────────────────────
Backlog    → To Do
Todo    → To Do
In Progress   → In Progress
In Review   → In Progress
Done    → Done
Canceled   → Archived (custom status)

Priority Mapping:

Linear Priority  → Verk Priority
─────────────────────────────────────
Urgent (1)   → High
High (2)   → High
Medium (3)   → Medium
Low (4)    → Low
No Priority   → (none)

Linear Cycles & Projects

Cycle Sync:

Linear Cycle → Verk Milestone
─────────────────────────────
Active cycle → Current milestone
Future cycles → Upcoming milestones
Past cycles → Completed milestones

Enable Cycle Tracking:

1. In Linear integration settings, enable Sync Cycles
2. Choose sync method (milestone, tag, or custom field)
3. Set active cycle behavior
4. Save configuration

Linear Projects:

Linear Project → Verk Project (Option 1)
Linear Project → Verk Tag (Option 2)

Choose based on your team structure:

• Verk Projects: Better for distinct initiatives
• Verk Tags: Better for cross-cutting themes

Linear Automation Examples

Auto-Triage Bugs:

Trigger: Linear issue created with "Bug" label
Action: Create Verk task in "Bug Triage" project
Priority: Set to High
Assign: On-call engineer
Notify: Post to #bugs Slack channel

Feature Development Workflow:

Trigger: Linear issue moved to "In Progress"
Condition: Issue has "Feature" label
Action: Create GitHub branch
Update: Verk task status
Add: Development checklist to task

Release Automation:

Trigger: All Linear issues in cycle completed
Action: Mark Verk milestone as complete
Create: Release notes task
Notify: Product team via Slack

Common Integration Patterns

Development Team Workflow

Jira + GitHub + Verk:

1. Product creates Jira epics
2. Epics sync to Verk projects
3. Engineers break down into tasks
4. Tasks sync back to Jira issues
5. GitHub commits reference both
6. Status updates flow everywhere

Linear + Verk + Slack:

1. Design team uses Verk for creative work
2. Engineering uses Linear for development
3. Cross-functional tasks exist in both
4. Status updates sync bi-directionally
5. Slack notifies on key changes

Hybrid Team Structure

Scenario: Design team uses Verk, Engineering uses Jira

Setup:

1. Map shared projects between systems
2. Sync handoff tasks bi-directionally
3. Keep tool-specific work isolated
4. Use tags to identify cross-tool tasks

Workflow:

Design Task (Verk only)
↓
Design Complete → Sync to Jira
↓
Engineering Task (Jira)
↓
Development Complete → Sync to Verk
↓
QA Task (Verk only)

Migration Strategy

Moving from Jira to Verk:

Phase 1: Setup (Week 1)

1. Connect Jira integration
2. Map one pilot project
3. Test bi-directional sync
4. Train team on both systems

Phase 2: Parallel (Weeks 2-4)

1. Teams use both systems
2. Sync keeps data aligned
3. Gradually shift work to Verk
4. Monitor for sync issues

Phase 3: Transition (Week 5+)

1. Create new work in Verk
2. Complete existing Jira issues
3. Reduce Jira usage over time
4. Keep integration for legacy data

Phase 4: Archive

1. Export Jira history
2. Disable integration
3. Archive Jira instance
4. Full workflow in Verk

Troubleshooting

Sync Failures

Issue: Tasks not syncing to Jira/Linear

Solutions:

• Verify integration is connected and authorized
• Check project mappings are configured
• Ensure you have permissions in both systems
• Review field mappings for incompatibilities
• Check for API rate limit errors
• Manually trigger sync to test

Status Not Updating

Issue: Verk status change doesn't update Jira

Solutions:

• Verify status mapping is configured
• Check Jira workflow allows the transition
• Ensure bi-directional sync is enabled
• Confirm you have edit permissions
• Look for workflow validator errors
• Review integration error logs

Duplicate Issues

Issue: Same item appears multiple times

Solutions:

• Check for multiple integrations to same project
• Verify unique ID mapping
• Review automation rules
• Disable and reconnect integration
• Contact support to help deduplicate

Field Mapping Issues

Issue: Custom fields not syncing

Solutions:

• Verify field types are compatible
• Configure field mapping explicitly
• Check for required fields without defaults
• Review data type conversions
• Use webhooks for complex mappings

Permission Errors

Issue: "Permission denied" in Jira/Linear

Solutions:

• Verify you're a project admin
• Check API token hasn't expired
• Re-authorize integration
• Review project-level permissions
• Contact Jira/Linear admin

Best Practices

Planning Your Integration

Start Small:

• Connect one project initially
• Test thoroughly before expanding
• Train team on sync behavior
• Document your field mappings

Strategic Project Selection:

• Choose projects with clear ownership
• Avoid projects in active transition
• Pick stable, well-defined workflows
• Select teams comfortable with change

Field Mapping Strategy:

• Map only essential fields initially
• Add custom fields incrementally
• Document mapping decisions
• Review and refine quarterly

Maintaining Sync Quality

Regular Audits:

• Review sync logs weekly
• Address errors promptly
• Verify data accuracy monthly
• Update mappings as workflows evolve

Communication:

• Train team on which tool to use when
• Document sync behavior
• Set expectations for sync timing
• Create escalation process for issues

Data Hygiene:

• Close stale issues in both systems
• Archive completed projects
• Clean up orphaned items
• Maintain consistent naming

Performance Optimization

Reduce API Calls:

• Sync only active projects
• Use scheduled vs. real-time for low-priority projects
• Batch updates when possible
• Archive old projects to reduce load

Smart Filtering:

• Exclude resolved issues from sync
• Filter by date ranges
• Sync only specific issue types
• Use labels to control what syncs

Related Documentation

• Integration Overview - General integration concepts
• Custom Integrations - Build custom connectors
• Webhooks - Advanced automation
• API Reference - Developer documentation
• Project Management - Verk project setup

---

Jira and Linear integrations keep engineering teams aligned across tools, eliminating duplicate work and ensuring everyone has the latest information.