{"id":20145122,"url":"https://github.com/terrastruct/byelinear","last_synced_at":"2025-04-09T19:18:00.496Z","repository":{"id":64298359,"uuid":"536225946","full_name":"terrastruct/byelinear","owner":"terrastruct","description":"Export Linear issues including assignees, comments, labels, linked issues/PRs and projects to GitHub issues.","archived":false,"fork":false,"pushed_at":"2025-03-05T21:12:51.000Z","size":12983,"stargazers_count":12,"open_issues_count":0,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-09T19:17:54.846Z","etag":null,"topics":["automation","github","go","issues","linear-app","script"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/terrastruct.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-09-13T16:58:32.000Z","updated_at":"2025-03-17T15:20:48.000Z","dependencies_parsed_at":"2024-06-19T23:05:05.152Z","dependency_job_id":null,"html_url":"https://github.com/terrastruct/byelinear","commit_stats":{"total_commits":62,"total_committers":3,"mean_commits":"20.666666666666668","dds":0.4838709677419355,"last_synced_commit":"31192ee14eb832343083c84b0420662c642ef598"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/terrastruct%2Fbyelinear","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/terrastruct%2Fbyelinear/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/terrastruct%2Fbyelinear/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/terrastruct%2Fbyelinear/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/terrastruct","download_url":"https://codeload.github.com/terrastruct/byelinear/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248094989,"owners_count":21046770,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","github","go","issues","linear-app","script"],"created_at":"2024-11-13T22:14:23.148Z","updated_at":"2025-04-09T19:18:00.447Z","avatar_url":"https://github.com/terrastruct.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# byelinear\n\n[![ci](https://github.com/terrastruct/byelinear/actions/workflows/ci.yml/badge.svg)](https://github.com/terrastruct/byelinear/actions/workflows/ci.yml)\n[![daily](https://github.com/terrastruct/byelinear/actions/workflows/daily.yml/badge.svg)](https://github.com/terrastruct/byelinear/actions/workflows/daily.yml)\n[![license](https://img.shields.io/github/license/terrastruct/byelinear?color=9cf)](./LICENSE)\n\n`byelinear` exports Linear issues including assignees, comments, labels, linked issues/PRs and projects to GitHub issues.\n\nWhile we enjoyed Linear's slick UI and superior featureset, we ultimately decided that we\nwanted our issues on the same platform with the rest of our development. GitHub issues\naren't perfect but they work well enough for us and are more tightly integrated with\nGitHub. So we wrote this for our internal migration from Linear issues to GitHub issues.\n\nbyelinear uses the Linear GraphQL API and the GitHub V3 and V4 APIs.\n\n\u003c!-- toc --\u003e\n- \u003ca href=\"#install\" id=\"toc-install\"\u003eInstall\u003c/a\u003e\n- \u003ca href=\"#configuration\" id=\"toc-configuration\"\u003eConfiguration\u003c/a\u003e\n- \u003ca href=\"#caveats\" id=\"toc-caveats\"\u003eCaveats\u003c/a\u003e\n  - \u003ca href=\"#issues-order\" id=\"toc-issues-order\"\u003eIssues order\u003c/a\u003e\n  - \u003ca href=\"#resumption\" id=\"toc-resumption\"\u003eResumption\u003c/a\u003e\n  - \u003ca href=\"#projects\" id=\"toc-projects\"\u003eProjects\u003c/a\u003e\n- \u003ca href=\"#example\" id=\"toc-example\"\u003eExample\u003c/a\u003e\n  - \u003ca href=\"#before\" id=\"toc-before\"\u003eBefore\u003c/a\u003e\n  - \u003ca href=\"#after\" id=\"toc-after\"\u003eAfter\u003c/a\u003e\n- \u003ca href=\"#related\" id=\"toc-related\"\u003eRelated\u003c/a\u003e\n\n## Install\n\n```sh\n$ go install oss.terrastruct.com/byelinear@latest\n$ byelinear --help\nusage:\n        byelinear [ from-linear | to-github ]\n\nUse from-linear to export issues from linear and to-github to export issues to github.\nSee docs and environment variable configuration at https://oss.terrastruct.com/byelinear\n```\n\nSee configuration to setup the required environment variables. Then see the example below\nfor how to run and what the logs look like.\n\n## Configuration\n\n```sh\n# Location of corpus for issues fetched from Linear.\n# Defaults to linear-corpus in the current directory.\nexport BYELINEAR_CORPUS=\n\n# Use to fetch and export only a single issue by the linear issue number. Useful for testing.\nexport BYELINEAR_ISSUE_NUMBER=\n\n# org/repo into which to import issues.\n# Required when running to-github.\nexport BYELINEAR_ORG=terrastruct\nexport BYELINEAR_REPO=byelinear\n\n# Secrets required when importing/exporting with private repos/issues.\nexport GITHUB_TOKEN=\nexport LINEAR_API_KEY=\n```\n\n## Caveats\n\n### Issues order\n\nbyelinear fetches Linear issues in reverse so that the most recent issue is created last\nand thus shows up first in GitHub issues.\n\n### Resumption\n\n#### from-linear\n\nIf you have thousands of issues and hit a rate limit or something goes wrong, know that\n`byelinear from-linear` stores all fetched issues on the disk in\n`./linear-corpus/\u003cissue-identifier\u003e.json`. You can ctrl+c and resume later and `byelinear\nfrom-linear` will know to start from the last fetched issue based on\n`./linear-corpus/state.json`.\n\nYou can change the corpus directory with `$BYELINEAR_CORPUS`.\n\n#### to-github\n\nIf something goes wrong when exporting to github and you ctrl+c, you can resume but you\nmight end up with an incomplete but also duplicate issue. To avoid this, first check your\nrepo to see the last created issue and ensure the state in the comment/linear matches the\ngithub state. Mainly labels, projects and comments. Make any changes you need to to make\nit match. Then go into `./linear-corpus/state.json` and ensure `\"exported_to_json\":true`.\n\nNow you can restart.\n\nIn fact I now realize you might also end up with duplicate issues if say the request to\nadd your issue to a project fails. Or to create a comment. to-github's retry loop is\naround recreating the issue again and redoing everything instead of around every\nindividual API request.\n\nIn the future to-github should be improved to allow seamless resumption by storing state\nabout each successfully completed operation in the state.json instead of just the issue\nas a whole.\n\nFor now, it's best that once you start, you let it export every issue to GitHub.\n\n### Projects\n\nbyelinear gets everything right except for projects and state as there are limitations in\nGitHub's project API. There is no way to add a new project state/column programatically so\nit tries to map incoming states to GitHub default states as best as possible.\n\ne.g. In Review from Linear becomes In Progress on GitHub. Cancelled becomes Done.\n\nAs well, GitHub's projects API does not allow for control over workflow automations like\nautomatically setting an issue to In Progress when a PR is opened for it. You'll have to\nmanually go into the projects settings and enable the workflows there.\n\n## Example\n\nThe following example fetches issue TER-1396 from linear and then exports it to GitHub.\nEmpty `$BYELINEAR_ISSUE_NUMBER` to fetch all issues.\n\n```\n$ BYELINEAR_ISSUE_NUMBER=1396 LINEAR_API_KEY=lin_api_... go run . from-linear\n2022/09/15 12:44:09 fetching 1396\n2022/09/15 12:44:10 fetched 1396\n```\n\n```\n$ BYELINEAR_ISSUE_NUMBER=1396 GITHUB_TOKEN=ghp_... BYELINEAR_ORG=terrastruct BYELINEAR_REPO=byelinear-test go run . to-github\n2022/09/15 12:44:49 TER-1396: exporting\n2022/09/15 12:44:49 TER-1396: ensuring label: backend\n2022/09/15 12:44:49 TER-1396: ensuring label: easy\n2022/09/15 12:44:49 TER-1396: ensuring label: blocked\n2022/09/15 12:44:50 TER-1396: ensuring label: dsl\n2022/09/15 12:44:50 TER-1396: creating\n2022/09/15 12:44:51 TER-1396: creating comment 0\n2022/09/15 12:44:52 TER-1396: creating comment 1\n2022/09/15 12:44:52 TER-1396: ensuring project: D2\n2022/09/15 12:44:54 TER-1396: exported: https://github.com/terrastruct/byelinear-test/issues/3\n```\n\n### Before\n\n![linear](./TER-1396-linear.png)\n\n### After\n\n![github](./TER-1396-github.png)\n\n## Related\n\n- [https://github.com/jccr/linear-to-gitlab](https://github.com/jccr/linear-to-gitlab)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fterrastruct%2Fbyelinear","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fterrastruct%2Fbyelinear","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fterrastruct%2Fbyelinear/lists"}