npm-its-doc/README.md

Jira Workflow Automation (NPM + Docker + TeamCity)

Dieses Projekt automatisiert folgenden Ablauf:

1. Letzte Jira Tickets anhand einer JQL abfragen.
2. Zusammenfassung erzeugen (Status-Verteilung + Ticketliste).
3. Neues Jira Ticket in einem anderen Projekt/Board erstellen.
4. Optional Xray/Sonar Links und Loesungsversion in den Report aufnehmen.
5. Optional eine Atlassian Wiki/Confluence Seite erzeugen.
6. HTML-Report erzeugen und optional per E-Mail versenden.

Voraussetzungen

• Node.js 20+
• Docker
• Jira Cloud API Token
• Optional: SMTP Zugangsdaten fuer Mailversand

Lokaler Start

npm install
cp .env.example .env
npm run dry-run

Wenn alles passt:

npm start

Wichtige Umgebungsvariablen

Pflicht:

• JIRA_BASE_URL
• JIRA_USER_EMAIL
• JIRA_API_TOKEN
• JIRA_TARGET_PROJECT_KEY oder JIRA_TARGET_BOARD_ID

Empfohlen:

• JIRA_SOURCE_JQL (z. B. project = SRC ORDER BY updated DESC)
• JIRA_SOURCE_MAX_RESULTS (Default: 10)
• JIRA_TARGET_ISSUE_TYPE (Default: Task)
• JIRA_TARGET_SUMMARY_PREFIX (Default: Automatischer Jira Report)
• JIRA_TARGET_LABELS (CSV)
• SOLUTION_VERSION (setzt auch fixVersions im Jira Ticket)
• XRAY_REPORT_URL (optional)
• SONAR_REPORT_URL (optional)
• JIRA_DRY_RUN (true/false)
• OUTPUT_HTML_PATH (Default: report-output/report.html)
• JIRA_CLOSE_ISSUE_KEYS (CSV, optional; z. B. ABC-1,ABC-2)
• JIRA_CLOSE_JQL (optional; Tickets fuer Schliessung per JQL ermitteln)
• JIRA_CLOSE_JQL_MAX_RESULTS (optional; Default: 100)
• JIRA_CLOSE_ALLOWED_STATUSES (CSV, optional; z. B. Done,Resolved)
• JIRA_CLOSE_TRANSITION_NAME (optional; Default: Geschlossen)
• JIRA_CLOSE_RESOLUTION_NAME (optional; z. B. Erledigt)

Atlassian Wiki / Confluence optional:

• ATLASSIAN_WIKI_ENABLED (true/false, Default: false)
• ATLASSIAN_WIKI_SPACE_KEY (Confluence Space Key, Pflicht wenn aktiviert)
• ATLASSIAN_WIKI_PARENT_PAGE_ID (optional)
• ATLASSIAN_WIKI_TITLE_PREFIX (Default: Automatischer Jira Wiki Report)
• ATLASSIAN_WIKI_BASE_URL (optional, Default: JIRA_BASE_URL)
• ATLASSIAN_WIKI_USER_EMAIL (optional, Default: JIRA_USER_EMAIL)
• ATLASSIAN_WIKI_API_TOKEN (optional, Default: JIRA_API_TOKEN)

SMTP optional:

• SMTP_ENABLED=true
• SMTP_HOST, SMTP_PORT, SMTP_SECURE
• SMTP_USER, SMTP_PASS
• SMTP_FROM, SMTP_TO
• SMTP_SUBJECT_PREFIX

Docker Nutzung

Image bauen:

docker build -t its-workflow-npm:local .

Container starten:

docker run --rm --env-file .env -v "$(pwd)/report-output:/opt/app-root/src/report-output" its-workflow-npm:local

TeamCity Integration

Empfohlene Build Steps:

1. Command Line (Linux Agent):
   • Script: sh teamcity/run-workflow.sh
2. Alternativ PowerShell (Windows Agent):
   • Script file: teamcity/run-workflow.ps1

Lege in TeamCity die Variablen als Parameter vom Typ env.* an, z. B.:

• env.JIRA_BASE_URL
• env.JIRA_USER_EMAIL
• env.JIRA_API_TOKEN (als Password Parameter)
• env.JIRA_SOURCE_JQL
• env.JIRA_TARGET_PROJECT_KEY
• env.SOLUTION_VERSION
• env.XRAY_REPORT_URL
• env.SONAR_REPORT_URL
• env.JIRA_CLOSE_ISSUE_KEYS
• env.JIRA_CLOSE_JQL
• env.JIRA_CLOSE_JQL_MAX_RESULTS
• env.JIRA_CLOSE_ALLOWED_STATUSES
• env.JIRA_CLOSE_TRANSITION_NAME
• env.JIRA_CLOSE_RESOLUTION_NAME
• env.ATLASSIAN_WIKI_ENABLED
• env.ATLASSIAN_WIKI_SPACE_KEY
• env.ATLASSIAN_WIKI_PARENT_PAGE_ID
• env.SMTP_ENABLED
• env.SMTP_HOST ...

Der Report wird im Build-Workspace unter report-output/report.html abgelegt und kann als Build Artifact publiziert werden.

Ablauf im Fehlerfall

• Jira API Fehler werden mit Antwortdetails ausgegeben.
• Bei SMTP_ENABLED=true ohne vollstaendige SMTP Daten wird der Lauf abgebrochen.
• Bei JIRA_DRY_RUN=true wird kein Ticket erstellt, aber Report + optional Mail erzeugt.