c7d6131db8
* feat(plainspace): add Collaborate action to project context menu Surface Plainspace sharing from the project context menu (active, non-Inbox, not-yet-shared projects) so it can be discovered at the moment of collaboration intent, reusing PlainspaceShareService. A new selectIsProjectSharedOnPlainspace selector hides the action once a project is shared to avoid provisioning a duplicate space on a repeat click. * docs(plainspace): document collaboration in wiki Add Plainspace to the issue-integration comparison (matrix + per-provider section) and a how-to for sharing a project via the project menu, including the network/privacy caveat. * feat(plainspace): place Collaborate action below the share-list item Group the two share/export actions and lift Collaborate higher for discoverability. Gated to active, non-inbox, not-already-shared projects. * fix(plainspace): smoother first-run connect and value-first dialog Pre-check connectivity and revalidate a stored token before the space picker, so a stale/foreign token routes to the connect dialog and an offline state shows a calm message instead of the raw 'check your token' picker error. Make the connect dialog value-first: lead with what you get, drop the 4-step how-to and email hint in favor of one short pointer (token-creation guidance moves to plainspace.org). * docs(plans): dedicated from-Super-Productivity flow on plainspace.org Open plan for a guided token/connect flow on plainspace.org when a user arrives from SP (Model A manual token, Model B OAuth-style handoff). * refactor(plainspace): drop redundant connect pre-check (multi-review) The space picker already detects a stale token and offers a reconnect (#8616), so the revalidate() pre-check duplicated that path, cost an extra GET /me, and forced re-auth on a valid token during a transient server blip. Keep only the one-line offline guard; drop revalidate(), the discriminated union, and the unnecessary _isOnline() seam (navigator .onLine is spyable in the runner). Fix stale doc comments and document the disabled-provider trade-off in the selector. * feat(plainspace): show brand icon in the connect dialog title * feat(plainspace): deep-link connect dialog to the from-SP onboarding flow Point the dialog's 'Open Plainspace' link at the dedicated /connect/super-productivity entrypoint (which guides token creation) instead of the bare marketing host, closing the connect-flow funnel leak. * feat(plainspace): bounce back to the app after connecting (desktop) Append a validated `?return=superproductivity://plainspace-connect` deep link to the connect URL, gated on IS_ELECTRON (only desktop registers the scheme — web/mobile would get dead buttons). Handle that action in the Electron protocol handler by surfacing the window, so the connect page's "Open Super Productivity" button re-focuses the app. Desktop-only; needs an on-device check.
8.3 KiB
Executable file
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)
- Open the issue provider panel (see above).
- Click the last tab — the one with the plus (add) icon. The view shows two sections: Connect Calendar and Setup Issue Provider.
- 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.
- For an issue provider: Under Setup Issue Provider, click the provider you want: Jira, Trello, GitHub, Redmine, GitLab, CalDAV, Open Project, Gitea, Linear, ClickUp, or Plainspace. 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. For Plainspace (collaboration), the easiest path is the project menu — see Collaborate on a Project with Plainspace below.
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.
Azure DevOps and Self-Hosted TFS URLs
For Azure DevOps, enter the full organization or collection URL in Host. For Azure DevOps Services this looks like https://dev.azure.com/<organization>. For self-hosted Azure DevOps Server/TFS this can include the collection path, for example https://server:8080/tfs/DefaultCollection. The separate Project field is still required.
Add an Issue or Calendar Item as a Task
- Open the issue provider panel and select the tab for the provider (e.g. Jira or GitHub).
- 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.
- 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:
- Open the add task bar (e.g. Shift+A or the “Add new task” button).
- Click the search icon or press Ctrl+2 (if configured) to switch to issue search mode. The placeholder becomes “Add existing task or issues…”.
- 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.
Collaborate on a Project with Plainspace
Plainspace is Super Productivity's optional collaboration layer: it turns a local project into a shared Space so you can work on it with others. Tasks assigned to you import automatically, and done state, title, and schedule stay in sync both ways. This is a network feature — task data in a shared project leaves your device; your other projects and core offline use are unaffected.
Share an existing project:
- Open the project's context menu (the ⋮ menu next to the project in the sidebar, or the project header menu).
- Click Collaborate on Plainspace.
- If you haven't connected yet, a guided dialog asks for a Plainspace API token (
pat_…). Create one in Plainspace under a Space → People → Advanced → API tokens, then paste it. - Choose to create a new Space for this project or link an existing one, then confirm. A bound Plainspace provider is created and tasks assigned to you start importing.
Share at creation time: When creating a project, enable Collaborate on this project on Plainspace in the create-project dialog to do the same in one step.
Once a project is shared, the Collaborate on Plainspace menu item is hidden for it. Unclaimed tasks in the Space appear in a claim pool in the work view, where you can claim them into your own list.
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.