🚀 Jirotion

Jira to Notion — Sync Jira issues assigned to you to Notion with an interactive terminal UI.

Prerequisites

• Node.js >= 18.0.0
• Jira account with API access
• Notion account with API access

Installation

Install globally via npm:

npm install -g jirotion

After installation, configure your credentials:

jirotion config

Note: The config command will detect missing settings and prompt you to set them up interactively.

Getting API Tokens

Jira API Token

1. Open your Atlassian Account Settings
2. Go to the Security tab
3. Click Create and manage API tokens
4. Click Create API token
5. Choose a name (e.g., "Jirotion") and an expiration date
6. Click Create
7. Copy the generated token and store it securely

⚠️ Important: Save the token immediately — you won't be able to see it again!

Notion Integration

1. Go to Notion Integrations
2. Click New integration
3. Choose a name (e.g., "Jirotion")
4. Optionally add an icon
5. Select the Associated workspace
6. Click Create
7. Click Configure integration settings
8. Copy the Internal Integration Secret and store it securely

Notion Database ID

1. Open the Notion database where you want to create tasks
2. Click ... in the top-right corner
3. Click Copy link
4. From the URL, extract the Database ID: notion.so/DatabaseName-{THIS_IS_THE_ID}?source=...
5. Go back to your database, click ... → Connections → Add the Jirotion integration

⚠️ Important: You must connect the integration to the database, otherwise Jirotion won't be able to access it!

Usage

Configuration

jirotion config

First-time setup — runs all sections in sequence: Jira → Notion → Todo items.

Existing config — shows a summary and opens a menu to update only the section you need:

? What would you like to update?
❯ 🔑  Jira credentials
  📓  Notion credentials & databases
  📋  Default todo items
  ✅  Exit

Each section saves independently. Secret fields (API tokens, Notion key) can be left blank to keep the current value. Press Ctrl+C at any point to cancel without saving.

Interactive Sync (Main Feature)

Sync a Jira issue to Notion interactively:

jirotion sync

Workflow:

1. 🔍 Fetch Issues — Your unresolved Jira tasks are loaded
2. ✅ Select Issue — Choose the issue you want to sync
3. 📁 Database — Auto-selects "Tasks" database (or prompts if multiple)
4. 📂 Select Project — Optionally link the task to a Notion project (automatically syncs Stacks if configured)
5. 📋 Customize Todo — Optionally add extra todo items between the configured start and end items
6. ✏️ Edit Title — Review and edit the formatted title before import
7. ✨ Task Created — Your Jira issue is now in Notion!
8. 📝 Linked Notes — Automatic creation of "Task info" and "Difficulties" in your Notes DB (if configured)

Features

• 🏗️ Smart Task Titles — Automatically formats Jira summaries and lets you edit them before sync.
• 📋 Configurable Todo Lists — Define default start and end todo items in jirotion config. Items added during sync are inserted between them.
• 🔗 Project & Stack Sync — Linking a project automatically pulls its associated Stacks into the new Notion task.
• 📓 Automatic Notes — Creates linked "Task info" and "Difficulties" pages in a Notes database, with status set to Done and Jira description pre-filled as a bullet list in "Task info".
• ⚙️ Flexible Configuration — Supports optional databases (Notes, Stacks) for a more robust workflow.

Each synced task automatically includes a todo list structured as:

• (start items — configured in jirotion config)
• Create branch: git checkout -b feat/PROJ-123
• Publish branch: git push -u origin feat/PROJ-123
• (custom items added interactively during sync)
• Open PR for PROJ-123
• (end items — configured in jirotion config)

Task titles are automatically formatted:

Jira	Notion
[Operations] Anagrafica - Dropdown	[WG-5345] Operations - Anagrafica - Dropdown
[FE] EMISSIONE FIR DIGITALE: Aggiungere regole	[WAS-926] Emissione Fir Digitale - Aggiungere regole

Sync a Specific Issue

Quickly sync a Jira issue by key:

jirotion sync --key PROJ-123

Sync to a Specific Database

jirotion sync --key PROJ-123 --database <notion-database-id>

List Your Jira Tasks

jirotion list

Tech Stack

• Language: TypeScript
• CLI Framework: Commander.js
• Prompts: Inquirer.js
• Jira Client: Axios
• Notion Client: @notionhq/client
• Loading Indicators: Ora
• Styling: Chalk

Development

Clone the repository:

git clone https://github.com/FRJess/jirotion.git
cd jirotion
npm install

Run in development mode:

npm run dev

Build for distribution:

npm run build

License

MIT