End-to-End sync Linear.app and GitHub

Overview

Initially created by Spacedrive, now maintained by Cal.com and Neat.run

Linear to GitHub Sync

This is a system to synchronize Linear issues to GitHub issues when a specific tag tag is added to the Linear issue. This allows contributors to work with open source projects without having to give them access to your internal Linear team.

Usage

Ensure you have the Vercel CLI installed globally on your machine!

git clone https://github.com/calcom/linear-to-github.git
cd linear-to-github/
cp .env.example .env # Make sure to fill to fill out your .env file
pnpm i
vercel dev

Before you've started the server make sure to fill out the information in the .env file, if you don't know how:

Setup

Welcome to the installation page for Spacedrive's Linear and GitHub sync system.

You'll be able to follow along with this guide below, if you need any help please feel free to join our Discord.

Linear

Linear Webhook

  1. Go to "Workspace Settings" and then go to "API".
  2. Under "Webhooks" click "New webhook".
  3. Label this webhook whatever you want, however, set the URL to the URL of the deployed Vercel API, ensuring the URL ends with "/api".
  4. Under "Event Types" check "Issues", "Issue comments", and "Labels".
  5. Press "Create webhook".

Linear API Key

  1. Go to "Workspace Settings" and then go to "API".
  2. Under "Personal API keys" enter a name for your API key in the "Label" field.
  3. Press "Create key".
  4. Hover over the created API key to copy it, make sure to save this somewhere as you can only view it upon creation.

Linear IDs

To get all of the IDs needed from Linear run the following GQL request however you please. Make sure to have your "Authorization" header set to Bearer ${LINEAR_API_KEY} and "Content-Type" as application/json.

query {
	users {
		nodes {
			id
			name
			displayName
		}
	}
	teams {
		nodes {
			id
			name
			key
			labels {
				nodes {
					id
					name
				}
			}
			states {
				nodes {
					id
					name
				}
			}
		}
	}
}

GitHub

GitHub Webhook

  1. In a repository go to "Settings" -> "Webhooks".
  2. Press "Add webhook".
  3. Set the payload URL to the URL of the deployed Vercel API, ensuring the URL ends with "/api".
  4. Set "Content type" to application/json.
  5. Set the "Secret" to a random string, make sure to set it in the .env file as well.
  6. Press "Let me select individual events." and check "Issue comments" and "Issues".
  7. Press "Add webhook"

GitHub API Key

  1. Log in to the account you want to use for syncing.
  2. Click on the dropdown in the top right where your profile picture is.
  3. Press "Settings" -> "Developer Settings" -> "Personal Access Tokens".
  4. Press "Generate new token".
  5. Write a memorable note.
  6. Set Expiration to "No Expiration".
  7. Check all top-level scopes I wasn't able to figure out which scopes properly worked with both public and private repositories, if you have please feel free to make an issue!
  8. Press "Generate token".
  9. Copy the generated token.
Comments
  • Listening to multiple teams at once?

    Listening to multiple teams at once?

    I use multiple teams for 1 project/repo for things like Frontend/Backend, I'd be nice if I could listen to all of the teams in my 1 Linear organization with only 1 linear-to-github API running.

    enhancement later 
    opened by mmattbtw 11
  • Manually removed webhook breaks re-sync

    Manually removed webhook breaks re-sync

    I had the same problem. Webhooks were added when first synchronizing. They will not be added when manually removed and then synchronized again. Secret is missing on GitHub if I fill it in manually, so how do you get secret or can you automatically add it again when synchronizing after detecting the deleted webhooks? image

    Originally posted by @blockmia in https://github.com/calcom/synclinear.com/issues/27#issuecomment-1330325889

    bug 
    opened by lingziyb 7
  • Refactor webhook handlers

    Refactor webhook handlers

    Summary

    Refactored the main POST route contents to use 2 handlers for webhook parsing. The file was really long, and it made testing and maintaining the codebase very hard. This refactor includes:

    • Extracting all the contents of the linear if statement to a new file utils/webhook/linear.handler.ts
    • Extracting all the contents of the github if statement to a new file utils/webhook/github.handler.ts
    • Removed dependency on the req object inside the handlers (body and headers passed as params)
    • Instead of calling res.send inside the handlers, the handlers exit in 2 ways:
      • Throw an API error exception with message and code status
      • Return a status string back to calling function
    • Haven't touched any functionality rather the exist of the handler functions

    I hope these changes are the first step to further refactor the handler functions as they contain more duplicated code.

    opened by scopsy 6
  • Fix sync matching for multi team setup

    Fix sync matching for multi team setup

    Summary

    When filtering sync, add a linearTeamId as part of the comparison to allow same user to be part of multiple linear teams. Internally we would love to sync issues from a Roadmap team to another repository at https://github.com/novuhq/roadmap, currently issues are not synced in this setup (we already sync issues for our main repo novuhq/novu

    Reproduce

    • Create 2 linear teams
    • Assign a user to be part of both teams
    • Try to sync issues from both teams
    • Only issues created from the first team will be synced
    opened by scopsy 6
  • does not add a webhook to github

    does not add a webhook to github

    It doesn't add a webhook to my github repository when I select my project repo to sync with linear.app, it loads, but when I go back to github I don't see a webhook added.

    synclinear.com

    image

    GitHub settings

    image


    PS: The first one did add a webhook, but then I deleted it and re-synced my repo, but this time it no longer added a webhook.

    bug 
    opened by abrahamcalsin 6
  • Runway deployment broken?

    Runway deployment broken?

    Screen Shot 2022-10-21 at 4 39 55 PM

    I deployed the app to runway but Linear is telling me the URL for hooking it up is invalid.

    Here is an API key sanitized version

    https://linear.app/oauth/authorize?client_id=1234&redirect_uri=https://app-production-111.up.railway.app&scope=write&state=linear-asdf&response_type=code&prompt=consent

    I played around with the uri.. adding /? between the domain and the url params. As well as doing encodeURIComponent on the url, but I got the same thing from Linear.

    This could be a Linear bug! Unsure.

    Anyone else seeing this?

    documentation 
    opened by jeffchuber 6
  • Sync not working after convert `Public` to workspace label

    Sync not working after convert `Public` to workspace label

    Description

    I converted Public from the team label to the workspace label in linear, then the sync service started not working on newly added issues.

    Steps to Reproduce

    1. setup sync service between linear team A and GitHub repository B
    2. create a label named Public in team settings
    3. convert Public to workspace label
    4. label an issue in A with Public
    5. the issue will not sync to B

    To convert a label to a workspace label

    image
    opened by HenryC-3 5
  • Refactor petitio to got

    Refactor petitio to got

    Summary

    Due to the unsupported node 16+ version on petition (https://github.com/helperdiscord/petitio/issues/40) which causes all one link deployments (railway and etc...) to not work. Closes #35

    Test Plan

    Unfortunately due to lacking existing test suite mostly doing manual tests for this, would love to get some help to spot potential errors. We have also deployed this to our own self-hosted version and working with this for the last couple of days with no issues.

    Related Issues

    Closes #35

    opened by scopsy 5
  • GitHub webhook deployment not working.

    GitHub webhook deployment not working.

    Hey there team, thanks for this project, seems very cool!

    An issue I've faced while trying to get setup is that the Deploy Webhook button seems to be already deployed when I go to deploy the GitHub webhook on my repo, but when I look in the Webhook settings of the GitHub repo there is no SyncLinear webhook, there is however a Discord one I use to relay events, it may be possible that it's conflicting with the setup?

    I'm not sure if this is something I've broken accidentally, but I've followed the steps that were detailed so not really sure where I went astray, if it was me.

    Thanks!

    bug 
    opened by Codeize 5
  • Gitlab support

    Gitlab support

    Hi,

    I was wondering if you'd be interested in supporting Gitlab repositories too. This is something that we are exploring at Front-Commerce and with maybe some guidance about the caveats to be careful at, we could even contribute this feature.

    Before this, I wanted to start a discussion here to see if you would be interested in including this in the project or if we'd rather fork it for internal purposes.

    Thanks!

    opened by real34 4
  • Feature suggestion: Syncing public github comments

    Feature suggestion: Syncing public github comments

    Why?

    It would be amazing to sync public github conversations to be visible inside Linear. Today the comments in linear are a bit weird because they only reflect core team conversations and missing community comments.

    How?

    Not sure exactly how best to implement but had in mind two ways:

    • Using an existing users as a commenter in Linear and add an annotation in the comment that will link to the real commenter github page
    • Somehow use the integration account (similar to the one opening the issues in Triage today)
    opened by scopsy 2
  • sync does not work from linear team -> github

    sync does not work from linear team -> github

    Hi,

    somehow the sync only works in one direction for me at the moment (github -> linear). When I make changes on github they appear in linear but not vice-versa. I.e. any change (such as a comment, marking an issue with Public etc.) on linear does not lead to a change on github.

    See below the involved repos: image

    The linear webhook appears to be there as well:

    image image
    opened by geekflyer 1
  • Sync milestones

    Sync milestones

    Summary

    • 1:1 sync of Linear projects and GitHub milestones
    • Works 2-way for creation and updating of title, description, and state

    Test Plan

    • Create Linear project in synced team. Ensure milestone is created with same title, description, open state (unless cancelled or completed), and link in footer.
    • Edit Linear project title, description, and state. Ensure milestone is synced.
    • Create GH milestone in synced repo. Ensure Linear project is created with same title, description, and backlog state.
    • Edit milestone title, description, and state. Ensure project reflects changes.

    TODO:

    • [ ] Auto-update webhooks for milestone/project events
    • [ ] Synced ticket added to synced project <> synced milestone assigned to synced issue

    Related Issues

    #5

    enhancement 
    opened by tedspare 8
  • Incorrect display of user with certain actions taken

    Incorrect display of user with certain actions taken

    This is a bug report and also a feature request.

    Some things I've noticed while testing with my team is that

    • When a member of my team self-assigned themselves to a Linear issue, it showed that I assigned them on GitHub, which is untrue.
    • When a member of my team closed a Linear issue, it showed that I close the issue on GitHub, which is untrue.
    • I've noticed that the <username> on Linear footer text is omitted presumably by design, my feature request is that this isn't the case, as it does help to see the source of comments. [See image below]

    image

    Thanks again!

    bug 
    opened by Codeize 3
  • Organization wide sync

    Organization wide sync

    Can we sync the whole organization instead of individual repos? That way we can use Linear as a "central command" for our mix of public and private repos.

    later 
    opened by zomars 6
Owner
Cal.com, Inc.
Scheduling infrastructure for absolutely everyone.
Cal.com, Inc.
This project is an attempt at recreating the WebGL animation featured in the 2021 Linear release page.

Linear Vaporwave Three.js scene This project is an attempt at recreating the WebGL animation featured in the 2021 Linear release page. Demo Head over

Maxime Heckel 31 Dec 28, 2022
Sync pages from Notion to GitHub to be used as a static website (JAM)

notion-jam Sync pages from Notion to GitHub to be used as a static website (JAM) Usage Quick Start Create a new Notion Integration Add Notion secret t

Victor 9 Nov 15, 2022
A CloudFlare Worker / script / bot to sync Notion pages publicly as GitHub Discussions.

notion-github-sync This bot syncs public Notion pages as GitHub Discussions/Issues. It's done periodically, based on the pages shared with the Notion

The Guild 20 Dec 22, 2022
A modern ebook manager and reader with sync and backup capacities for Windows, macOS, Linux and Web

简体中文 | English Koodo Reader A cross-platform ebook reader Download | Preview | Roadmap | Document Preview Feature Format support: EPUB (.epub) Scanned

Troye Guo 8.6k Dec 29, 2022
Argon - extension for VS Code and plugin for Roblox allowing easy two-way sync of code and instances

About Argon is a simple two-way sync plugin for Roblox and extension for Visual Studio Code allowing developers not only to sync code but every possib

DARK 16 Dec 29, 2022
Get a diff view of your Obsidian Sync, File Recovery and Git version history

Version History Diff (for Sync and File Recovery Core plugins and Git) Note This plugin uses private APIs, so it may break at any time. Use at your ow

null 39 Dec 26, 2022
A simple in-memory key-value cache for function execution, allowing both sync and async operations using the same methods

A simple in-memory key-value cache for function execution, allowing both sync and async operations using the same methods. It provides an invalidation mechanism based both on exact string and regex.

cadienvan 10 Dec 15, 2022
This tool allows you to test your chains.json file to see if your chains are available, syncing, or in sync.

Chains Tester This tool allows you to test your chains.json file to see if your chains are available, syncing, or in sync. This is an open source tool

Jorge S. Cuesta 9 Nov 4, 2022
Obsidian plugin to sync Pinboard.in links to Daily Notes

Obsidian Pinboard Sync An Obsidian plugin that adds links you've saved with Pinboard to your Obsidian Daily Notes, synchronizing periodically. Why? I'

Mathew Spolin 35 Dec 1, 2022
Obsidian.md plugin to sync highlights/notes from koreader

Obsidian KOReader Plugin Sync KOReader notes in your Obsidian vault. The KOReader device must be connected to the device running obsidian to let the p

Federico Granata 24 Dec 18, 2022
Sync your personal calendar to your work calendar, privately 🐒

Callibella ?? It is considered unusual among Callibella in that it gives birth to only a single baby instead of twins, the norm for Callibella. Wikiep

Yo'av Moshe 19 Oct 12, 2022
🔂 Send patches around to keep the system in sync.

The core idea is to use patches to keep the UI in sync between client and server, multiple clients, or multiple windows. It uses Immer as an interface

Webstudio 27 Sep 15, 2022
A CLI tool to make Taobao's npm mirror sync your package immediately.

npm-mirror-sync A CLI tool to make Taobao's npm mirror sync your package immediately. 让淘宝的 NPM 镜像立即收录你的包的新版本。 背景 相信国内小伙伴都在用淘宝的 NPM 镜像(npmmirror.com)作为

CSS魔法 10 Jun 9, 2022
Obsidan Plugin: Simpread annote sync

描述 SimpRead.Unreader.Sync.mp4 安装此插件后,在简悦中加入稍后读 / 标注(包括:新增或更新)均可实时同步到 Obsidian 库相应的文件夹中。(每个稍后读(标注)对应一个 Markdown 文件) 意义 通常在 Web 标注的话,大多需要这样的操作步骤:标注后 → 复

Kenshin Wang 26 Dec 28, 2022
🍎 A simple application which enables you to sync readings from your Withings scale to a Notion page.

weight-logger weight-logger is a simple application which enables you to sync readings from your Withings scale to a Notion page. Preview Installation

Juri Adams 2 Jan 14, 2022
Lip-sync VRM avatar client for zero-webcam mic-based vtubing

VU-VRM A lip-sync VRM avatar client for zero-webcam mic-based vtubing: automattic.github.io/VU-VRM/ Why? Because multitasking. Because sometimes you n

Automattic 10 Oct 19, 2022
Markdown note maker (with Git sync) using Tauri.

Mediocre Markdown note maker (with Git sync) using Tauri. Screens Tech Stack Frontend Monaco Editor for the editor interface Chakra UI library Redux T

Nilay Savant 14 Dec 6, 2022
Recoil Sync stores for Next.js

recoil-sync-next Recoil Sync stores for Next.js Features URL Persistence Syncing an atom with the browser URL. Session Storage Persistence Synced with

Recruit Co., Ltd. 47 Dec 28, 2022
Tries to execute sync/async function, returns a specified default value if the function throws

good-try Tries to execute sync/async function, returns a specified default value if the function throws. Why Why not nice-try with it's 70+ million do

Antonio Stoilkov 14 Dec 8, 2022