# Manage Task Integrations

This how-to describes how to set up and use issue integrations (Jira, GitHub, GitLab, and others) and calendars to import and link tasks from external systems. For an overview of how integrations work, see [[4.24-Integrations]]. For a comparison of which provider supports worklogs, status transitions, subtasks, and other features, see [[3.07-Issue-Integration-Comparison]].

## Open the Issue and Calendar Panel

The **issue provider panel** (Integrations & Calendars) is a side panel that lists your configured providers and lets you search and add issues or calendar events as tasks.

**From the header:** Click the panel button that shows or hides the issue provider panel. Its tooltip is **Show/hide issue provider panel**. On desktop it appears in the top bar; on mobile it is in the side menu.

**With the keyboard:** If configured, use the shortcut for “Show/hide issue provider panel” (see [[3.02-Settings-and-Preferences]] → Keyboard and [[3.03-Keyboard-Shortcuts]]).

## Add a New Integration (issue Provider or calendar)

1. Open the issue provider panel (see above).
2. Click the **last tab** — the one with the **plus (add)** icon. The view shows two sections: **Connect Calendar** and **Setup Issue Provider**.
3. **For a calendar:** Under **Connect Calendar**, click **Google Calendar**, **Outlook 365**, or **iCal Other**. A configuration dialog opens (e.g. URL for iCal, or OAuth for Google/Outlook). Fill in the details and save.
4. **For an issue provider:** Under **Setup Issue Provider**, click the provider you want: **Jira**, **Trello**, **GitHub**, **Redmine**, **GitLab**, **CalDAV**, **Open Project**, **Gitea**, **Linear**, or **ClickUp**. A configuration dialog opens. Enter the required fields (host URL, token or password, project/repo ID, etc. — the exact fields depend on the provider). Save to create the integration.

### Calendar Integrations: iCal Vs CalDAV (e.g. Nextcloud)

**iCal** and **CalDAV** are two different integrations and need **different link types**:

- **iCal (Calendar):** Use a **subscription** or **export** URL. No login. The app shows **events** (VEVENT) in the Schedule/Planner. In **Nextcloud**, use **“Copy subscription link”** and paste it into **“URL of the iCal source”** in the app. Do **not** use “Copy private link” for iCal—that is for CalDAV.
- **CalDAV:** Use the **CalDAV URL** for your user and calendar, and enter **username and password**. The app shows **tasks/todos** (VTODO) and can sync completion back. In **Nextcloud**, use **“Copy private link”** (or the CalDAV calendar URL, e.g. `…/remote.php/dav/calendars/<USER>/<CALENDAR>/`). Do **not** use the subscription link for CalDAV.

If the integration “doesn’t work,” check that you used the right link and the right provider (iCal vs CalDAV). For more detail see [[4.24-Integrations]] and [[3.07-Issue-Integration-Comparison]].

After saving, a new **tab** appears in the panel for that provider. You can have multiple instances of the same type (e.g. two Jira configurations) and reorder tabs by dragging.

## Add an Issue or Calendar Item as a Task

1. Open the issue provider panel and select the **tab** for the provider (e.g. Jira or GitHub).
2. **For issue providers:** In the **Search** field, type a query (syntax depends on the provider; a hint or link to search syntax may appear). Matching issues are listed. Click the **add (plus)** button next to an issue to add it as a task in the current project. The task is linked to that issue.
3. **For calendars (e.g. iCal):** The tab may show an agenda or list of events. Use the controls in that tab to add an event as a task or open it, depending on the calendar integration.

Tasks added from the panel are created in the **current project** (or the default project set for that provider; see below).

## Edit or Reconfigure an Integration

**From the provider tab:** In the **header** of the provider tab there is a **settings (gear)** icon. Click it to open the same configuration dialog and change host, token, project, or other options. Save to apply.

**From the tab label:** **Long-press** (or long-click) on the provider’s **tab** (the tab with the provider icon and initials). The configuration dialog opens. This is useful on mobile or when the tab is selected.

## Set a Default Project for an Integration

When a provider has a default project set, new issues added from that provider’s tab are created in that project. In the **header** of the provider tab you may see an arrow and a project name; that is the current default. To change it, open the provider’s **settings** (gear icon or long-press on the tab) and set the default project in the dialog, if the provider supports it.

## Add Existing Issues from the Add Task bar (search mode)

You can also add issues (and existing tasks) without opening the issue panel:

1. Open the **add task bar** (e.g. **Shift+A** or the “Add new task” button).
2. Click the **search** icon or press **Ctrl+2** (if configured) to switch to **issue search** mode. The placeholder becomes “Add existing task or issues…”.
3. Type to search across configured providers and your tasks/archive. Select an issue from the list to add it as a linked task in the current context.

See [[2.03-Add-Tasks]] for more on the add task bar and search mode.

## Project-level Integration Settings

Some integrations can be configured **per project** (e.g. which Jira project to use). Open **Project settings** for the project (via the project menu or sidebar) and look for the **Issue Integration** or provider-specific section. There you can attach a project to a given issue provider or override integration settings for that project.

## Troubleshooting

- **No issues in search / “Check your config!”:** Open the provider’s **settings** (gear in the tab) and check host URL, token, and project/repo ID. Test the connection if the dialog offers it. For Jira in the **web app**, a browser extension may be required; the tab will show a notice if so.
- **Provider tab is disabled:** The tab appears grayed out when the provider is disabled. Long-press the tab (or use the settings gear from another route) to open the dialog and enable it again.
- **Issues not updating:** Some providers poll for updates on an interval. Check the provider’s configuration for options like “Check for updates every X” or polling interval. Refreshing the list in the tab may also trigger an update.
