Docs Handleiding Digilab Chat (Mattermost)

Handleiding Digilab Chat (Mattermost)

Digilab Chat is de online community van Digilab, op Mattermost. Je logt in met een Pleio-account. Alles werkt in de browser, ook in omgevingen zoals Citrix waar je geen app kunt installeren; de desktop- en mobiele app zijn optioneel.

Eerste keer inloggen

Ga naar digilab.overheid.nl/chat en klik op Inloggen bij Digilab Chat.
Kies op Login bij Digilab voor Login met Pleio. De knop Login met GitLab (Digilab Beheerders) is alleen voor beheerders van Digilab.
Log in bij Pleio: vul je e-mailadres in en kies Log in with password, of Send login link voor een inloglink per e-mail. Heb je nog geen Pleio-account, kies dan Create account en bevestig je e-mailadres. Daarna kom je terug in Digilab Chat.
Zet tweestapsverificatie aan in je Pleio-account (zie hieronder).

Pleio-account

Je account staat bij Pleio, niet bij Digilab. Daar regel je ook:

Tweestapsverificatie: ga naar account.pleio.nl, kies Security en zet Two-factor authentication aan. Wie je Pleio-wachtwoord of e-mail in handen krijgt, kan anders ook in Digilab Chat.
Wachtwoord vergeten: kies op het Pleio-loginscherm Send login link. Je krijgt dan een inloglink per e-mail en hebt geen wachtwoord nodig. Een nieuw wachtwoord stel je in onder Security → Change password.
Ander e-mailadres: pas het aan onder Profile op account.pleio.nl. Je Digilab Chat-account hangt aan je Pleio-account, niet aan je e-mailadres, dus je houdt je kanalen en berichten.

Log altijd in met hetzelfde Pleio-account. Een tweede Pleio-account geeft een tweede, leeg account in Digilab Chat.

Desktop- en mobiele app

Installeer de Mattermost-app: desktop, of Mattermost in de App Store of Google Play.
Vul als server-URL in: https://digilab.overheid.nl/chat
Klik op Inloggen bij Digilab Chat en log in met Pleio, zoals hierboven.

Kanalen en berichten

Kanaal zoeken: klik onderaan de kanalenlijst op Add Channels → Browse channels, of gebruik Find channel bovenaan. Klik op een kanaal en daarna op Join.
Direct bericht: klik op + naast Direct Messages en zoek op naam.
Meldingen: klik op het tandwiel rechtsboven en kies Notifications.

Bots

Soort	Wat het doet	Wie richt het in
Notificatie-bot (incoming webhook)	Een tool, zoals CI of monitoring, plaatst berichten in één kanaal	De team-admin van je team
Commando (slash command, outgoing webhook)	`/deploy` of een trefwoord roept een tool van je team aan	De team-admin van je team
Interactieve bot	Een programma met een eigen account leest mee en reageert	Alleen bij uitzondering, zie hieronder

Ben je geen team-admin, vraag het dan aan de team-admin van je team. In Digilab Chat kun je niet zien wie dat is: vraag het aan je teamgenoten. Weet niemand het, vraag het dan met de naam van je team in het kanaal Mattermost van team Digilab.

Regels voor notificatie-bots

Een uitgelekte webhook-URL kan misleiden

Wie de URL van een webhook heeft, kan in het kanaal posten onder elke naam en met elk icoon, ook als een collega of als “Digilab beheer”. In de app staat er altijd BOT bij, maar een pushnotificatie op je telefoon of desktop toont alleen kanaal, naam en tekst. Daarom:

Eén apart kanaal per bot, waarvan de naam laat zien dat er alleen automatische berichten komen, bijvoorbeeld deploy-notificaties of alerts-monitoring. Zet in de kanaalkop welke tool er post. Gebruik het kanaal niet voor gesprekken.
De naam van de tool als afzender, nooit die van een persoon, een team of Digilab.
De URL is een wachtwoord. Bewaar hem in een CI-variabele of secret store, nooit in een repository, chat of ticket. Is hij uitgelekt, verwijder de webhook dan onder Incoming Webhooks en maak een nieuwe aan.
Een icoon op een host die je zelf beheert. De host van het icoon kan zien wie het kanaal leest.

Notificatie-bot inrichten (team-admin)

Klik linksboven op het menu met negen puntjes en kies Integrations. Zie je Integrations niet, dan ben je geen team-admin.
Kies Incoming Webhooks en klik op Add Incoming Webhook.
Vul een titel in en kies het botkanaal. Digilab Chat zet elke webhook vast op zijn kanaal: de webhook kan nergens anders posten, ook niet in een direct bericht. Vul bij Username en Profile Picture de naam van de tool en de URL van een icoon in.
Klik op Save en kopieer de URL naar de plek waar je tool hem als geheim bewaart.

Test de webhook:

curl -X POST -H 'Content-Type: application/json' \
  -d '{"text":"Hallo"}' \
  <webhook-url>

Een tool kan per bericht een andere naam en icoon meesturen met username en icon_url, zoals Alertmanager, Flux en Argo CD doen:

curl -X POST -H 'Content-Type: application/json' \
  -d '{"username": "alertmanager",
       "icon_url": "https://monitoring.example.org/alertmanager.png",
       "text": "Pod api-7f9c herstart steeds opnieuw."}' \
  <webhook-url>

Zo ziet dat eruit in het kanaal; berichten van een webhook krijgen in de app altijd het label BOT:

Een bericht van de webhook met de naam alertmanager, een eigen icoon en het label BOT

Commando inrichten (team-admin)

Slash command: kies onder Integrations voor Slash Commands → Add Slash Command. Vul het trefwoord en de URL van je tool in. Na het opslaan krijg je een token; je tool controleert daarmee dat een verzoek van Digilab Chat komt.

Een ingevuld slash command

Outgoing webhook: kies onder Integrations voor Outgoing Webhooks → Add Outgoing Webhook. Vul het trefwoord in en bij Callback URLs de URL van je tool. Na het opslaan krijg je een token; je tool controleert daarmee dat een verzoek van Digilab Chat komt. Kies altijd een kanaal, een openbaar kanaal waarin je team werkt, zoals team-tools; niet het kanaal van een notificatie-bot. Zonder kanaal stuurt Digilab Chat elk bericht met het trefwoord, uit alle openbare kanalen van het team, naar je tool.

Een outgoing webhook met een kanaal, een trefwoord en een callback-URL

Interactieve bot

Een interactieve bot leest alle openbare kanalen van zijn teams mee en kan iedereen een bericht sturen. Daarom maken we die alleen bij uitzondering. Een notificatie-bot of commando volstaat bijna altijd. Denk je dat jouw geval een uitzondering is, vraag het dan in het kanaal Mattermost van team Digilab: wat moet de bot doen, en waarom volstaat een notificatie-bot of commando niet?

Uitloggen

Klik rechtsboven op je profielfoto en kies Log out.

Daarmee ben je uitgelogd uit Digilab Chat, maar niet bij het Digilab-inlogscherm: de volgende keer dat je op Inloggen bij Digilab Chat klikt, log je direct weer in met hetzelfde account. Wil je met een ander account inloggen, log dan ook daar uit via Uitloggen bij Digilab-login. Die link staat ook op de loginpagina van Digilab Chat.

Problemen oplossen

Ik heb per ongeluk GitLab gekozen, of kom steeds met het verkeerde account binnen. Log uit bij Digilab Chat en daarna via Uitloggen bij Digilab-login. Klik opnieuw op Inloggen bij Digilab Chat en kies Login met Pleio.

Ik krijg een foutmelding of ‘geen toegang’ na het inloggen. Meestal ben je met het verkeerde account ingelogd. Volg de stappen hierboven.

Ik ben mijn wachtwoord vergeten. Kies op het Pleio-loginscherm Send login link.

Ik heb een nieuw e-mailadres (bijvoorbeeld een nieuwe werkgever). Wijzig het in je Pleio-account onder Profile. Maak geen nieuw Pleio-account aan: dan krijg je een tweede, leeg account in Digilab Chat.

Ik krijg geen meldingen op mijn telefoon. Controleer in de app het tandwiel → Notifications, en in de instellingen van je telefoon of Mattermost meldingen mag sturen.

Kom je er niet uit? Stel je vraag in het kanaal Mattermost van team Digilab. Kun je niet inloggen, stuur dan een bericht via het contactformulier; daarvoor hoef je niet ingelogd te zijn.