How to Route Automated Work into Linear Issues with Jinba

Summary

• Linear API authentication: Send the personal API key directly in the Authorization header; adding Bearer is a common cause of UNAUTHENTICATED.
• Resolve team IDs first: Run LINEAR_LIST_TEAMS to get the target team's UUID, because Linear only accepts team_id, not human-readable team names.
• Create and chain issues: LINEAR_CREATE_ISSUE needs team_id and title; capture the returned issue ID to add comments and monitor progress.
• Automate the full lifecycle: Use LINEAR_ADD_ISSUE_COMMENT for audit trails and LINEAR_GET_ISSUES / LINEAR_GET_PROJECT_PROGRESS with AI summaries to eliminate manual status reporting, which costs senior engineers roughly two hours per week.
• Skip custom code with Jinba: Jinba Flow provides native Linear steps to build this multi-step automation without owning API integrations.

To open a Linear issue from a workflow, use the LINEAR_CREATE_ISSUE step with config: api_key set to your Linear personal API key, plus input: team_id and input: title. Run LINEAR_LIST_TEAMS first to resolve the correct team_id. The workflow is complete once the issue is created and its ID is returned for downstream steps.

Linear's API is capable. The built-in automation layer is not. Teams that migrate to Linear quickly find that native automations are limited to single-trigger, single-action, per-team workflows with no support for conditional logic, cross-team rules, or multi-step sequences. The LinearAPI exists precisely to fill that gap, but reaching for it means writing and maintaining code that most teams would rather not own.

Jinba bridges that gap. The steps below walk through a complete linear automation flow: from storing credentials to tracking issue progress, using only Jinba's native Linear steps and no custom code.

Step 1: Generate and store your Linear API key

Linear authenticates API requests with a personal API key, a long-lived credential tied to your user account and sent in the Authorization header of every request. Unlike OAuth, there is no token exchange or redirect flow. The key is static and user-scoped, which makes configuration straightforward.

To generate one:

1. Log in to your Linear workspace at linear.app.
2. Go to Settings → Account → Security & Access.
3. Scroll to Personal API keys and click Create API key.
4. Name the key descriptively, for example Jinba-Automation, and copy it immediately. It is shown only once.

Store the key in an environment variable or secrets manager. Never commit it to version control or expose it in client-side code. In Jinba, reference it through the config block:

config:
api_key: "{{env.LINEAR_API_KEY}}"

One important note on the Authorization header format: Linear expects the key directly, not prefixed with Bearer. Using Bearer YOUR_KEY is a common source of UNAUTHENTICATED errors. The correct format is Authorization: YOUR_KEY.

Step 2: Resolve the team ID with LINEAR_LIST_TEAMS

The Linear API operates on internal UUIDs, not human-readable names. You cannot target the "Backend" or "Platform" team by name. Every issue creation call requires the team's unique team_id.

Use LINEAR_LIST_TEAMS to fetch all teams in the workspace:

- step: LINEAR_LIST_TEAMS
config:
api_key: "{{env.LINEAR_API_KEY}}"

The response returns each team's id, name, and key. Run this step once, identify the ID for your target team, and store it. In a dynamic workflow, you can pass the ID forward as a variable. In a static workflow, hardcode it after the initial lookup.

Step 3: Create the issue with LINEAR_CREATE_ISSUE

With the team_id in hand, LINEAR_CREATE_ISSUE creates a fully formed issue in a single step. The required inputs are team_id and title. Optional inputs give the issue the context it needs to be actionable from the moment it lands.

Key parameters:

• team_id: The UUID from LINEAR_LIST_TEAMS.
• title: A concise, descriptive string.
• description: Markdown is supported. Use it to include structured context such as error messages, stack traces, or customer details.
• priority: An integer. 0 is No Priority, 1 is Urgent, 2 is High, 3 is Medium, 4 is Low.
• assignee_id: The UUID of the team member to assign the issue to.

- step: LINEAR_CREATE_ISSUE
config:
api_key: "{{env.LINEAR_API_KEY}}"
input:
team_id: "{{steps.list_teams.output.team_id}}"
title: "Payment gateway timeout - production"
description: |
## Summary
Timeout errors on the payment gateway detected at 14:32 UTC.

## Impact
Affects checkout flow for all users on plan tier Enterprise.
priority: 1
assignee_id: "{{env.ON_CALL_ENGINEER_ID}}"

The step returns the new issue's id. Capture it. Every subsequent step in the workflow that references this issue, whether to add a comment, update status, or query progress, depends on it.

One common issue to be aware of: automated issues created via the API can land in the backlog rather than the triage inbox. This is a reported pattern among teams using external tools to create issues. To ensure issues route to triage, verify that the target team has the Triage feature enabled under Settings → Teams → [Team] → Features. You can also set a triage responsibility assignee so that all incoming triage issues are automatically assigned without manual intervention.

Step 4: Add context with LINEAR_ADD_ISSUE_COMMENT

Issue creation is the start, not the end. The comment thread is where engineers get the information they actually need: raw log output, customer account IDs, links to monitoring dashboards, reproduction steps.

Use LINEAR_ADD_ISSUE_COMMENT with the issue_id from the previous step:

- step: LINEAR_ADD_ISSUE_COMMENT
config:
api_key: "{{env.LINEAR_API_KEY}}"
input:
issue_id: "{{steps.create_issue.output.id}}"
body: |
**Source:** Payment monitoring alert
**Error code:** GATEWAY_TIMEOUT
**Affected users:** 412
**Trace ID:** abc-9821-xyz

This step creates a clear audit trail. Every automated workflow that touches the issue leaves a timestamped comment, which means engineers can reconstruct what happened and when without context-switching to a separate system. Effective linear automation treats the comment thread as structured data, not a scratchpad.

Step 5: Monitor progress with LINEAR_GET_ISSUES and an AI summary step

Creating the issue closes one loop and opens another. Teams that automate issue creation without automating follow-up end up with the same information gaps they had before: no visibility into whether the issue moved, who touched it, or whether the project it belongs to is on track.

LINEAR_GET_ISSUES retrieves the current state of one or more issues. LINEAR_GET_PROJECT_PROGRESS returns a higher-level view across all issues attached to a project, including completion percentage and remaining work. Both steps take the same api_key config.

- step: LINEAR_GET_PROJECT_PROGRESS
config:
api_key: "{{env.LINEAR_API_KEY}}"
input:
project_id: "{{env.PROJECT_ID}}"

The practical use case is a scheduled summary workflow. Run LINEAR_GET_ISSUES on a filtered set of issues, pipe the output into an AI summarization step, and post the result to a Slack channel or email distribution list. This approach removes cross-project blind spots that emerge when teams grow and no single person tracks all active work. A senior engineer who spends roughly two hours per week on manual triage and status reporting recovers most of that time when summarization and triage routing run automatically.

Common errors and how to handle them

UNAUTHENTICATED: The API key is missing, malformed, or includes a Bearer prefix that Linear does not expect. Verify the key value and the header format.

FORBIDDEN: The key's associated user does not have permission to act on the specified team or project. Check team membership and role in Settings → Members.

Rate limits: High-volume batch creation, such as importing a backlog from another tool, risks hitting Linear's API rate limits. Structure batch workflows with a delay between steps or a retry-with-backoff strategy.

Issues landing in backlog instead of triage: Enable the Triage feature at the team level and confirm a triage responsibility assignee is configured. Issues created via the API follow the same routing rules as manual issues, so the team setting governs where they land.

What to build next

The five-step pattern, store credentials, resolve team ID, create the issue, add context, monitor progress, covers the full lifecycle of an automated issue. It works for bug reports triggered by monitoring alerts, support escalations routed from a helpdesk, and recurring operational tasks that need a tracked owner each sprint.

The next step is to identify one repetitive source of issues in your current workflow, whether that is an alert that engineers triage manually each morning or a customer report that gets copied into Linear by hand, and replace that manual step with a Jinba workflow. The time cost of the current process is the baseline. Measure against it after the first week.

Linear's API is the right foundation. Jinba removes the need to build and maintain the scaffolding around it.

Frequently Asked Questions

How do I create a Linear issue from a Jinba workflow?

Use the LINEAR_CREATE_ISSUE step with your Linear personal API key in config.api_key, plus input.team_id and input.title. First run LINEAR_LIST_TEAMS to get the correct team UUID, then pass the returned issue ID to any downstream steps for comments or status updates.

Which Linear API key do I need for Jinba Linear steps?

You need a personal Linear API key generated from Settings → Account → Security & Access → Personal API keys. Store it in an environment variable or secrets manager and reference it through config.api_key, never hardcode it in your workflow file.

Do I need to add Bearer before my Linear API key?

No. Linear expects the API key directly in the Authorization header. Sending Authorization: Bearer YOUR_KEY is a common cause of UNAUTHENTICATED errors; use Authorization: YOUR_KEY instead.

How do I find my Linear team ID for automation?

Run the LINEAR_LIST_TEAMS step in your Jinba workflow. It returns each team's id, name, and key. Use the UUID in the team_id input of LINEAR_CREATE_ISSUE because the Linear API does not accept human-readable team names.

What does LINEAR_CREATE_ISSUE return?

It returns the newly created issue's id. Capture that value and pass it to subsequent steps such as LINEAR_ADD_ISSUE_COMMENT or LINEAR_GET_ISSUES to keep the workflow connected to the correct issue.

Why do API-created Linear issues land in the backlog instead of triage?

This is a known pattern when external tools create issues. To route them to triage, enable the Triage feature at Settings → Teams → [Team] → Features and set a triage responsibility assignee. Once configured, API-created issues follow the same routing rules as manually created issues.

Can I add comments to a Linear issue from a Jinba workflow?

Yes. Use LINEAR_ADD_ISSUE_COMMENT with the issue_id from LINEAR_CREATE_ISSUE and the markdown body you want to add. This keeps an audit trail of logs, error details, and context directly in the issue thread.

How do I monitor Linear issue progress after creation?

Use LINEAR_GET_ISSUES to check current issue state or LINEAR_GET_PROJECT_PROGRESS for a higher-level project view. A useful pattern is to run those steps on a schedule, pipe the output into an AI summary step, and send the summary to Slack or email.

What are common Linear API errors when using Jinba?

The most common are UNAUTHENTICATED, usually from a missing or malformed key or an incorrect Bearer prefix, and FORBIDDEN, which means the API key's user does not have permission to act on the target team or project. Rate limits can also occur during high-volume batch creation.

Can Jinba replace Linear's native automations?

Yes, Jinba fills the gap left by Linear's built-in automations, which are mostly single-trigger, single-action, per-team workflows. Jinba supports multi-step sequences, conditional logic, cross-team coordination, comments, and progress monitoring without requiring custom code.