Raise bugs from Microsoft Teams

Connect an app, step by step

1. In qarunbook

   Open the app's Microsoft Teams settings

   Open any app, choose Configure, then the Integrations tab, and choose the Microsoft Teams tile under Where bugs are reported.

2. In qarunbook

   Download the Teams app

   Choose Download the Teams app. You get qarunbook-teams.zip. Keep it as it is — Teams takes the zip, not what is inside it.

3. In Microsoft Teams

   Upload it to your organisation

   Either way works:

   • As a Teams admin, in the Teams admin center: Teams apps → Manage apps → Upload new app, and choose the zip.
   • Where your organisation allows custom apps, in Teams: Apps → Manage your apps → Upload an app, and choose the zip.
4. In Microsoft Teams

   Add it to your teams

   Add QA Runbook to the teams and chats that should be able to raise bugs and hear about them. A team must have it before an app can post notices in one of its channels.

5. In qarunbook

   Get a link code

   Back on the card, choose Get a link code. A code like ABCD-EFGH-JKMN appears, with Copy “link …” and Open the bot in Teams. The code works once, for half an hour.

6. In Microsoft Teams

   Send it to the bot

   Choose Open the bot in Teams, or open a chat with QA Runbook yourself, and send link ABCD-EFGH-JKMN. Send it in your 1:1 chat with the bot. The bot answers Linked. This Teams organisation now raises bugs into [your workspace].

7. In qarunbook

   See it linked

   The card notices on its own within a few seconds: Linked to [your organisation]. Every other app in the qarunbook workspace is now linked too.

8. In qarunbook

   Optional: pick a channel for this app

   Choose Change. Under Channel for this app's notices, pick a channel — they are listed as Team › Channel — or leave it on No channel — threads only. Under Tell about, tick New issues, Fixed — ready to retest or Fix verified.

   A workspace admin also sees Who can raise bugs from Teams: Anyone in the Teams organisation or Only QA Runbook members. Choose Save.

Raise a bug from Teams

From a message

1. In Microsoft Teams

   Open the message's menu

   On any message in a channel, a group chat or a 1:1 chat, open More actions (…) and choose Raise as bug.

2. In Microsoft Teams

   Fill in the dialog and choose Raise

   When you can raise on more than one app, pick the App and choose Next; with one, the dialog goes straight to the form. Then:

   • Check: for an app being tested, the check it breaks — type to search. A long plan also takes Not listed? Its reference.
   • Platforms: leave it empty when it happens everywhere.
   • Priority: for a live app.
   • What went wrong: already filled in with the message's words.

   Choose Raise. The dialog says Logged as QA-41 in [app].

By talking to the bot

• bug the login button does nothing — in a channel, mention the bot first. When there is nothing to ask (you can raise on one app, and it is live), the bug is raised at once. Otherwise the bot answers with a Raise as bug… button that opens the same dialog, for you alone.
• link CODE — in a 1:1 chat with the bot, links this Teams organisation to a workspace.
• help, or anything else, says what the bot can do.

Check it works

1. In Microsoft Teams

   Raise a test bug

   In a channel of a team that has QA Runbook, post Test: Teams connection. On that message, choose More actions (…) → Raise as bug, pick the app, and choose Raise.

2. In Microsoft Teams

   See the bot answer

   The bot replies in the message's thread: Logged as QA-41 · Open in QA Runbook.

3. In qarunbook

   Mark it fixed

   Open the issue from the link and choose Mark fixed.

4. In Microsoft Teams

   See the thread hear back

   The bot replies in the same thread, mentioning you: QA-41 has been marked fixed by [name]. Could you check it again? Open in QA Runbook. If you picked a channel for the app, it also gets a card for each notice you ticked.

How it works

A qarunbook workspace links to one Teams organisation, and every app in it shares the link. The code proves which workspace it is; the bot's message proves which Teams organisation. One organisation links to one workspace: a second workspace is told to have the first unlink it.

The issue is raised exactly as one raised in the runbook is, so if the app is connected to Linear, Jira or GitHub, it is filed there too. Files on the message are copied onto it where Teams hands them over. When the issue is marked fixed — in qarunbook, by a merged pull request, from Linear or through the API — the bot says so in the same thread, mentioning whoever raised it, and asks them to check it again. The check reads retest here as usual.

People are matched by the work email address Teams gives for them. Someone whose address belongs to a member of the workspace raises as themselves, on the apps they can test, and is told in qarunbook as well as in Teams when it is fixed. Anyone else in the organisation raises as their name via Teams, on any app in the workspace, and hears back only in Teams — unless the workspace chose Only QA Runbook members. Guests in your organisation can never raise bugs unless their address belongs to a member.

Each app can post any of these to a channel, as a card with a link:

• New issues — raised from anywhere, not only Teams.
• Fixed — ready to retest — whoever fixed it, and where. The reporter's thread hears of a fix whatever is ticked here.
• Fix verified — someone confirmed the fix holds on a live app. Ticked, the reporter's thread hears of it too.

Channels are offered from every team the QA Runbook app has been added to. Add it to a team to post there.

Good to know

• Teams brings bugs in and hears about fixes. It never creates checks or sections — those stay in qarunbook.
• Raised where the bot was never added — a chat or a team without QA Runbook — the replies go to the person in a 1:1 chat with the bot instead, and so does “fixed”.
• Files sent to the bot in a 1:1 chat, and pictures pasted into a message to it, come across: up to ten files, each up to 50 MB, counted against the plan's storage. Files shared in a channel or group chat stay in SharePoint, where only Microsoft Graph can read them — the thread names them, so they can be attached in qarunbook.
• Issues raised from Teams count against a Free workspace's monthly allowance like any other.
• Fixing twice says nothing twice, and reopening an issue says nothing in Teams.
• Unlink stops every app hearing from Teams. Issues raised from Teams keep their place here. The app stays in Teams until someone removes it; until it is linked again, it says it is not linked. Removing the app from a team stops notices to that team's channels.

Troubleshooting

• “Microsoft Teams isn't set up on this site yet.” The site's operator has not registered the bot — see below.
• Upload an app is missing in Teams. Your organisation does not allow custom apps. Ask a Teams admin to upload the zip in the Teams admin center, or to allow custom apps for you.
• Raise as bug is missing from the menu. The app is not installed for you. Add QA Runbook from Apps in Teams, or ask your Teams admin to make it available.
• “This Teams organisation is not linked to QA Runbook yet.” Get a link code in qarunbook and send link and the code to the bot.
• “That code has expired or has been used.” Codes last half an hour and work once; getting a new one replaces the last.
• “Only people with a QA Runbook account…” The workspace allows members only, and your Teams email matches nobody. An admin invites you with the address Teams uses for you.
• No channels to choose from. The bot is in no team yet. Add QA Runbook to a team, then choose Change again.
• Nothing in the thread. The bot cannot post where it was never added; look in your 1:1 chat with it.

For the site's operator

One bot serves every workspace. Register it once in the Teams Developer Portal under Tools → Bot management, with the messaging endpoint https://qarunbook.com/api/integrations/teams/messages, and add a client secret. Set TEAMS_APP_ID to the bot's id and TEAMS_APP_PASSWORD to the secret; when the bot's Microsoft Entra app is single-tenant, set TEAMS_TENANT_ID to its directory (tenant) id as well. The package each workspace downloads is integrations/teams/manifest.json with that id filled in; node scripts/teams-package.mjs builds the same file by hand.