Linear setup

Before connecting Linear

Use this page when the customer wants WebRiskOps to create or update Linear issues for remediation work. Linear is cloud-only, so setup should focus on the customer-owned workspace, team, labels and issue permissions instead of private-network or self-hosted URL checks. Start from `/settings` after Cloud and self-hosted integrations confirms Linear is a cloud target. Do not save a Linear token until the destination team, label mapping, auth summary and revoke path are clear.

Connect a Linear team

Follow the path `Cloud and self-hosted integrations → Linear cloud target → Team and label mapping → Work management export → Revoke or fallback`.

1. Open /settings and review Integration status, then choose Linear setup. Result: provider_key is recorded as linear_cloud before team fields are requested.
2. Confirm Linear is a cloud-only target and leave base_url empty. Result: deployment_mode stays cloud and self-hosted network checks are not shown for Linear.
3. Choose the customer-owned Linear workspace and authorize with the supported auth_method. Result: WebRiskOps can list only the teams and labels the customer allowed.
4. Select team_id for the issue destination and optional project or cycle defaults. Result: future work management exports know which Linear team owns the issue.
5. Confirm label_id, assignee and priority mapping when the workspace exposes them. Result: WebRiskOps can route findings without requesting unrelated Linear access.
6. Save only when the team, labels and auth summary match the customer workflow. Result: Linear is available to work management export without exposing token values in documentation or support messages.
7. If PROVIDER_AUTH_REQUIRED appears, reconnect Linear before retrying. Result: the target stays blocked until valid cloud credentials exist.
8. If PROVIDER_SCOPE_UNAVAILABLE appears, adjust the Linear authorization or choose portable fallback. Result: issues are not created without the team and issue permissions Linear requires.
9. Continue to Work management export after setup. Result: team_id, labels, assignee and priority mapping use the same Linear provider record.

Configure Linear authorization

Linear setup should collect only the workspace and issue access the customer needs.

• `linear_cloud` is the only supported Linear provider key.
• `base_url` should stay empty because Linear does not have a self-hosted target.
• `auth_method` should identify the supported Linear OAuth or token flow before a credential is saved.
• `scopes` should allow team, issue, label and member lookup for the selected workspace.
• `team_id` and `label_id` should be visible before Linear appears in work management export.
• Revoke access in Linear first, then disconnect the Linear target in WebRiskOps so historical issues keep references without keeping live credentials.

Ready Linear integration states

Continue only when the issue destination is clear.

• Cloud target ready means `provider_key` is `linear_cloud` and `deployment_mode` is cloud.
• Team ready means `team_id` belongs to the customer-owned workspace.
• Label ready means `label_id` or the chosen label mapping can route WebRiskOps findings.
• Scope ready means Linear can create issues and read the teams, labels and members needed for mapping.
• Revoke path ready means the customer knows how to revoke the Linear authorization before disconnecting WebRiskOps.

Blocked Linear setup states

Blocked Linear setup should explain exactly what to fix.

• `PROVIDER_AUTH_REQUIRED` means reconnect Linear before saving or retrying export.
• `PROVIDER_SCOPE_UNAVAILABLE` means the token cannot access the selected team, issue fields, labels or members.
• A non-empty `base_url` means the customer is trying to use an unsupported self-hosted Linear target.
• Missing `team_id` means work management export cannot place the issue.
• Missing label, assignee, cycle or priority mapping should fall back to default team routing or portable export notes when Linear does not expose matching fields.

Continue after Linear setup

Continue to Work management export when the Linear team is ready. Use Status sync and duplicate handling when a Linear issue already exists, Portable export fallbacks when Linear permissions cannot be made safe, or Azure DevOps Services and Server setup when the team tracks work in Azure DevOps.