Intro to Plane x GitLab

Video Placeholder Duration: 5-7 minutes Topics covered: GitLab integration setup, merge request automation, connecting projects

---

What is Plane x GitLab?

The Plane GitLab integration connects your GitLab repositories with project management. Automate work item updates based on merge request activity and keep development synchronized.

---

Integration Benefits

• Auto-update work items from MRs
• Link merge requests to work items
• Reference work items in MR titles
• Webhook-based real-time updates

---

Supported GitLab Versions

Version	Description
GitLab.com	Standard cloud-hosted GitLab
GitLab Self-managed	Self-hosted GitLab instances

---

Setting Up the Integration

Step 1: Connect GitLab Account

For GitLab.com:

1. Go to Workspace Settings → Integrations
2. Find GitLab
3. Click Connect
4. Authorize Plane to access your GitLab

For Self-managed:

1. Go to Workspace Settings → Integrations
2. Select GitLab Self-managed
3. Enter your instance URL
4. Complete configuration

Step 2: Connect GitLab Project

1. In the GitLab Project Connections section
2. Click Add
3. Select your GitLab project
4. Confirm connection

This enables webhooks for real-time updates.

Step 3: Connect Plane Project

1. Link your GitLab project to a Plane project
2. Configure MR automation rules
3. Set state mappings

---

Merge Request Automation

How It Works

Reference Plane work items in MR titles or descriptions to trigger automation.

Reference Formats

With brackets (full automation):

[WEB-123] Implement new login flow

Without brackets (link only):

Related to WEB-123

MR State Mapping

Configure what happens at each MR lifecycle stage:

MR Event	Work Item Action
MR opened (draft)	Move to "In Progress"
MR opened	Move to "In Review"
Review requested	Keep in "In Review"
MR approved	Move to "Approved"
MR merged	Move to "Done"
MR closed	Move to "Cancelled"

---

Configuring MR Automation

Access Settings

1. Go to project settings
2. Find GitLab integration section
3. Configure pull request automation

Map States

Define which Plane state corresponds to each MR event:

MR Draft Created → In Progress
MR Ready for Review → In Review
MR Approved → Ready to Deploy
MR Merged → Done
MR Closed (not merged) → Cancelled

Apply Mapping

Save settings. Automation takes effect immediately for new MRs.

---

Workflow Example

---

Multiple Work Items

Reference multiple work items in one MR:

Title: [WEB-123][WEB-124] Auth improvements

Description:
This MR addresses:
- [WEB-123] Session timeout fix
- [WEB-124] Remember me feature

All referenced items update based on MR state.

---

Best Practices

Consistent Formatting

Standardize MR titles:

[WEB-XXX] Brief description

Train Your Team

Everyone should know:

• How to reference work items
• What automation is configured
• When to use bracket format

Match Your Workflow

Configure state mappings to match how your team works:

• When does "in progress" start?
• What states exist between review and done?

Review Automations

Periodically check:

• Is automation working?
• Are states mapping correctly?
• Any edge cases to handle?

---

GitLab vs GitHub Integration

Feature	GitLab	GitHub
MR/PR automation	✅	✅
Issue sync	Limited	✅
Bidirectional sync	Limited	✅
Self-hosted support	✅	✅
Comment sync	Limited	✅

GitHub integration is more feature-complete; GitLab focuses on MR automation.

---

Troubleshooting

MRs not triggering updates

• Check work item format [WEB-123]
• Verify GitLab project is connected
• Check webhook is active

Wrong state applied

• Review state mapping configuration
• Check MR event matches expected stage
• Update mappings if needed

Connection issues

• Re-authenticate GitLab connection
• For self-managed: verify instance URL
• Check permissions

---

Key Takeaways

• GitLab integration automates work items from merge requests
• Supports GitLab.com and self-managed instances
• Reference work items with [WEB-123] format
• Configure state mappings for your workflow
• Real-time updates via webhooks
• Focus is on MR automation (not full issue sync)

---

Next Steps

Extend Plane with custom functionality through Plane Apps.

Next Lesson: Intro to Plane Apps