github-linear-bridging
Skill13 starsChanged 21 days agoMITView on GitHub
Conventions for bridging GitHub and Linear: creating Linear issues from GitHub issues, cross-referencing the two trackers, and checking whether a GitHub issue is already tracked in Linear. Load when asked to create Linear issues from GitHub issues, link the trackers in either direction, or report tracking status. Not needed for work that stays inside one tracker.
2 other projects use a version of this.
Adopted by
Most recently taken up by
- getsentry/software-factoryword for word, first seen Oct 25, 2026
- vercel-labs/eve-software-factory-templateword for word, first seen Oct 13, 2026
Other versions2 projects use a version of this.
Word for word · 2
- vercel-labs/eve-software-factory-template★ 1.2k100% same
- getsentry/software-factory★ 0100% same
Edited · 0
None found.
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository5 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- digest-formatSkill
- triaging-issuesSkill
- writing-qualitySkill
The file
We split this skill into the rules it gives an agent
8 rules. About 0 are common, 8 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈8
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 10
Before creating a Linear issue for a GitHub issue, search Linear for it.
- Distinctive: line 12
If a match exists, don't create a duplicate.
- Distinctive: line 13
If the match is uncertain (similar title, no explicit reference), say what you found and ask before creating anything.
- Distinctive: line 24
If the user's stored preferences include a default Linear team, use it.
- Distinctive: line 26
If the user states a lasting default while answering ("always use the Platform team"), persist it as a preference so you don't ask again.
- Distinctive: line 36
Don't sync labels wholesale.
- Distinctive: line 37
Don't mirror every comment or status change.
- Distinctive: line 38
When a bridged issue closes on one side, note it on the other only when the user asks or the workflow they described calls for it.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
GitHub to Linear Bridging
Rules for carrying a GitHub issue into Linear and keeping the two sides pointing at each other. The goal is one clear Linear issue per GitHub issue, findable from either end, with no duplicate tracking and no noise copied across.
Check for an existing Linear issue first
Before creating a Linear issue for a GitHub issue, search Linear for it. Search by the GitHub issue number (for example "#42"), the issue title, and the GitHub issue URL; any of the three may appear in an existing Linear issue's title, description, or comments.
- If a match exists, don't create a duplicate. Report the existing Linear issue with its link and current status, and add the GitHub link to it if it's missing.
- If the match is uncertain (similar title, no explicit reference), say what you found and ask before creating anything.
What a well-formed bridged issue looks like
- Title: carry the GitHub issue's title over, cleaned up if it's vague or noisy. A reader should recognize it as the same issue from either tracker.
- Description: a short summary of the substance, in your own words. State the problem or request, the key facts from the discussion, and any decision or reproduction detail that matters. Never paste the whole GitHub thread.
- Backlink: include the full URL of the GitHub issue in the description, near the top, so the Linear side always leads back to the source.
- Assignee: set the assignee the user asked for. If they named someone you can't resolve in Linear, say so and ask instead of picking someone else or leaving it silently unassigned.
Choosing the Linear team
- If the user's stored preferences include a default Linear team, use it.
- Otherwise ask which team the issue belongs to. Never guess a team from its name, and never pick the first team in the list.
- If the user states a lasting default while answering ("always use the Platform team"), persist it as a preference so you don't ask again.
Cross-link both directions
After creating the Linear issue, the GitHub side should point at it too, when a comment there is appropriate: the requester maintains the repo, or they asked you to note the tracking. Post a short comment on the GitHub issue with the Linear issue's identifier and link, one line, nothing more. Skip the comment when it would be noise, for example on a repo the requester doesn't maintain or when they asked for private tracking; in that case just report the link back to them.
Mirror only meaningful state
The two trackers stay loosely coupled. Carry over what changes decisions, not metadata.
- Don't sync labels wholesale. Mention a label in the summary only when it carries meaning (a severity, a confirmed bug), and only set a Linear label when the user asks for one.
- Don't mirror every comment or status change. When asked for status, read both sides live and report the current state rather than copying updates across.
- When a bridged issue closes on one side, note it on the other only when the user asks or the workflow they described calls for it.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.