Pylon To Linear Bridge

The Pylon to Linear bridge is a Cloudflare Worker in pylon-linear-bridge/. It automates feature-request creation in Linear while keeping Pylon as the source of the customer conversation.

Why It Exists

Pylon's native Linear integration supports manual Linear issue creation from the sidebar. It does not let Pylon triggers create Linear issues automatically.

The bridge fills that gap:

• Receives a Pylon webhook.
• Creates a Linear issue.
• Routes it to the correct Linear team by tms_module.
• Uploads Pylon attachments into Linear-owned storage.
• Links the Linear issue back to Pylon.
• Lets Pylon's native Linear sync handle downstream status/comment sync.

Scenarios Covered

The Worker itself does not decide which issue types should create Linear work. Pylon triggers own that decision and send only the matching events to the Worker.

Known documented use:

Scenario	Trigger owner	Result
New Feature Request issue created in Pylon	Pylon trigger filtered by request type/module	Worker creates a routed Linear issue and links it back to Pylon.

Additional scenarios can be enabled by adding Pylon triggers that point to the same Worker URL. For example, FreightTiger can choose to forward selected bug classes or module-specific escalations, but that should be explicit in Pylon trigger conditions so routine support tickets do not flood Linear.

Trigger inventory needed

The exact live Pylon trigger list was not exported into this repository. Before FreightTiger takes over hosting, export or screenshot the Pylon trigger conditions and destinations and add them to this page.

Flow

1. Pylon trigger fires on issue creation for the selected request type.
2. Trigger sends JSON to the Worker.
3. Worker verifies X-Pylon-Webhook-Secret.
4. Worker calls Pylon and checks whether the issue already has a Linear external issue.
5. Worker claims a Cloudflare KV key using pylon_issue_id.
6. Worker immediately returns 200 { accepted: true } to Pylon.
7. Worker creates the Linear issue in the background.
8. Worker resolves Linear team from MODULE_TEAM_MAP, falling back to LINEAR_TEAM_ID.
9. Worker uploads each Pylon attachment to Linear.
10. Worker posts the Linear external issue back into Pylon.

Required Secrets

Secret	Purpose
PYLON_WEBHOOK_SECRET	Shared secret matching the Pylon webhook destination header.
PYLON_API_TOKEN	Pylon API token for issue lookup, attachment download, and external issue linking.
LINEAR_API_KEY	Linear API key for issue creation and file upload.

Worker Config

Variable / binding	Purpose
LINEAR_TEAM_ID	Default Linear team id, used when module mapping is missing.
LINEAR_LABEL_IDS	Optional comma-separated Linear label ids.
MODULE_TEAM_MAP	JSON object mapping Pylon tms_module values to Linear team ids.
DEDUP	Cloudflare KV namespace used as a short-lived dedup claim store.

Pylon Webhook Body

{
  "pylon_issue_id": "{{ issue.id }}",
  "title": "{{ issue.title }}",
  "body_html": "{{ issue.body_html }}",
  "issue_type": "{{ issue.custom_field.tms_request_type }}",
  "module": "{{ issue.custom_field.tms_module }}",
  "issue_url": "{{ issue.link }}",
  "account_name": "{{ issue.account.name }}",
  "requester_email": "{{ issue.requester.email }}",
  "attachment_urls": "{{ issue.body.attachment_urls }}"
}

Required fields: pylon_issue_id, title.

Duplicate Protection

The Worker uses two layers:

Guard	Purpose
Pylon external-issue check	Durable guard. If the Pylon issue is already linked to Linear, skip creation.
KV dedup claim	Race guard. Prevents concurrent or retried webhook deliveries from creating duplicate Linear issues before the backlink exists.

Fast acknowledgement prevents Pylon retry storms caused by slow attachment upload.

Failure Behavior

Failure	Behavior
Secret mismatch	Return 401; no Linear issue created.
Existing Linear link	Return skipped response; no duplicate issue created.
KV read/write failure	Fail open; Pylon external-issue check remains the durable backstop.
Linear create failure	Return/create error and release KV claim so a later trigger can retry.
Attachment upload failure	Linear issue still created and linked; per-file failures are logged.
Pylon link failure	Linear issue exists without Pylon backlink; KV claim remains for TTL to reduce near-term duplicate risk. Manual remediation required.

Testing

From pylon-linear-bridge/:

npm test

The tests cover signature verification, Worker behavior, module routing, attachment upload, idempotency, and failure paths.

Codebase

File	Purpose
pylon-linear-bridge/src/index.ts	Worker request handling, dedup, Linear create, attachment upload, Pylon backlinking.
pylon-linear-bridge/src/verify.ts	Shared-secret verification.
pylon-linear-bridge/wrangler.toml	Cloudflare Worker name, KV binding, vars, and module-team map.
pylon-linear-bridge/test/*.test.ts	Worker and verification tests.

Modify And Host Anywhere

The Worker is Cloudflare-first but portable in concept: it is just an HTTP POST endpoint that verifies a secret, calls Pylon, calls Linear, and returns JSON.

Cloudflare Workers

cd pylon-linear-bridge
npm install
npx wrangler kv namespace create DEDUP
npx wrangler kv namespace create DEDUP --preview
npx wrangler secret put PYLON_WEBHOOK_SECRET
npx wrangler secret put PYLON_API_TOKEN
npx wrangler secret put LINEAR_API_KEY
npm test
npx wrangler deploy

Other Hosts

To host elsewhere:

1. Keep the same POST contract and X-Pylon-Webhook-Secret check.
2. Replace Cloudflare KV with Redis, Postgres, DynamoDB, Durable Object, or another short-lived dedup store.
3. Keep the durable Pylon external-issue check.
4. Preserve module-to-team mapping.
5. Preserve attachment upload behavior if screenshots/files must survive Pylon signed URL expiry.
6. Update the Pylon webhook destination URL to the new host.

Shutdown Plan

Once FreightTiger deploys this Worker in their own infrastructure and updates Pylon webhook destinations, implementation-owned Workers should be shut down to avoid duplicate Linear issue creation.