Linear Collector
Extract Linear ticket references from pull request titles, validate them against the Linear GraphQL API, and detect ticket reuse across PRs.
linear to your lunar-config.yml:uses: github://earthly/lunar-lib/collectors/linear@v1.0.0
What This Integration Collects
This integration includes 2 collectors that gather metadata from your systems.
ticket
Extracts Linear ticket ID from PR title, fetches issue metadata from the Linear GraphQL API, and writes normalized ticket data to .vcs.pr.ticket and native Linear data to .vcs.pr.ticket.native.linear.
ticket-history
Queries the Lunar SQL database to count how many other PRs reference the same ticket. Writes .vcs.pr.ticket.reuse_count for policy evaluation. Detects ticket recycling abuse.
How Collectors Fit into Lunar
Lunar watches your code and CI/CD systems to collect SDLC data from config files, test results, IaC, deployment configurations, security scans, and more.
Collectors are the automatic data-gathering layer. They extract structured metadata from your repositories and pipelines, feeding it into Lunar's centralized database where guardrails evaluate it to enforce your engineering standards.
Learn How Lunar Works →Example Collected Data
This collector writes structured metadata to the Component JSON. Here's an example of the data it produces:
{
"vcs": {
"pr": {
"ticket": {
"id": "ENG-123",
"source": { "tool": "linear", "integration": "api" },
"url": "https://linear.app/acme/issue/ENG-123/add-payment-validation",
"valid": true,
"status": "In Progress",
"type": "bug",
"summary": "Add payment validation",
"assignee": "jane@acme.com",
"reuse_count": 0,
"native": {
"linear": {
"id": "abc123",
"identifier": "ENG-123",
"title": "Add payment validation",
"url": "https://linear.app/acme/issue/ENG-123/add-payment-validation",
"state": { "name": "In Progress", "type": "started" },
"assignee": { "email": "jane@acme.com", "displayName": "Jane" },
"labels": { "nodes": [{ "name": "bug" }] },
"priority": 2,
"priorityLabel": "High",
"team": { "key": "ENG", "name": "Engineering" }
}
}
}
}
}
}Configuration
Configure this collector in your lunar-config.yml.
Inputs
| Input | Required | Default | Description |
|---|---|---|---|
ticket_prefix
|
Required | — | Character(s) before the ticket ID in PR titles (empty = match anywhere) |
ticket_suffix
|
Required | — | Character(s) after the ticket ID in PR titles (empty = match anywhere) |
ticket_pattern
|
Optional |
[A-Za-z][A-Za-z0-9]+-[0-9]+
|
Regex pattern for ticket ID (without prefix/suffix) |
type_labels
|
Required | — | Comma-separated label names to treat as issue types (e.g. "bug,feature,chore"). If the Linear issue has a matching label, it is written as .vcs.pr.ticket.type. Empty means no type extraction from labels. |
Secrets
This collector requires the following secrets to be configured in Lunar:
| Secret | Description |
|---|---|
LINEAR_API_KEY
|
Linear personal API key for authentication |
GH_TOKEN
|
GitHub token for reading PR metadata |
Documentation
View on GitHubLinear Collector
Extract Linear ticket references from pull request titles and validate them against the Linear GraphQL API.
Overview
This collector parses PR titles for Linear ticket IDs (e.g. [ENG-123] Fix bug), validates the ticket against the Linear GraphQL API, and writes both normalized ticket data to .vcs.pr.ticket and native Linear data to .vcs.pr.ticket.native.linear. It also detects ticket reuse across PRs by querying the Lunar SQL database.
The normalized .vcs.pr.ticket paths are the same as the Jira collector, so the existing ticket policy works with both issue trackers without any changes.
Collected Data
This collector writes to the following Component JSON paths:
| Path | Type | Description |
|---|---|---|
.vcs.pr.ticket |
object | Normalized ticket reference (id, source, url, valid, status, type, summary, assignee) |
.vcs.pr.ticket.reuse_count |
number | Count of other PRs referencing the same ticket |
.vcs.pr.ticket.native.linear |
object | Full raw Linear GraphQL response |
Collectors
This integration provides the following collectors (use include to select a subset):
| Collector | Description |
|---|---|
ticket |
Extracts ticket ID from PR title and fetches Linear issue metadata |
ticket-history |
Queries Lunar SQL for ticket reuse count across PRs |
Installation
Add to your lunar-config.yml:
collectors:
- uses: github://earthly/lunar-lib/collectors/linear
on: ["domain:your-domain"]
with:
type_labels: "bug,feature,chore,improvement"
Required secrets:
LINEAR_API_KEY— Linear personal API key (Settings → API → Personal API keys)GH_TOKEN— GitHub token for reading PR metadata
Linear has no native "issue type" field. The type_labels input lets you specify label names (e.g. bug,feature,chore) that should be treated as types. If a matching label is found on the issue, it is written to .vcs.pr.ticket.type. The Linear GraphQL API returns the full issue URL, so no base URL input is needed (unlike the Jira collector). Linear uses TEAM-NUMBER identifiers (e.g. ENG-123), which match the same default regex as Jira.
Open Source
This collector is open source and available on GitHub. Contribute improvements, report issues, or fork it for your own use.
Common Use Cases
Explore guardrails that use data from Linear Collector.
Ready to Automate Your Standards?
See how Lunar can turn your engineering wiki, compliance docs, or postmortem action items into automated guardrails with our 100+ built-in guardrails.
Infrastructure conventions
Post-mortem action items
Security & compliance policies
Testing & quality requirements