Skip to content

relay.md

Latest commit

 

History

History
133 lines (93 loc) · 9.05 KB

relay.md

File metadata and controls

133 lines (93 loc) · 9.05 KB
Raw
title Relay (Instant Events)
description Connect the worker to the DevIntern relay for instant PR and task events without webhook setup
section Server Automation
order 3
dateModified 2026-08-04

Relay (Instant Events)

devintern worker connect pairs your worker with the DevIntern relay. Source webhooks (GitHub, Linear, Asana, Trello, Azure DevOps, Jira) reach DevIntern's ingest, are stripped down to reference envelopes, and your worker picks them up within seconds instead of waiting for the next poll. No public endpoint on your side, no tunnels.

What the relay sees (and what it never sees)

An envelope is a reference, not a payload:

{
  "source": "github",
  "eventType": "pr.review_submitted",
  "repo": "acme/webapp",
  "ref": { "pr": 142 },
  "deliveryId": "gh-delivery-uuid",
  "ts": "2026-07-03T10:00:00Z"
}

Explicitly excluded: diffs, file contents, ticket bodies, comment text, and credentials of any kind. When your worker receives an envelope, it fetches the real data directly from GitHub or your tracker using your own local credentials, and everything executes on your machine as usual.

If the relay is unreachable, nothing breaks: the worker's regular polling keeps running as a fallback, so relay downtime affects latency only, never correctness.

How authentication works

Connect is an interactive step. The default devintern worker init flow offers sign-in, registers GitHub plus the active tracker, and stores the workspace's durable pairing under ~/.devintern/. The relay verifies the session and your automation entitlement, then mints a durable relay token (drt_…). The worker uses that token for /v1/status and /v1/events long-polls, so polling survives session rotation, logouts, and password changes.

LICENSE_KEY is still required for the local unattended license gate when you run devintern worker (same as polling mode without the relay). It is not the credential the relay data plane accepts.

Tracker webhooks never hit your machine. Self-register commands call the tracker API from your laptop with your own API keys, pointing the callback at a private per-customer ingest URL on the relay.

Signing in over SSH or mosh

Browser OAuth redirects to http://127.0.0.1:<port>/auth/callback on the machine where the CLI is running. Over SSH/mosh there is no local GUI, and opening the URL on your laptop hits your laptop's loopback — not the remote process.

Preferred (works with mosh): sign in on a machine with a browser, then copy the session file:

# on your laptop
devintern login
scp .devintern-code/.auth-session.json user@host:/path/to/project/.devintern-code/

Then re-run worker init / worker connect on the remote host (it will see you as signed in).

SSH tunnel alternative: remote login binds a stable callback port (17865, or DEVINTERN_AUTH_CALLBACK_PORT). From your laptop:

ssh -N -L 17865:127.0.0.1:17865 user@host
# open the printed OAuth URL in your laptop browser

Mosh cannot forward TCP — use ssh for the tunnel, or the session-copy path above.

Quick Start

# Sign in (interactive connect step)
devintern login

# Automation license for the worker daemon
# Set LICENSE_KEY in .devintern-code/.env (from https://devintern.com/account)

# Pair this repo for GitHub App delivery
devintern worker connect

# Then install the DevIntern AI GitHub App on the repository when prompted,
# and run the worker as usual:
devintern worker

The worker detects the pairing and starts the relay connection automatically alongside its normal polling. worker init stores workspace pairing under the workspace home; standalone worker connect stores single-repo pairing in .devintern-code/relay.json.

For Linear, Asana, Trello, or Azure DevOps, set that tracker's credentials in .devintern-code/.env first (same vars as TASK_TRACKER=…), then run the matching connect command below. Jira needs no extra Jira env for registration: connect prints a private ingest URL for one-time admin webhook setup.

Commands

Command Description
devintern worker connect Register this repository for relay delivery (auto-detects the GitHub repo)
devintern worker connect github --repo owner/name Register a specific repository
devintern worker connect linear Self-register a Linear webhook for Issue events
devintern worker connect asana Self-register an Asana webhook for task events
devintern worker connect trello Self-register a Trello webhook for card events
devintern worker connect azure-devops Self-register work item service hooks
devintern worker connect jira Print the one-time Jira admin webhook setup with your private ingest URL
devintern worker connect status Show registrations, buffered events, and per-source freshness

Linear deliveries are verified with a signing secret generated on your machine. Asana deliveries are verified with the hook secret from Asana's registration handshake. Trello, Azure DevOps, and Jira deliveries carry no usable signature, so their authentication is the unguessable ingest URL itself: keep it secret, and re-run connect to rotate it.

Environment variables

Always

Variable Required Description
(signed-in session) Connect Run devintern login before worker connect. Session lives in .devintern-code/.auth-session.json
LICENSE_KEY Worker Automation license for unattended devintern worker runs (local license gate)
WORKER_RELAY_URL No Relay base URL override (default: https://relay.devintern.com)

Per worker connect target

These are the same credentials you already use for that tracker. Set them in .devintern-code/.env before running the matching connect command. GitHub connect only needs a detectable git remote (or --repo); Jira connect mints the ingest URL and prints admin setup steps (no Jira API call from the CLI).

Target Required env vars Notes
github (none beyond login + LICENSE_KEY for the worker) Repo from git remote, or --repo owner/name
linear LINEAR_API_KEY Creates the Linear webhook pointing at your relay ingest URL
asana ASANA_API_TOKEN, ASANA_DEFAULT_PROJECT_GID Webhook scoped to that project; Asana handshakes with the relay
trello TRELLO_API_KEY, TRELLO_API_TOKEN, TRELLO_DEFAULT_BOARD_ID Webhook scoped to that board
azure-devops AZURE_DEVOPS_ORG, AZURE_DEVOPS_PAT, AZURE_DEVOPS_PROJECT Creates work item create/update service hooks
jira (none for registration) Paste the printed ingest URL into Jira admin webhooks

Running the worker against those trackers still needs the usual TASK_TRACKER=… credentials so the agent can fetch ticket bodies locally after an envelope arrives. Markdown tasks are local files and need no relay.

How events are handled

  • Reviews submitted on the agent's own PRs are addressed automatically, same as polling mode.
  • New PR comments are checked for a @devintern-ai mention; the same permission gate applies (only users with push access can direct the agent).
  • Tracker task events re-run your configured [defaults].task_query before acting, so "ready" still means whatever your query says.
  • Every envelope is deduplicated against the worker's local database, so relay delivery and fallback polling never double-run work.

Availability

The relay requires an automation license (solo supporter, team subscription, or legacy server addon). All sources are supported: GitHub (via the DevIntern Relay App), Linear, Asana, Trello, and Azure DevOps self-register with your own credentials, and Jira uses a one-time admin webhook setup. Markdown tasks are local files and need no relay. Every tracker also keeps working with plain polling if you prefer no DevIntern infrastructure at all.