Jira: Verbindung einrichten

Verbinde als Admin deine Jira-Site, danach verbindet jedes Teammitglied den eigenen Jira-Account mit einem Klick.

Ein Admin verbindet einmalig deine Jira-Site, und jedes Teammitglied verbindet einmalig den eigenen Jira-Account. Neu hier? Starte mit dem Überblick.

Service-Account-Token erstellen

(Admin, einmalig.)

docket liest mit diesem Token Projekte, Issues und Worklogs. Nach Jira schreibt er nie etwas.

Gehe, angemeldet als Service-Account, zu id.atlassian.com → Security → API tokens.
Klicke auf Create API token, vergib eine Bezeichnung (z. B. docket service account) und wähle genau diese zwei Scopes:

Scope	Wofür
`read:jira-user`	Token prüfen und Nutzerinfos lesen (z. B. Anzeigenamen für die Auslastung)
`read:jira-work`	Projekte, Issues und Worklogs aus Jira lesen

Klicke auf Create und kopiere den Token sofort. Atlassian zeigt ihn nur einmal an.
Füge ihn in docket ein (Teil 1 unten).

Nimm einen eigenen Service-Account („Bot“), nicht den Account einer echten Person. Verlässt die Person das Unternehmen und wird ihr Account deaktiviert, bricht die Verbindung ab.

Was der Service-Account in Jira braucht

Nur Lesezugriff, keine Schreib- oder Admin-Rechte:

Zugang zu Jira: einen Jira-Platz in eurer Atlassian-Organisation.
„Browse projects“ auf jedem Projekt, das du verknüpfst. In einem team-managed Projekt fügst du den Account unter Project settings → Access mit der Rolle Viewer hinzu. In einem company-managed Projekt braucht er eine Projektrolle, die im Berechtigungsschema des Projekts „Browse projects“ hat (oft haben das ohnehin alle angemeldeten Nutzer).
„Browse users and groups“ (globale Berechtigung): nur nötig, um Jira-Personen zu suchen, wenn du sie docket-Nutzern zuordnest (siehe Fragen zu Accounts und Tokens unten).

Ohne Lesezugriff auf ein Projekt meldet Jira keinen Fehler, sondern liefert einfach keine Issues. docket erkennt das und zeigt es rot unter Projekt → Einstellungen → Jira an.

Ihre Zeit schreibt jede Person über die eigene Verbindung nach Jira (Teil 2). Sie braucht also selbst das Recht, auf dem Issue Zeit zu buchen, der Service-Account nicht.

Teil 1: Admin verbindet die Jira-Site

(Admin, einmalig pro Jira-Site.)

Gehe zu Administration → Integrationen und klicke auf Verbindung hinzufügen.
Fülle aus:
- Name, z. B. „Company Jira“.
- Site-URL: https://yourcompany.atlassian.net. docket ermittelt daraus die Jira-cloud_id.
- E-Mail des Service-Accounts und API-Token des Service-Accounts (der Bot-Account).
- Zeiterfassungs-Backend: Lass es auf Jira-eigene Worklogs, außer dein Team erfasst Zeit mit Tempo Timesheets. Dann wähle Tempo und gib den Tempo-API-Token ein.
- Jira-Autoren ohne docket-Account (standardmäßig an): Für jede Person, die in Jira Zeit erfasst, aber keinen docket-Nutzer hat, legt docket einen Platzhalter-Nutzer an, damit ihre Zeit in Budgets und Reports zählt (siehe Wie Zeit aus Jira behandelt wird). Die Leistung, mit der ein neuer Platzhalter startet, bestimmt den Satz, zu dem seine Zeit abgerechnet wird; pro Platzhalter kannst du sie später ändern. Ohne Leistung bleibt die Zeit nur lesbar.
Klicke auf Verbindung hinzufügen. docket prüft die Zugangsdaten sofort gegen Jira: Ein grünes aktiv-Badge heißt, Jira ist erreichbar. Ein rotes Anmeldung fehlgeschlagen-Badge heißt, E-Mail oder Token sind falsch oder haben keinen Zugriff (korrigiere das über ✎ Bearbeiten). Mit ↻ Verbindung testen prüfst du jederzeit neu, z. B. nachdem du den Token rotiert hast.

Teil 2: Jedes Teammitglied verbindet den eigenen Jira-Account

(Alle, die Zeit auf Jira-Tickets buchen, einmalig.)

docket schreibt deine Zeit als du nach Jira. Die Stunden erscheinen dort also unter deinem Namen, nicht unter dem des Bots.

Öffne in deinen Profileinstellungen (dein Name → Einstellungen) den Bereich Jira und klicke auf Mit Jira verbinden.
Wähle auf der Atlassian-Seite deine Jira-Site und klicke auf Accept. Du landest wieder in docket.
docket zeigt Verbunden als mit deinem Jira-Namen und eine ✓/✗-Liste der Jira-Sites deines Workspace:
- ✓: Deine Zeit auf den Projekten dieser Site wird nach Jira synchronisiert.
- ✗ Not shared with docket yet: Du hast diese Site auf der Atlassian-Seite nicht ausgewählt. Klicke auf Weitere Jira-Site hinzufügen und wähle sie aus.
- ✗ mit einer anderen Meldung: Dein Atlassian-Account kommt an diese Site nicht heran, meist weil dir dort der Zugriff fehlt. Frag deinen Admin.

Wenn du diesen Schritt überspringst, kannst du trotzdem Zeit auf Jira-Tickets buchen, sie wird nur nicht nach Jira übertragen. Diese Einträge sind mit „Nicht in Jira — verbinde dein Jira-Konto“ markiert. Sobald du verbunden bist, überträgt docket sie von selbst.

Wenn die Verbindung nicht mehr funktioniert (du hast sie bei Atlassian widerrufen, oder sie wurde etwa drei Monate nicht genutzt), steht das im Jira-Bereich, zusammen mit einem Jira neu verbinden-Button. Außerdem verlangt Atlassian einmal im Jahr von allen, die Verbindung erneut zu bestätigen.

Trennen: Das Papierkorb-Icon neben „Verbunden als“ entfernt die Verbindung aus docket. Um docket den Zugriff ganz zu entziehen, entferne docket zusätzlich in deinem Atlassian-Profil unter Connected apps.

Alternative: ein persönlicher API-Token

Nimm diesen Weg, wenn Mit Jira verbinden nicht angezeigt wird oder der Atlassian-Admin deines Unternehmens das Verbinden von Apps blockiert hat (Atlassian zeigt dann auf seiner Seite einen Hinweis):

Gehe mit deinem eigenen Atlassian-Account zu id.atlassian.com → Security → API tokens, klicke auf Create API token, vergib eine Bezeichnung (z. B. docket) und wähle genau diese zwei Scopes:

Scope	Wofür
`read:jira-user`	Token prüfen (docket checkt, ob er jede verbundene Site erreicht)
`write:jira-work`	Deine Worklogs in Jira anlegen, ändern und löschen

Klicke auf Create und kopiere den Token sofort. Atlassian zeigt ihn nur einmal an.
Klicke im Jira-Bereich von docket auf Stattdessen ein API-Token nutzen, gib deine Atlassian-E-Mail und den Token ein, lass Gilt für auf Standard (alle Verbindungen) und klicke auf Token speichern.

Ein Token gilt für jede Jira-Site, auf die dein Atlassian-Account zugreifen kann.

Fragen zu Accounts und Tokens

Wo finde ich meine Jira-Account-ID? Meist brauchst du sie nicht: docket liest sie aus, wenn du deinen Jira-Account verbindest. Ordnet ein Admin einen docket-User von Hand einem Jira-User zu (Administration → Integrationen → Verbindung → Nutzerzuordnung), tippt er einen Namen oder eine E-Mail ins Jira-User-Feld. docket durchsucht Jira live und trägt die accountId ein, sobald er einen Treffer auswählt. Dafür braucht der Service-Account in Jira die globale Berechtigung „Browse users and groups“ (Jira-Admin → Global permissions, vergeben an eine Gruppe, zu der der Service-Account gehört; volle Jira-Admin-Rechte sind nicht nötig). Bleibt die Suche trotzdem leer, gib die accountId direkt ein. Du findest sie:

in deinem Jira-Profil: dein Avatar (in Jira oben rechts) → Profile. Die Account-ID steht in der URL der Seite: https://yourcompany.atlassian.net/jira/people/5b10ac8d82e05b22cc7d4ef5
über die REST API: Öffne, während du in Jira eingeloggt bist, https://yourcompany.atlassian.net/rest/api/3/myself im Browser. Die JSON-Antwort enthält "accountId": "...".

Brauche ich für alle eine Jira-Lizenz? Ja. Jede Person, die Zeit nach Jira bucht, braucht einen eigenen Atlassian-Account und verbindet ihn, weil ihre Stunden unter ihrem Namen nach Jira geschrieben werden.

Was, wenn wir Tempo für die Zeiterfassung nutzen? Dein Admin stellt die Verbindung auf Tempo. Worklogs werden dann über die Tempo-API mit dem Token der Verbindung geschrieben; die eigenen Verbindungen der Teammitglieder verraten docket nur, wer sie in Jira sind.

Ist meine Verbindung sicher? Deine Verbindung (bzw. dein API-Token) wird verschlüsselt gespeichert und nie wieder angezeigt. Nur du kannst sie verwalten; nicht mal Admins können sie sehen. docket fragt bei Atlassian nur an, was es braucht: das Lesen deiner Jira-Arbeit und Nutzerinfos sowie das Schreiben deiner Worklogs.

Weiter geht's: Projekt verknüpfen und mit dem Tracken loslegen.