UNDERSTANDING LINEAR AUTOMATION IN SWAMP

Linear is where a team plans and tracks its work. Swamp is where a team automates operations and records what each automated step did. The Linear extensions connect the two. This page covers how that connection is shaped, the choices it leaves to a team and the reasons behind them.

How Linear maps onto Swamp

A Linear integration in Swamp is a behavior. Each behavior holds one Linear personal API key as a global argument, and its methods call the Linear API on behalf of that key. This follows the general pattern described in Behaviors, Types, and Methods. The behavior type describes what a Linear connection can do, and each behavior is one configured connection.

The results of each method are written as data. A method that lists teams writes team resources. Other methods write issue, project, workflowState, label or commentThread resources, depending on what they touch. This puts Linear's state in the same place as everything else Swamp records. Workflow steps can read it, it is versioned, and it can be queried after the fact. The Data Layer covers how that storage works. Swamp stores a copy of what Linear returned at the time of the call. Linear itself remains the source of truth, and the data in Swamp shows what an automation saw and did.

Choosing an extension

Four extensions provide Linear behavior types. Each has a different scope.

@hivemq/linear is the smallest of the four. It creates issues and lists teams, projects and workflow states. It is also the most widely pulled, and it fits automations that only need to file issues, such as a workflow that opens a ticket when a check fails.

@mgreten/linear has the same core and goes further. It can update issues, delete them after verification, create epics with sub-issues, add labels by name, read and write comments, fetch documents and project resources, and file issues assigned to the key's own user. It suits a team that manages its backlog from Swamp or lets an agent work in Linear.

@mgreten/linear-activity only reads from Linear. It records what one user did on a given day.

@mgreten/graphite-linear-sync reconciles issue states with the pull requests that reference them.

The three @mgreten extensions declare the MIT license. The registry entry for @hivemq/linear doesn't declare one. About Extension Licenses discusses why that can matter for a team that redistributes or depends on an extension.

The extensions can be used together. One repository can hold a @hivemq/linear behavior for incident tickets and a @mgreten/linear-activity behavior for standups, because each behavior is independent.

Keeping the API key in a vault

Every Linear type requires apiKey. The pages in this set always refer to the key as ${{ vault.get('linear', 'api-key') }} rather than writing it into the definition. Behavior definitions are files in a repository and are often committed. A key written inline would end up in version control and in every copy of the repository. With a vault reference, the definition records where the key is kept, not the key itself, and Swamp redacts the resolved value from run output and stored data. Storing Secrets shows the redaction in practice, and the Vaults reference covers the expression syntax.

A Linear personal API key acts as the user who created it. Issues created through it show that user as the creator. getViewer returns that user, createMyIssue assigns new issues to them, and daily_activity reports their activity. A team that wants automated issues to come from a separate identity can create the key from a dedicated Linear account. The choice of key decides whose name appears in Linear.

Defaults and scope

Several global arguments exist to reduce the inputs each call needs. With defaultTeamId set, createIssue and the list methods don't need a teamId on every run. In @mgreten/linear, defaultProjectId does the same for createMyIssue. The teamKeys argument of the activity and sync types does something different. It limits which teams those behaviors look at.

A team can create one behavior per Linear team or one shared behavior that receives the team as an input. One behavior per team keeps each call short and makes the target team visible in the definition. A shared behavior means fewer definitions to maintain, but every call must state its team. Neither is wrong. The choice usually follows how the Linear workspace is organised.

Read methods and write methods

The methods fall into two groups. List and get methods only read Linear and record what they find. They are safe to repeat. createIssue, createEpic, updateIssue, addLabels, createComment and true_up change Linear, and running them twice usually has an effect twice.

Two methods have extra safeguards because their mistakes are costly. deleteIssue in @mgreten/linear fails closed. It takes an identifier, an expectedTeamKey and confirm set to delete. It checks the live issue's identifier and team against these values before deleting anything, and refuses if they don't match. After a deletion it writes an issueDeletion audit record, so the removed issue can still be traced. true_up in @mgreten/graphite-linear-sync defaults to a dry run. Unless told otherwise, it reports the transitions it would make without making them.

Combining methods in workflows

Single method runs are useful for exploring. The integrations become more useful in workflows. scan_stack followed by true_up is a natural two-step workflow. daily_activity on a schedule records each day's work before the standup. A manual approval step placed before a write method lets a person check the dry run or the planned issues before anything changes in Linear. See Create and Run a Workflow, Run Workflows on a Schedule and Gate a Workflow with Manual Approval.

Agents and Linear

An AI agent can file and update Linear issues by calling these behaviors instead of calling the Linear API directly. Each call then goes through the same definition, vault reference and method checks as a call made by a person. The agent never needs to see the API key. Each call is also recorded in the audit trail, so a team can later see which issues an agent created or changed and with which inputs. AI agent integration and The Audit System discuss this in more detail. Some teams give agents only the read methods at first and add write methods once they trust what the agent files.