ADR-0042: Disconnecting, reconnecting, and rotating a source, and showing its health
- Status: Accepted
- Date: 2026-11-11
- Amended: 2026-11-16, for rotating and reconnecting a Linear source; see the amendment. The question it left open was settled on 2026-11-19 by ADR-0018's amendment
- Amends: ADR-0002, whose secret rotation and replacement were left to a later workflow; ADR-0016, for when a repository belongs to one Project and when an import may start; ADR-0017 and ADR-0018, for rotating the secret each one was connected with; and ADR-0019, for when a poll is booked and whose account a Jira token belongs to
- Refers to: ADR-0020, whose GitHub Release action borrows a source's token
Context
A source stays connected for good. docs/implementation-status.md defers disconnecting or
replacing one, rotating a Linear signing secret without reconnecting, and rotation
reminders, and ADR-0002 left secret rotation and replacement to "explicit future
workflows". A team that moves a repository, loses a token, or suspects a leaked webhook
secret can only create a new Project, and loses the old one's history in the process.
It also cannot tell when a source has gone quiet. On 2026-11-01 the dbvault lab's webhooks
pointed at a dead tunnel address from about 02:30 to 15:40 UTC, about 13 hours, and
ReleaseFlow showed nothing: the Projects page has each source's last verified delivery,
but nothing marks it as old, nothing outside that page shows it, and a delivery whose
signature fails is answered 401 webhook_signature_invalid and recorded nowhere. With a
dead address nothing arrives at all, so silence is the only symptom ReleaseFlow can see.
Four facts of the current model decide most of what follows:
- A change is identified by its source.
ChangeIntakerefuses a change whose(source_id, external_id)it already holds, andchanges_source_external_uniquemakes that the rule under concurrency too. A new source ID for the same repository is therefore a new identity: re-running the 90-day import on it records every pull request the old source already recorded, a second time. - Changes point at their source.
changes_source_type_matchesis a foreign key tointegration_sources (id, source_type), so deleting a source would orphan or delete its changes, the releases that contain them, and the folding and duplicate evidence about them. - Ciphertexts are bound to their source. A webhook secret's authenticated data is the
Organization, Project, and source IDs with the repository owner and name for GitHub, or
the type and external key for the others; a token's adds a purpose line. Rewriting any
of those columns makes the secret and the token stop decrypting.
webhook_id,webhook_auth_mode,api_base_url,external_workspace_key,credential_identity, and the schedule are not bound. - The token already rotates.
PUT /api/projects/{projectId}/sources/{sourceId}/tokenhas the provider confirm a new token before it replaces the old one, for all four types, and puts a failing source back in order. What is missing is the rest of the lifecycle around it.
The providers set the limits of a rotation, because a hook is edited by a person, by hand, after ReleaseFlow has already changed its side:
- GitHub does not redeliver a refused delivery on its own. A person can redeliver one from the hook's Recent deliveries for three days.
- GitLab lists a hook's Recent events for two days, each with Resend Request, and disables a hook that fails four times in a row, for a minute at first and up to a day, and for good after 40 failures.
- GitLab clears a hook's secret token (
token, theX-Gitlab-Tokenmode) when its URL changes, a security fix of its own (gitlab-org/gitlab#382260; the warning in the form came with !139865). Its signing token behaved differently on the dbvault lab: a URL-only edit through the hooks API on 2026-10-20 left it in place, and the hook still reportedsigning_token_present: truewhen it was next read, on 2026-11-01. - GitLab's signing token is set on the lab through the hooks API,
urlandsigning_tokenin onePUT, in the Standard Webhooks formwhsec_followed by the standard Base64 of ReleaseFlow's secret; GitLab refuses the secret as ReleaseFlow writes it (lab TESTLOG SRC-6, FINDINGS #1). Its documentation describes the form's Generate signing token, which makes a token in GitLab instead, so what the form accepts typed in is not something to depend on. - Linear retries a refused delivery three times, the last about six hours later. Its documentation shows the signing secret on the webhook's detail page and says nothing of regenerating it. (Amended on 2026-11-16, corrected on 2026-11-18: the lab saw no retry of a delivery ReleaseFlow refused; see the end.)
Decision
Disconnecting
- An administrator disconnects a source; its row stays.
POST /api/projects/{projectId}/sources/{sourceId}/disconnectwritesdisconnected_atanddisconnected_byin one short transaction. The row, its type, its external key, and every bound column are kept, so every change it recorded keeps its source, its history, its reviews, its releases, and its evidence, and the Change Inbox still filters by it. Nothing is called at the provider: ReleaseFlow cannot delete a GitHub hook or revoke a token it was only lent, so the confirmation page and the guide say to delete the hook and revoke the token there. - What it destroys. The same transaction sets
webhook_id,secret_nonce,secret_ciphertext,token_nonce,token_ciphertext, andnext_poll_atto null. The live row then holds nothing that decrypts to a credential; older row versions and backups still hold the ciphertexts until vacuum and backup expiry remove them, which is why the provider-side revocation is part of the guide rather than an optional extra. - Its webhook path answers like an unknown one. With no
webhook_id, the verifier finds no source, so a delivery is answered401 webhook_signature_invalid, exactly as for a path that never existed, and is recorded nowhere: not as a delivery and not as a signature failure. - Polls and imports stop. With no
next_poll_at,JiraPollSchedulernever books a poll. The same transaction ends the source's pending or retrying sync job asFAILEDwithsource_disconnected. A job already running reads its credentials before each provider call, finds none, and ends the same way, so no page is read after the disconnect. A page fetched just before it may still be recorded. - Work that needed the token behaves as if the source had none. A change still being
processed is completed with its files unavailable (
NO_ACCESS_TOKEN), which forces review, as for any source without a token. The lookups of other capabilities —SourceAccess.findByTypefor linked context and issue reads at review,findSolefor the GitHub Release action, the code host behind a note's compare and release links, and the overview's "a source is connected" — count connected sources only. A linked issue whose tracker is disconnected keeps its recorded status, as an issue that could not be read already does (ADR-0041). - Disconnecting is final for that connection, and refused twice. Disconnecting a
disconnected source, or setting its token or secret, or importing into it, answers
409 source_disconnected.
Reconnecting
-
The same repository, project, or team in the same Project is the same source.
POST .../sources/{sourceId}/reconnectbrings a disconnected source back under its own ID, soChangeIntakekeeps recognising every change it recorded: a history import after the reconnect records only what is new, and a redelivery of an old pull request is aduplicate.ChangeIntakeandchanges_source_external_uniquedo not change. -
Reconnecting never changes what the source is. Type, external key, instance, workspace, and Project stay as they were, so no bound column is touched; the new credentials are encrypted afresh under the same authenticated data. What a reconnect takes is what connecting that type takes, minus what identifies it:
Type Reconnect takes ReleaseFlow makes Provider calls GitHub an optional token a new webhook ID and secret, shown once one token check, only if a token is given GitLab an optional token, and for a signed source an optional signing token GitLab generated a new webhook ID, and a secret shown once in the form its mode needs unless one was pasted one project check, only if a token is given Linear the pasted signing secret and an API key a new webhook ID one team(id)query, which must still answer the stored workspaceJira the account email and an API token the next poll, one interval later one project check A new webhook ID means the old path stays dead: a hook nobody updated cannot start delivering again, and a hook pointed at the new path proves itself with the new secret.
-
A Jira source picks up where it stopped. Its cursor stays where its last completed poll left it, moved forward to no earlier than 90 days ago, the window an import reads. The first poll after a reconnect therefore reads what was completed while it was disconnected, and intake drops what it already holds.
-
Connecting the key again is refused in favour of reconnecting. Connecting a repository, project, or team that the same Project holds disconnected answers
409 source_reconnect_requiredand names the source, rather than creating a second identity for it.integration_sources_external_uniquebecomes a unique index over connected sources only, beside a full unique index on Organization, Project, type, and key, so a key is connected in at most one Project of the Organization and held at most once by each Project. -
Another Project may take the key. Once a source is disconnected, a different Project may connect the same repository. That is a new source with its own ID: the old Project keeps its changes, and the new one starts its own record, which its own import may fill. The two Projects do not share changes, because a change belongs to one Project.
-
A renamed or moved repository is a new source. ReleaseFlow cannot prove that two names are one repository without following a redirect, which no client does, and treating them as one on a person's word would silently drop real changes of an unrelated repository with the same numbers. Replacing a source therefore means disconnecting it and connecting the new name; that new source's import records again what the old one recorded under the old name, as new changes, which the possible duplicate check (ADR-0013) and exclusion (ADR-0033) are there to handle. A renamed GitHub repository already announces itself: its deliveries are refused as
webhook_repository_mismatch, which never counts as a delivery, so the source turns quiet below.
Rotating a webhook secret
-
The path stays; the old secret stops at once. Two ways in, by who makes the secret:
POST .../sources/{sourceId}/webhook-secretgenerates one, shown once in ano-storeresponse: GitHub, and GitLab in either mode. For a signed GitLab source the response also carries it assigningToken, in thewhsec_form GitLab's API takes, with the request to send it.PUT .../webhook-secret {"webhookSecret"}stores one the provider made, never echoed: Linear's signing secret, or a signing token GitLab generated for a signed GitLab source, which must bewhsec_followed by Base64 or it is refused with400.- A secret-token GitLab source and a GitHub source only generate, and answer a
PUTwith409 source_secret_generated; Linear only pastes, and answers aPOSTwith409 source_secret_pasted; Jira has no secret and answers both with409 source_has_no_webhook.
Either way the new ciphertext replaces the old under the same authenticated data,
secret_updated_atis set, and the next delivery signed with the old secret is refused. ReleaseFlow does not depend on which of GitLab's forms accepts a typed value: both ways reach the same verifier, which already reads awhsec_secret. -
Why at once, not after an overlap.
- A secret is rotated because someone else may know it. During an overlap, whoever holds the old one can still put a merged pull request of their choosing into the Change Inbox. A delivery that is missed can be recovered; a forged one is indistinguishable from a real one once it is in.
- A missed delivery is recoverable and, with this ADR, visible. The refusal is counted with its time (below), so the gap is on the page. GitHub keeps the refused delivery for three days and GitLab for two, each with a button to send it again; and the 90-day import of either reads the gap through the same intake and records nothing twice.
- An overlap needs a second secret per source, an expiry, and verifiers that try two, and a timed overlap only moves the problem: a person who takes longer than the window loses deliveries anyway, and one who never updates the hook leaves the old secret alive until it expires.
- It is the rule a signed automation trigger already follows (ADR-0021), so a person meets one behaviour.
-
What the page says, for each provider. The page that shows the new secret says exactly where it goes and in which order, and the guide repeats it:
- GitHub: the repository's Settings → Webhooks → the hook → Edit, paste into Secret, Update webhook; the Payload URL does not change. Then Recent deliveries, and Redeliver each delivery refused since the rotation.
- GitLab, signed headers: either send ReleaseFlow's value with the request the page
shows,
PUT /api/v4/projects/<project>/hooks/<hook>withurlandsigning_tokentogether, or select Generate signing token on the hook in GitLab and paste what GitLab shows once into ReleaseFlow. - GitLab, secret token header: the project's Settings → Webhooks → the hook
→ Edit, paste into Secret token, and save; through the hooks API,
urlandtokenin onePUT. - GitLab, either mode: GitLab clears the secret token whenever the URL changes, and the lab saw the signing token kept, but the guide does not lean on the difference: whenever the URL is edited — a new tunnel address, say — the token is entered again in the same save. A token cleared anyway can only be replaced by rotating again, because ReleaseFlow showed it once. Then Recent events, Resend Request for each refused event, and, if four refusals in a row made GitLab disable the hook, enable it again.
- Linear: because Linear documents no way to regenerate a signing secret, the page says to create a second webhook in Linear with the same URL and the Issues event, copy its signing secret from its detail page, paste it into ReleaseFlow, and then delete the old webhook. While both exist every event is sent twice, at least one copy verifies before and after the paste, and intake keeps one, so nothing is missed; the copies that fail are counted, and Linear's own retries cover a slow paste. (Amended on 2026-11-16: Linear refuses the second webhook, so this cannot be done; see the end.)
-
The rotation itself calls no provider. A generated secret is made locally, and a pasted one cannot be confirmed by anyone but the next delivery. ReleaseFlow never sends the hooks API request itself: it holds no token that may edit a hook.
Rotating a token
- The existing replacement is the rotation, for all four types. It keeps the source, its path, and its secret; the provider confirms the new token first; the old one is never used again once the new one is stored, though a call already under way finishes with it. ReleaseFlow cannot revoke the old token, so the form and the guide say to revoke it at the provider once the new one is saved.
- A Jira token may change account. A Jira token belongs to the account it was made
by, and that person may leave.
PUT .../tokentherefore takes an optionalaccountEmailfor a Jira source, confirmed together with the token by the same one project check, and written tocredential_identity, which no ciphertext is bound to. - No reminders. Nothing reminds anyone to rotate. The page already shows when the token and now the secret were last set, and reminders stay deferred.
The GitHub Release action
- A disconnected source lends nothing.
findSolecounts connected GitHub sources only, so enabling a rule with a GitHub Release action is refused asautomation_github_source_missingwhile the Project has none connected, as it is now when the Project has none at all. - A run says which repository it was for, and why it failed. A run records the
repository of the Project's one connected GitHub source; when none is connected but
exactly one disconnected GitHub source remains, it records that one's. When the
recorded repository's source is disconnected at the time the action runs, the action
fails as
FAILEDwithgithub_source_disconnectedbefore any call — nothing was written, so it is notUNKNOWN— and the run stops there, as after any failed action. Reconnecting the same repository keeps its name, so retrying that action then succeeds without a new run. - Disconnecting does not disable rules. A suspected leak must be stoppable at once, and disabling a rule cancels runs whose other actions have nothing to do with GitHub. Instead, the disconnect confirmation lists the enabled rules of that Project with a GitHub Release action, and the Automation page marks each such rule until the Project has one connected GitHub source again.
Source health
- Recorded on the source, never in a log of requests. Three columns:
secret_updated_at,signature_failure_count, andlast_signature_failure_at.last_delivery_atalready exists and keeps its meaning: the last delivery that proved itself and was accepted. - A signature failure is counted, nothing more. When a path resolves to a connected
source of the right type and its proof fails — a missing or wrong signature, a stale
stamp, another workspace — the failure is added to the source's count and its time
noted, after the verifier has answered and outside any transaction of the request. The payload, the
headers, the secret, the caller's address, and the reason are not stored or logged.
The answer is the same
401as before, so a refusal still says nothing about what exists, and an unknown or disconnected path records nothing, because there is no source to record it on. The count restarts at zero whenever the secret is set, by connecting, rotating, or reconnecting, so it reads as "refused since this secret". A body over the limit is refused before any source is looked up and is not counted. A caller who knows a path can raise its count; it is evidence on a page, writes no new row, and never changes what is accepted. - A flood is bounded by coalescing the write. ReleaseFlow has no inbound rate limit:
a webhook request is bounded only by the 1 MiB body limit, checked first, and by
whatever the deployment's proxy enforces. So the count is kept exact without one write
per request. The first failure on a source writes at once; later ones add to a pending
count held in memory for that source, and a drain once a second writes each pending
count in one
UPDATE(count = count + pending, the later time) — at most about oneUPDATEper source per second, however many forged deliveries arrive. The pending map holds an entry only for a source that resolved, so it is as large as the sources being refused, never as large as the requests. Several instances each coalesce their own, and the additions still sum exactly. Each pending count names the secret it was refused under, and itsUPDATEapplies only whilesecret_updated_atis unchanged, so failures against a secret just replaced never land on the new one's count. A drain runs on shutdown; only a process that dies outright loses what it had not written, at most about a second of failures. The request's own cost — one lookup by webhook ID, one decryption, one HMAC — is what it is today; a deployment that expects floods limits/webhooks/**at its proxy, as the operations guide will say. - A quiet source is flagged against its own rhythm. At read time, from the changes
that source delivered by webhook in the last 90 days, ReleaseFlow takes the gaps between
consecutive arrivals and their 90th percentile, with a floor of one hour. A connected,
delivered source is quiet when its last delivery, or its secret's last setting if it
has had none since, is older than that. Fewer than ten gaps are not enough to judge,
and then nothing is flagged. Each source is measured alone: a dead address silences
every source behind it at once, so the busy ones show it, and a rarely used source in a
busy Project is not flagged for being rare. Every accepted delivery
moves
last_delivery_at, and a hook sends many more events than merges, so comparing any delivery with the gaps between merges leans towards not flagging. The flag states its figures — quiet for 14 hours, where this source usually delivers within 6 — so a person can judge it. It is evidence on a page: no job computes it, nothing is sent anywhere, and it never stops a source, a release, or a rule. - A polled source has its own health. A Jira poll succeeds when nothing was done, so its silence means nothing; it keeps its last and next read and its error, and is marked overdue when its next read is more than one poll interval in the past.
- Shown where people look. The Change Inbox's Source sync panel lists every source of the Project — today it lists only polled and importable ones, so Linear is missing — each with its last delivery or read, its signature failures since the secret was set with the time of the last one, and the quiet or overdue flag; a disconnected source is listed as disconnected, with its time. The overview shows the selected Project's sources the same way, compactly, beside the figures it already has: it is information, not a step, so the one next step and the order that picks it do not change. The Projects page shows the same, and the API's source view carries the same fields.
The binding invariant
- No action in this ADR rewrites
organization_id,project_id,id,source_type,external_project_key,repository_owner, orrepository_name. Rotation and reconnect write a new nonce and ciphertext under the same authenticated data; disconnect writes nulls. A different repository is a different source, never an edited one. The mapping marks every bound column as not updatable, and a test proves that each action leaves them as they were and that the stored secret and token still decrypt.
Cost
- No AI and no DeepL request comes from any action here: disconnecting,
reconnecting, rotating, counting, and flagging classify and translate nothing. A change
recorded for the first time after a reconnect — by a delivery, a poll, or an import a
person starts — is processed like any new change, AI included when it is configured; a
change already recorded is a
duplicateand costs nothing. - Provider requests: disconnecting, rotating a secret, counting a failure, and computing health call no provider; nor does ReleaseFlow send the GitLab hooks request it shows. Reconnecting and rotating a token make the one confirmation call in the table above (none for GitHub or GitLab without a token). A reconnected Jira source's first poll reads, page by page, what was completed while it was disconnected, within 90 days.
Schema
V37addsdisconnected_at,disconnected_by,secret_updated_at(set tocreated_atfor existing rows),signature_failure_count(zero), andlast_signature_failure_at; replacesintegration_sources_external_uniquewith the two indexes above; and restates the presence checks so that a connected source has exactly what its type needs, as now, and a disconnected one has no webhook ID, secret, token, or next poll. No existing row changes, so every ciphertext still decrypts.
Consequences
- A source can be disconnected in an emergency without losing a single change, and
brought back without duplicating any: the same ID is what keeps
ChangeIntakehonest. - A leaked webhook secret can be replaced in place, with the path unchanged. The price is a gap between ReleaseFlow's save and the provider's, which the page shows and each provider's own resend, or the import, fills. (Amended on 2026-11-16: for Linear nothing fills it; see the end.)
- A source that stops delivering is visible within about one of its usual gaps, wherever people look, and a hook pointed at ReleaseFlow with the wrong secret is visible at once. Neither is an alert: nothing is sent, and a source with no rhythm yet is never flagged. A source whose overnight gaps are long flags a dead address only after an unusually long silence, and a source with fewer than ten delivered changes in 90 days is never flagged at all.
- A repository that was renamed is a new source whose import repeats the old one's changes; ReleaseFlow does not guess that two names are one repository.
- A flood of refused deliveries on a known path costs about one row update per source per second, and an exact count. Rotation reminders, alerts on a quiet source, and deleting a source with its changes remain deferred.
Amendment, 2026-11-16: Linear rotation and reconnect
The decision above stands: a rotated secret keeps the path and stops the old one at once, a reconnect keeps the source's ID, and neither calls a provider. What changes is what the page and the guide tell an administrator to do in Linear, and what they promise about the gap. No code path, request, response, or stored value changes.
What was found. The dbvault acceptance tried the Linear rotation as written, before any release carried it:
- Linear refuses a second webhook for a URL that already has one:
webhookCreateanswered400 INPUT_ERROR, "url not unique … A webhook for the URL … already exists on the workspace", with an administrator's key. Its schema says the same of the mutation: "The destination must not already be registered for the same team scope." So "create a second webhook with the same URL" cannot be done, and with it goes the claim that two webhooks cover the gap. - Linear's documentation still describes no way to rotate a signing secret in its
settings, but its GraphQL schema has
webhookRotateSecret(id), which "generates and returns a new HMAC-SHA256 signing secret for the webhook … the previous key is replaced rather than kept as a second active key", andwebhookUpdate, whose input takes aurl. - Nothing recovers a refused Linear delivery. Linear's documentation says it retries a
failed delivery after one minute, one hour, and six hours, but on the dbvault lab it
sent no retry of a delivery ReleaseFlow refused with
401: after two refusals on 2026-11-16, at 14:43:24Z and 14:53:15Z, nothing more arrived at the 1-minute, 1-hour, or 6-hour mark, the source's signature-failure count stayed at 2, and Linear's own error log for the webhook lists only those two refusals (readings on #94). A retry would not help in any case: ReleaseFlow has checked the body'screatedAtwithin 60 seconds since ADR-0018, and Linear definescreatedAtas "the date and time that the action took place" andwebhookTimestampas the time the webhook was sent. (Corrected on 2026-11-18: this bullet said Linear's retries arrive and are refused; the lab saw none arrive.) - The reconnect row had the same fault in another form: its body needs the signing secret before the new path exists, and a webhook cannot be made at a path that is not known, nor at the old one while the old webhook still holds it.
What the instructions say now.
- Rotating: rotate the existing webhook's secret in Linear, on the webhook's page if
Linear offers it and otherwise with
webhookRotateSecret, then paste the returned secret into ReleaseFlow right away. Linear goes first, because it makes the secret. A delivery refused between the two is counted and not recorded, nothing sends it again, and because ReleaseFlow cannot import Linear's history the issue is recorded only if it is completed again. The advice is to rotate while nobody is changing the team's issues and to paste within the minute. - Reconnecting: create a new webhook disabled, at ReleaseFlow's own address with a
path it does not know, which answers
401and records nothing; or keep the team's old webhook and rotate its secret first, since a source is often disconnected because its secret may be known. Reconnect with that secret, then change the webhook's URL to the new path and enable it. Linear'sWebhookCreateInputandWebhookUpdateInputboth takeurlandenabled. A holding address anywhere else was rejected: Linear would send the team's issues to whoever answers it. - Connecting for the first time had the reconnect's fault since ADR-0018, in text
that was released: it said to create the webhook at the source's path, which does not
exist until the team is connected. It now gives the same three steps, and the 1.3.0
entry of
CHANGELOG.mdsays so. - The guide's Linear section carries a known-issue note for the stale
createdAt, linking #94. (Removed on 2026-11-19, with the fix.) - The statements above that Linear's retries cover a slow paste, and that each provider's resend fills the gap, do not hold for Linear and are marked where they stand.
What is left open. Checking webhookTimestamp instead of createdAt would accept a
first delivery that arrives late, the loss the lab observed; it would not bring back a
delivery refused for its signature, since no retry came. That changes which deliveries
ReleaseFlow accepts, so it is a decision of its own, amending ADR-0018, and not part of this
amendment; #94 tracks it.
Settled on 2026-11-19 by
ADR-0018's amendment:
a delivery is fresh by its webhookTimestamp, so a first delivery Linear sends late is
accepted. A delivery refused for any other reason, in a rotation gap included, is still
lost, and the advice above to rotate while nobody is changing the team's issues and to
paste within the minute stands.