Overview

The Jira integration delivers issue, sprint, and workload telemetry directly into Sizemotion so reviews and retros can reference the engineering work that actually shipped. Open the Integrations Hub to see status badges for Jira alongside your other connectors.

Why it matters

  • Brings Jira issues, sprint health, and cycle time into performance reviews, goals, and 1:1s.
  • Helps managers and leads spot blockers early by surfacing overdue issues and overloaded assignees.
  • Automates data collection, reducing the manual work of compiling charts from multiple tools.

Sync surface

  • Issues & sub-tasks: Fetches active tickets from configured projects and the default board filters.
  • Boards & sprints: Reads Scrum boards, current sprints, and sprint history to drive velocity and retrospective insights.
  • Workload distribution: Calculates assignee workload so you can rebalance commitments.
  • Metrics: Cycle time, lead time, completion rate, and throughput are available via the metrics API.

Setup & validation

Only account admins can configure the Jira connector. The integration flow validates credentials before saving.

  1. Open the Integrations Hub: Visit /integration/manage and select the Jira card to view status and quick actions.
  2. Gather API credentials: Create an API token at https://id.atlassian.com/manage/api-tokens and note the username (email) tied to it.
  3. Configure the connector: Go to /integration/jira/config, enter the Jira base URL, email, and API token, select the relevant projects, and test the connection. The controller ensures the URL, email, and token validate before persisting.
  4. Choose projects & boards: After saving, pick which projects and boards the sync should include; the default behavior is all Scrum boards under the specified projects.

Permissions

Follow least-privilege security:

  • Only admins can POST to /integration/jira/config or modify the connector via the hub.
  • Store credentials in your secrets manager and rotate tokens when team members leave.
  • The integration caches Jira responses for 30-120 minutes but revalidates 401s immediately.
  • Audit events log who configured or reconnected the Jira integration.

Workflow & metrics

Once enabled, the integration runs every 15 minutes and surfaces data in overview, metrics, and 1:1 contexts.

  • Overview page: Open /integration/jira to see synced issues grouped by project, sprint, and status.
  • Metrics endpoint: View cycle time, completed story points, and sprint velocity at /integration/jira/metrics.
  • Workload insights: Use the Jira data when discussing capacity during planning or coaching sessions.

Monitoring

  • The Integrations Hub shows live status badges (green = healthy, amber = attention, gray = disabled).
  • Error summaries explain if Jira responds with 401, 403, or rate limit headers so admins can act quickly.
  • Manual sync triggers are available from the config page if you need an immediate refresh.

Troubleshooting

  • Invalid URL format: Ensure you use the full cloud domain (e.g., https://your-domain.atlassian.net).
  • "Attempt to read property 'id' on null": Confirm the admin user has a personal team (withPersonalTeam()) so the controller can resolve their account.
  • Disabled integration: Re-enable it via /integration/manage/jira or refresh the credentials.
  • Token expired or blocked: Generate a new API token in Atlassian, then paste it on the config screen.

FAQs

Can I limit the sync to specific boards?

Yes, configure the projects and boards on the config page. The service only polls selected Scrum boards to reduce noise.

What about Jira Server / Data Center?

Currently only Jira Cloud is supported. For server instances, contact support to plan a custom integration.

How long does the cached data stay valid?

Responses are cached between 30 and 120 minutes depending on data type. You can force a refresh from the config page if needed.

Next steps