Connect the worker to the DevIntern relay for instant PR and task events without webhook setup

Relay (Instant Events)

devintern worker connect pairs your worker with the DevIntern relay. Source webhooks (GitHub, GitLab, 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. The worker connect sentry target shares this integration command namespace but configures a direct local Sentry poller; it does not send Sentry data through the relay.

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",
  "repoId": 987654321,
  "installationId": 12345678,
  "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.

GitLab reference envelopes contain the provider, instance URL, numeric project ID and path, merge-request IID or branch/head SHA when needed, event type, delivery ID, and timestamp. The relay never receives the GitLab API token, code, diffs, discussion text, CI logs, ticket bodies, or agent prompts/output.

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.

GitHub repository registration is completed through the DevIntern AI GitHub App. The CLI prints a short-lived installation URL and waits while GitHub authorizes the App. The relay verifies that the signed-in GitHub user can access the requested repository through that installation before it records anything. Routing then uses GitHub’s immutable installation and repository IDs—not the user-supplied owner/name slug. An installation already associated with another DevIntern account cannot be claimed or overwritten.

The App’s private key never reaches the worker: it fetches referenced PRs/comments and performs GitHub writes with its local GITHUB_TOKEN, so customer-owned GITHUB_APP_ID credentials are ignored in this relay-backed mode.

GitHub connections created before verified pairing was introduced must run devintern worker connect github once again. The command verifies every unpaired GitHub repository listed in the fleet workspace. Old local confirmation markers are not treated as completed setup, while an existing live relay route remains usable during the upgrade.

GitLab registration is different: the CLI uses your local GitLab credential to resolve each project, verify Maintainer or Owner access, create or rotate a named project hook, and trigger GitLab’s hook test endpoint. The GitLab API token stays on your machine. GitLab.com and Self-Managed use the same workflow; a Self-Managed GitLab server only needs outbound HTTPS access to relay.devintern.com. The worker host still needs no inbound port.

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 the workspace .env (from https://devintern.com/account)

# Pair all GitHub and GitLab repositories in the workspace
devintern worker connect

# Authorize any printed GitHub App URLs. GitLab hooks are installed and tested
# automatically when the configured token has Maintainer or Owner access.
devintern worker

The worker detects the workspace pairing and starts the relay connection automatically alongside its normal polling. Both worker init and worker connect store relay state under the workspace home.

For Linear, Asana, Trello, or Azure DevOps, set that tracker’s credentials in the workspace .env or a team’s env_file / inline [teams.env], 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.

For multi-team tracker routing, deploy the team-aware relay control plane before upgrading the CLI. The new CLI detects an older relay and fails team-scoped registration with an actionable error; team-less registration remains compatible in either deployment order.

Commands

In a multi-team workspace, devintern worker connect linear --team growth selects that team’s credential layers and registers the source under that stable team name. If exactly one team uses the requested tracker, --team is optional and the CLI selects it automatically. When several teams use the tracker, --team is required and each team receives a distinct, idempotent ingest URL. The flag is invalid for GitHub, GitLab, and status because those targets are workspace-wide.

Team-aware task.changed envelopes route only to the exact tracker and team pair, even when two boards contain the same task key. Events for unknown or removed teams are logged, skipped, and acknowledged so they cannot stall the stream. Older buffered envelopes have no team tag and retain the legacy source-only path: they run only when the tracker maps to one unambiguous workspace source. GitHub PR envelopes are unchanged.

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. Re-registering the same tracker/team keeps its URL; registering another team creates a separate URL.

worker connect stores the shared pairing under the workspace home in owner-only .devintern-code/relay.json. It skips repositories whose immutable GitHub repository IDs are already verified and continues when one GitHub or GitLab project fails. GitLab signing values are one-time setup material and are never written to this state file. Tracker connect uses the selected team’s credential layers when applicable; otherwise it reads the workspace .env with explicit shell variables taking precedence.

Environment variables

Always

Per worker connect target

Set code-host credentials in the workspace or per-repository environment. Tracker targets use the same credentials you already use for that tracker: set them in the workspace .env, or use --team <name> to compose that team’s env_file and inline env. Shared .env files may namespace credentials as <TRACKER>_<TEAM>_<SETTING>; for example, JIRA_PLATFORM_URL, JIRA_PLATFORM_EMAIL, and JIRA_PLATFORM_API_TOKEN become the normal Jira settings for team platform. Team names are uppercased and non-alphanumeric characters become _. A team’s env_file and inline env still take precedence. GitHub connect uses every unpaired GitHub repository in workspace.toml. Jira connect mints the ingest URL and prints admin setup steps without calling the Jira API.

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 the exact team’s configured query (or [defaults].task_query for a team-less workspace) before acting, so “ready” still means whatever your query says.
• GitLab discussion, MR, pipeline, and failed-job events are hints only. The worker matches an exact registered project/MR and re-fetches authoritative state with its local token before acting.
• 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). GitHub uses the DevIntern Relay App; GitLab, Linear, Asana, Trello, and Azure DevOps self-register with your own local credentials; Jira uses a one-time admin webhook setup. Markdown tasks are local files and need no relay. Every integration also keeps working with plain polling if you prefer no DevIntern infrastructure at all.