> For the complete documentation index, see [llms.txt](https://ai-security-docs.akto.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai-security-docs.akto.io/integrations/linear.md).

# Linear

Integrate Akto with Linear to streamline your agentic AI security workflow by creating Linear issues for vulnerabilities directly from Akto. You can connect with a Linear API key, or create the issues through a workflow in your Port.io organization.

## Benefits

* Instantly create Linear issues for Agentic component vulnerabilities.
* Manage multiple Linear teams from a single integration.
* Map Akto severity to Linear priority for each team.
* Create issues automatically after a scan.
* Enable **bi-directional sync** to keep issue status aligned between Akto and Linear.
* Maintain a centralized view of security issues.

## Quick Setup Steps (Linear API key)

{% stepper %}
{% step %}
**Access Integrations**

* Go to **Settings > Integrations**.
* Find and click the **Linear** card.
  {% endstep %}

{% step %}
**Enter Linear Details**

* Under **API Key**, paste your Linear personal API key.
* Click **Save**.

{% hint style="info" %}
The API key must be able to read your teams. To create teams from Akto, it must also be allowed to create teams.
{% endhint %}
{% endstep %}

{% step %}
**Add Teams**

* Under **Linear Teams**, add a team and select it from your Linear workspace.
* To create a new team, click **Create team** and enter a team name and an optional team key (for example `SEC`).
* Add as many teams as you need.
  {% endstep %}

{% step %}
**Select Priority Mapping**

* For each team, click **Edit Mapping** under **Severity to Priority Mapping**.
* Choose the Linear priority for each Akto severity, then save.

| Akto severity | Default Linear priority |
| ------------- | ----------------------- |
| Critical      | Urgent                  |
| High          | High                    |
| Medium        | Medium                  |
| Low           | Low                     |
| {% endstep %} |                         |

{% step %}
**Save Configuration**

* Click **Save** under **Linear Teams** to finalise.
  {% endstep %}
  {% endstepper %}

## Create Linear issues

* **From the Issues page:** select issues, click **Create Linear ticket**, choose a team, then click **Create ticket**.
* **From an issue:** open the issue and click **Create Linear Ticket**. If you have more than one ticketing integration connected, use **Create ticket > Linear**.
* **Automatically after a scan:** when you run a scan, turn on **Auto-create tickets**, choose **Linear**, then select a team and the severities to create issues for.

Akto saves the Linear issue link on the finding. Findings that already have a Linear issue are skipped.

{% hint style="info" %}
**Important Notes**

* Issues are created in the team you choose, with the priority set by that team's severity mapping.
* If an error occurs while creating an issue, the other issues in the batch are still created.
  {% endhint %}

## Bi-directional sync

Keep the status of Akto issues and Linear issues aligned.

1. Go to **Settings > Integrations > Linear**.
2. Save your API key and at least one team.
3. Select **Enable bi-directional sync**.

Every hour, Akto compares the issues changed in Akto and in Linear since the last sync. The most recent change wins. Disabling sync stops the hourly job; enabling it again resumes from the last sync.

| Linear state type                                 | Akto status |
| ------------------------------------------------- | ----------- |
| Backlog, Unstarted (To do), Started (In progress) | Open        |
| Completed (Done)                                  | Fixed       |
| Canceled, Duplicate                               | Ignored     |

When Akto moves a status to Linear, it uses the first state of the matching type in the issue's team.

{% hint style="info" %}
**Important Notes**

* Only issues in the teams saved in Akto are synced from Linear.
* The mapping is by state type, so it works with any team workflow.
* If an error occurs while syncing an issue, it is logged and skipped.
  {% endhint %}

## Linear integration via Port.io

Create Linear issues for Akto findings through a workflow in your [Port.io](https://www.port.io) organization. Akto only needs Port.io credentials. The Linear API key stays in Port.io.

{% hint style="success" %}
**Prerequisites**

1. The [Linear integration](https://docs.port.io/build-your-software-catalog/sync-data-to-catalog/project-management/linear/) is installed in Port.io and syncs your Linear teams, issues and workflow states into the catalog.
2. Actions processing is enabled for the Linear integration, so workflows can use Linear actions. Port.io's [Linear integration actions](https://docs.port.io/workflows/build-workflows/nodes/action-nodes/integration-actions/project-management/linear/) page has the sample workflow this setup is based on.
3. Your Port.io client ID and client secret. Organization credentials are recommended, and they must be allowed to run the workflow.
   {% endhint %}

### Set up the workflow in Port.io

{% stepper %}
{% step %}
**Copy your Linear team identifier**

In Port.io, go to **Context lake > Catalog > Linear Team**. Copy the **identifier** of your team. It must be a UUID. If it is a short key such as `ENG`, resync the Linear integration first.
{% endstep %}

{% step %}
**Create the workflow**

1. In Port.io, create an empty workflow. The name is up to you. Use the identifier `linear_ticket_creation`, or any identifier and enter the same one in Akto in the next step.
2. Open the workflow's **Edit JSON** view and replace its content with the JSON below.
3. Replace `REPLACE_WITH_LINEAR_TEAM_UUID` with the identifier from step 1, then save.
   {% endstep %}

{% step %}
**Connect Akto**

1. In Akto, go to **Settings > Integrations > Port.io**.
2. Enter the client ID, client secret and workflow identifier (`linear_ticket_creation`).
3. Click **Save**.
   {% endstep %}
   {% endstepper %}

### Workflow JSON

```json
{
  "identifier": "linear_ticket_creation",
  "title": "Akto: Create Linear issue",
  "icon": "Linear",
  "description": "Creates a Linear issue from Akto. Requires the Linear integration with actions processing enabled. Replace REPLACE_WITH_LINEAR_TEAM_UUID in the Linear node with the identifier of your Linear team entity.",
  "nodes": [
    {
      "identifier": "trigger",
      "config": {
        "type": "SELF_SERVE_TRIGGER",
        "published": true,
        "userInputs": {
          "properties": {
            "team": {
              "title": "Linear team",
              "description": "Optional. Akto runs use the default team set in the Linear node.",
              "type": "string",
              "format": "entity",
              "blueprint": "linearTeam"
            },
            "title": {
              "title": "Title",
              "type": "string"
            },
            "description": {
              "title": "Description",
              "type": "string",
              "format": "markdown"
            },
            "priority": {
              "title": "Priority",
              "type": "string",
              "enum": [
                "No priority",
                "Urgent",
                "High",
                "Normal",
                "Low"
              ],
              "default": "No priority"
            }
          },
          "required": [
            "title"
          ],
          "order": [
            "team",
            "title",
            "description",
            "priority"
          ]
        }
      }
    },
    {
      "identifier": "linear_action",
      "title": "Create Linear issue",
      "config": {
        "type": "INTEGRATION_ACTION",
        "installationId": "linear",
        "integrationProvider": "linear",
        "integrationInvocationType": "create_issue",
        "integrationActionExecutionProperties": {
          "teamId": "{{ (.outputs.trigger.team | if type == \"object\" then .identifier else . end) // \"REPLACE_WITH_LINEAR_TEAM_UUID\" }}",
          "title": "{{ .outputs.trigger.title }}",
          "description": "{{ .outputs.trigger.description }}",
          "priority": "{{ .outputs.trigger.priority }}"
        },
        "deferIntegrationInstallation": false
      },
      "links": [
        "{{ .result.issueUrl }}"
      ]
    }
  ],
  "connections": [
    {
      "sourceIdentifier": "trigger",
      "targetIdentifier": "linear_action"
    }
  ]
}
```

Akto sends `title`, `description` and `priority`. The `team` field is only used when someone runs the workflow manually in Port.io.

{% hint style="warning" %}
Set the workflow's permissions as your organization requires, and make sure the client ID and secret you give Akto (preferably organization credentials) can run it.
{% endhint %}

### Create tickets

* **Issues page:** select issues, then **Create Linear ticket via Port.io**.
* **Issue details:** open an issue and click **Create Linear Ticket via Port.io**. If you have more than one ticketing integration connected, use **Create ticket > Linear via Port.io**.
* **Automatically:** when you run a scan, turn on **Auto-create tickets** and choose **Linear via Port.io**.

Akto maps severity to a Linear priority. Change the mapping under **Settings > Integrations > Port.io**.

### Bi-directional sync (optional)

<details>

<summary>Set up bi-directional sync (optional)</summary>

Keep the status of Akto issues and the Linear issues created through Port.io aligned. This needs a second workflow in Port.io.

**Step 1: Create the update workflow**

1. In Port.io, create an empty workflow.
2. Open the workflow's **Edit JSON** view and replace its content with the JSON below, then save.

```json
{
  "identifier": "akto_linear_update_issue",
  "title": "Akto: Update Linear issue status",
  "icon": "Linear",
  "nodes": [
    {
      "identifier": "trigger",
      "config": {
        "type": "SELF_SERVE_TRIGGER",
        "published": true,
        "userInputs": {
          "properties": {
            "issue": { "title": "Linear issue", "type": "string" },
            "stateId": { "title": "Linear workflow state", "type": "string" }
          },
          "required": ["issue", "stateId"],
          "order": ["issue", "stateId"]
        }
      }
    },
    {
      "identifier": "linear_action",
      "config": {
        "type": "INTEGRATION_ACTION",
        "installationId": "linear",
        "integrationProvider": "linear",
        "integrationInvocationType": "update_issue",
        "integrationActionExecutionProperties": {
          "issueId": "{{ .outputs.trigger.issue }}",
          "stateId": "{{ .outputs.trigger.stateId }}"
        },
        "deferIntegrationInstallation": false
      },
      "links": ["{{ .result.issueUrl }}"]
    }
  ],
  "connections": [{ "sourceIdentifier": "trigger", "targetIdentifier": "linear_action" }]
}
```

**Step 2: Enable sync in Akto**

1. In Akto, go to **Settings > Integrations > Port.io**.
2. Select **Enable bi-directional sync**.
3. Enter the update workflow identifier (`akto_linear_update_issue`) and click **Enable sync**.

Every hour, Akto compares the issues changed in Akto and in Linear since the last sync. The most recent change wins, using the same status mapping as the [Linear sync](#bi-directional-sync).

* **Linear to Akto:** Akto reads the Linear issue status from the Linear issues Port.io has synced. This does not start any workflow run.
* **Akto to Linear:** each status change in Akto starts one run of the update workflow. At most 50 runs start per hourly sync.
* **Linear sync also enabled:** if you also enabled [bi-directional sync](#bi-directional-sync) on the Linear integration with an API key, that sync updates these tickets directly through the Linear API, and no Port.io workflow runs are used.

**Important notes**

* Each status change sent to Linear counts toward your Port.io plan's workflow run limit.
* The Port.io credentials you give Akto must be able to read the Linear Issue and Linear Workflow State entities and run both workflows.
* Linear changes appear in Akto as soon as Port.io has synced them. Enable live events for the Linear integration in Port.io to keep this near real time.

</details>

### Troubleshooting

| Problem                                   | Fix                                                                                                           |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| Akto cannot start the run                 | Check the workflow identifier, and that the Port.io credentials can run the workflow (see Permissions above). |
| The run fails with a team error           | The team identifier is not a Linear team UUID.                                                                |
| The run succeeds but Akto shows no ticket | Open the run in Port.io and check that the Linear node output contains `issueUrl`.                            |

## Get Support for your Akto setup

There are multiple ways to request support from Akto. We are 24X7 available on the following:

1. In-app `intercom` support. Message us with your query on intercom in Akto dashboard and someone will reply.
2. Join our [discord channel](https://www.akto.io/community) for community support.
3. Contact `help@akto.io` for email support.
4. Contact us [here](https://www.akto.io/contact-us).
