Linear setup - Configview Support

ConfigView pulls Linear data through one Personal API key. The key inherits the permissions of the user who created it, so the inventory follows that user’s access — not the workspace as a whole. You will end up with 1 secret in ConfigView (LINEAR_API_KEY) when setup is complete.

⚠️ Required: the key must be created by a Workspace Admin
Linear’s Personal API key carries the creating user’s permissions. ConfigView requires the key to come from a Workspace Admin — not a regular member, and not a guest. With a member-level key:

OAuth Applications, Organization Invites and Audit Entries return authorization errors and are recorded as empty

Private teams the member cannot see are missing from Teams, and every table derived from them is short by that team’s rows

Integrations and Webhooks come back empty or partial

Seat and plan data on Organization is present but the surrounding governance picture is not

None of this raises an error — ConfigView records a gated capability as an empty snapshot, exactly as it does for a workspace on a plan that never had the feature. That is the right behaviour for a mixed estate, but it means a member-tier key produces a quietly incomplete inventory. If no admin is available, ask the customer to (a) elevate an existing user temporarily, or (b) create a dedicated service user, promote it to Admin, then create the key from that account.

Step 1: Create the Personal API key

Sign in to Linear as a Workspace Admin (see the callout above — this is not optional)
Verify your role: Settings → Members. Your row must read Admin. If it reads Member or Guest, stop and use the workaround above.
Go to Settings → Security & access → Personal API keys (or open linear.app/settings/account/security)
Click New API key, give it a label such as ConfigView
Copy the key (starts with lin_api_). Linear shows it once — if you lose it you must create a new one.

Store it bare. Copy the key on its own, with no Bearer prefix. Linear’s personal API keys go in the Authorization header without Bearer — only OAuth access tokens use that prefix. A key stored as Bearer lin_api_... fails with an HTTP 400 that reads like a malformed query. The health check detects this specific mistake and names it.

OAuth alternative. Linear also supports OAuth 2.0 for multi-tenant apps. ConfigView is single-tenant per satellite, so the Personal API key is the right choice — simpler, and it gets the larger complexity budget (3,000,000 points/hour against an OAuth app’s 2,000,000).

Step 2: Add the secret to ConfigView

Go to your ConfigView dashboard: https://{companyname}.configview.com/admin/secret/
Click Add Secret
Secret name: LINEAR_API_KEY
Secret value: Paste the lin_api_... key from Step 1
Click Save

Step 3: Enable the Linear scripts

Go to: https://{companyname}.configview.com/admin/cron/
You should see linear in the list of available apps
Enable the scripts you want. No script depends on another — Linear serves one GraphQL endpoint and every collector queries it directly, so they can be enabled in any order and run in parallel.

Identity & licensing

Script	Notes
Organization	The workspace record: plan, seat count, SSO/SCIM posture, trial dates. `seats` vs `userCount` is the licence reconciliation. `subscription` is null on Free — expect NULL seat columns there.
Users	Every member, including deactivated and archived accounts. Filter on `active` in your query, not at ingestion — a disabled user still holding a seat is the point.
Teams	Visibility (private/public/restricted), SCIM management, cycle and triage settings.
Team Memberships	The user × team join, with per-team owner flags. Denormalised with email and account status.
Organization Invites	Pending and historical invitations. Each unaccepted invite becomes a billable seat on acceptance.
External Users	Customers and collaborators with no paid seat. They are not in `linear_users`.
Project Members	Who can see each project. See the nested-page caveat below.

Security & governance

Script	Notes
OAuth Applications	Third-party apps holding delegated access, with redirect URIs and grant types. Admin key required.
Integrations	Connected services (Slack, GitHub, Figma…) and who connected each.
Webhooks	Outbound event feeds. Records whether each is signed, never the signing secret itself.
IP Restrictions	Configured IP/CIDR restrictions. Enterprise-only — empty elsewhere.
Audit Entries	Actor, IP and country per action. Enterprise-only. Capped at the 10,000 most recent entries; see the caps section below.

Work structure

Script	Notes
Projects	Lead, status, health, dates, progress. `health` + `last_update_at` is the staleness lens.
Project Milestones	Target dates and overdue status.
Project Updates	The written updates behind each health rating, with Linear’s own `is_stale` flag.
Project Statuses	Status definitions — what makes `linear_projects.status_name` meaningful.
Project Labels	Project label taxonomy with retirement and last-applied dates.
Initiatives	The layer above projects: owner, status, health, visibility.
Initiative Projects	The initiative × project join (a project can sit under several).

Workflow configuration

Script	Notes
Cycles	Sprints per team, with active/past/future flags.
Workflow States	Every team’s board columns. Group by `state_type`, not `state_name`.
Issue Labels	Label taxonomy, workspace-wide and team-scoped.
Templates	Issue, project and document templates with last-applied dates.
Custom Views	Saved views and their filters. `shared = 1` means workspace-visible.
Triage Responsibilities	Who is on triage duty per team.

Work items

Script	Notes
Issues	The main work table. Archived issues are excluded; capped at 20,000. See caps below.
Issue Relations	Blocks / duplicate / related edges.
Comments	Across issues, projects, updates and initiatives. Capped at 20,000.
Attachments	Links out to GitHub, Slack, Figma, Zendesk and uploaded files. Capped at 20,000.
Documents	Linear documents and what each is attached to.

Rate limits and collection caps

Linear meters two budgets per API key, and either can throttle a run:

Budget	Per personal API key	Per OAuth app
Requests	5,000/hour (~83/min)	5,000/hour
Complexity	3,000,000 points/hour	2,000,000 points/hour
Single query	10,000 points maximum	10,000 points maximum

Complexity is the limit that actually bites. It scales with page size × fields × nesting, so the collectors use different page sizes rather than one folder-wide constant — 50 for wide types like issues, 100–250 for narrow configuration tables. ConfigView paces requests well under the ceiling and reads the live X-RateLimit-Complexity-Remaining header on every response, pausing until the window resets when the workspace is close to exhausting it. Three collectors are deliberately capped, because the underlying data is unbounded:

Script	Cap	Why
Issues	20,000 most recent	Archived issues excluded. A mature workspace’s full history would page for hours and exhaust the hourly complexity budget.
Comments	20,000 most recent	Same reasoning.
Attachments	20,000 most recent	Same reasoning.
Audit Entries	10,000 most recent	An audit log grows without limit.

When a cap is reached the run log prints an explicit TRUNCATED warning naming the collector — a partial snapshot is never reported as if it were the whole workspace. Raise the limit in tools/linear_specs.py (max_pages) and regenerate if a customer needs the full history. Project Members has a different kind of cap. Linear serves a project’s member list as a nested connection, which has no cursor of its own, so only the first 100 members per project are returned. The collector prints a warning naming any project that hits that ceiling.

What gets collected

30 collectors, one table each. Every table is a per-run snapshot stamped with run_at, and each collector prunes older snapshots after a successful insert — so query the latest with:

WHERE run_at = (SELECT MAX(run_at) FROM <table>)

Table	Script	Key columns
`linear_organization`	Organization	org_id, name, url_key, user_count, seats, subscription_type, saml_enabled, scim_enabled, trial_ends_at
`linear_ip_restrictions`	IP Restrictions	org_id, restriction_type, ip_range, enabled
`linear_users`	Users	user_id, email, name, active, admin, owner, guest, is_app, last_seen, identity_provider_id
`linear_teams`	Teams	team_id, team_key, name, visibility, scim_managed, issue_count, cycles_enabled, triage_enabled
`linear_team_memberships`	Team Memberships	membership_id, team_id, team_key, user_id, user_email, is_owner
`linear_organization_invites`	Organization Invites	invite_id, email, invite_role, is_external, accepted_at, expires_at, inviter_email
`linear_external_users`	External Users	external_user_id, email, name, last_seen
`linear_integrations`	Integrations	integration_id, service, creator_email, team_key
`linear_oauth_applications`	OAuth Applications	application_id, client_id, name, developer, distribution, redirect_uris, webhook_url
`linear_webhooks`	Webhooks	webhook_id, label, url, enabled, resource_types, has_secret, creator_email
`linear_audit_entries`	Audit Entries	entry_id, entry_type, actor_email, ip, country_code, created_at
`linear_projects`	Projects	project_id, name, status_type, health, lead_email, target_date, progress, last_update_at
`linear_project_members`	Project Members	project_id, project_name, user_id, user_email, user_active
`linear_project_milestones`	Project Milestones	milestone_id, project_id, name, milestone_status, target_date
`linear_project_updates`	Project Updates	update_id, project_id, health, is_stale, user_email, body_excerpt
`linear_project_statuses`	Project Statuses	status_id, name, status_type, position
`linear_project_labels`	Project Labels	label_id, name, retired_at, last_applied_at, team_key
`linear_initiatives`	Initiatives	initiative_id, name, initiative_status, health, owner_email, visibility, target_date
`linear_initiative_projects`	Initiative Projects	link_id, initiative_id, project_id, project_status_type
`linear_cycles`	Cycles	cycle_id, team_key, cycle_number, starts_at, ends_at, is_active, progress
`linear_workflow_states`	Workflow States	state_id, team_key, name, state_type, position
`linear_labels`	Issue Labels	label_id, name, team_key, retired_at, last_applied_at
`linear_templates`	Templates	template_id, name, template_type, team_key, last_applied_at
`linear_custom_views`	Custom Views	view_id, name, model_name, shared, owner_email, filter_data
`linear_triage_responsibilities`	Triage Responsibilities	responsibility_id, team_key, action, current_user_email
`linear_issues`	Issues	issue_id, identifier, title, state_type, assignee_email, team_key, project_id, cycle_id, due_date
`linear_issue_relations`	Issue Relations	relation_id, relation_type, issue_identifier, related_identifier
`linear_comments`	Comments	comment_id, issue_id, project_id, user_email, external_user_email, body_excerpt
`linear_attachments`	Attachments	attachment_id, issue_identifier, title, url, source_type, creator_email
`linear_documents`	Documents	document_id, title, project_id, initiative_id, team_key, creator_email

What is deliberately not collected

ConfigView reads inventory, not credentials. These fields exist in Linear’s API and are left out on purpose:

Field	Why
`Webhook.secret`	The live signing secret. Anyone holding it can forge events into the workspace. ConfigView records whether one is set (`has_secret`) and strips the value before writing.
`Organization.samlSettings` / `scimSettings` / `authSettings` / `securitySettings`	JSON blobs that can carry IdP certificates and SCIM bearer tokens. The `saml_enabled` / `scim_enabled` booleans carry the posture signal without copying the credential into your reporting database.
`Organization.aiProviderConfiguration`, `codingAgentSettings`, `linearAgentSettings`	Can hold third-party provider API keys.
`IdentityProvider.ssoSigningCert`	The workspace SSO certificate. Only the IdP’s `id` and `type` are stored.
`User.calendarHash`	A bearer token in a URL — anyone with it can read that user’s calendar feed.
`Document.content`, `Template.templateData`	Long free-text bodies that would dominate storage and that nothing queries. `title` and `summary` are collected.

Attachment URLs are collected, and for uploaded files these can be signed object-store URLs. Treat linear_attachments with the same care as a storage-bucket listing.

Verifying the setup

Run the health check from /admin/cron/. It probes, in order:

LINEAR_API_KEY retrievable from Secret Manager — and not stored with a Bearer prefix
viewer — names the identity behind the key and whether it is an admin
organization — workspace name, user count, plan and SSO posture
users — the core read path
Teams, Projects, Issues, Integrations, Webhooks, OAuth applications, Organization invites, Audit log, Initiatives — each reported as ok or skip, never as a failure when the plan or key scope simply does not grant it
Rate-limit headroom — remaining requests and complexity points for the hour

A workspace on the Free plan with a member-level key should still show overall: ok, with several checks marked skip. That is the design: a skip means “not granted here”, a fail means “broken”.

Troubleshooting

Issue	Fix
Health check fails with HTTP 400 on every query	The key is stored with a `Bearer` prefix. Personal API keys go in bare — re-save `LINEAR_API_KEY` with just the `lin_api_...` value.
Health check fails on “Linear API auth (viewer)“	The key is wrong, revoked, or belongs to a deactivated user. Create a new one under an admin account.
`linear_oauth_applications` / `linear_organization_invites` empty	The key is not from a Workspace Admin. These need admin scope.
`linear_audit_entries` / `linear_ip_restrictions` always empty	Both are Enterprise-only features. Empty is correct on other plans.
`linear_organization` seat columns are NULL	The workspace is on the Free plan and has no `subscription` object. Expected.
A private team’s issues are missing	The key’s user is not a member of that private team. Linear scopes reads to the user; add them to the team or use a broader admin account.
Runs slow down or pause mid-collection	The workspace is near its hourly complexity budget. The collectors wait for the window to reset by design. Stagger the schedules of Issues, Comments and Attachments if it happens every run.
`TRUNCATED` in the run log	A collection cap was reached — the snapshot is partial by design. Raise `max_pages` in `tools/linear_specs.py` and regenerate if the full history is needed.
A project’s member list looks short	More than 100 members on that project; Linear’s nested connection stops there. The run log names the affected project.
Many columns NULL after the first run	NULL-audit before assuming a bug: Linear’s schema declares fields that a given workspace may never populate (SLA timers, GitHub links, initiative fields on workspaces that do not use initiatives).

​⚠️ Required: the key must be created by a Workspace Admin

​Step 1: Create the Personal API key

​Step 2: Add the secret to ConfigView

​Step 3: Enable the Linear scripts

​Identity & licensing

​Security & governance

​Work structure

​Workflow configuration

​Work items

​Rate limits and collection caps

​What gets collected

​What is deliberately not collected

​Verifying the setup

​Troubleshooting

⚠️ Required: the key must be created by a Workspace Admin