{
 "about": "Nexus StudioQA integrations, for AI assistants: every .env key, its valid format and check, and error → cause → fix. Follow assistant.rules and assistant.flow.",
 "page": "https://nexusstudioqa.com/docs/integrations",
 "assistant": {
  "secretRule": "Never paste a token, key, password or webhook URL into a chat. Type it only in Studio → Settings → Integrations, where it is saved in your workspace's .env file and shown as dots.",
  "rules": [
   "Never ask the user to paste a token, PAT, API key, password or webhook URL into the chat, and never ask for the contents of .env. If they already pasted one, tell them to revoke it and create a new one.",
   "Credentials are typed only in the Studio: Settings → Integrations (they are saved in the workspace .env, shown as dots, and never leave the machine except to the service itself).",
   "Ask only for non-secret facts: the site address, the project key or name, the organization name, and the exact text of the error line. The Studio already blanks secrets in its error lines.",
   "The Studio's own checks are the source of truth: Check connection, Send test message, Create test ticket. Ask the user to read you the result line; never say \"it works\" without it.",
   "One step at a time. Wait for the result of each step before the next one.",
   "Match the error to the table of that integration (symptom → cause → fix). If it matches none, ask for the exact error line and send the user to support@nexusstudioqa.com."
  ],
  "flow": [
   "Ask which service the user is connecting (Jira, Azure Boards, GitHub Issues, Slack, Teams or Telegram) and what the Studio shows now.",
   "Open that integration's guide and give the \"Get the credentials\" steps, one at a time. The user creates the credential on the service's own site.",
   "Tell the user to paste the credential in Studio → Settings → Integrations and press the check button. Not here.",
   "Ask for the result line the Studio shows (green or red). If it is an error, find it in the table and give the fix.",
   "When the check passes, turn the service on (its *_ENABLED switch) and, for ticket trackers, press Create test ticket under Settings → Integrations → Tickets.",
   "Ask the user to open the test ticket or message in the service and confirm it is there. Then remind them to delete the test ticket and, if a credential was ever shared in a chat, to revoke it."
  ]
 },
 "integrations": [
  {
   "id": "jira",
   "name": "Jira Cloud",
   "guide": "https://nexusstudioqa.com/docs/jira-setup",
   "does": "Files one Bug per failing test, comments on it when the test fails again, and moves it to Done when the test passes clean.",
   "needs": [
    "A Jira Cloud site, for example https://your-team.atlassian.net (Jira Cloud only; the address must be https).",
    "The email of your Atlassian account and an API token created with that same account.",
    "A project key, for example QA, whose project has an issue type named Bug.",
    "In that project, permission for that account to browse, create issues, add comments, create attachments and transition issues."
   ],
   "getCredentials": [
    "Open https://id.atlassian.com/manage-profile/security/api-tokens and choose Create API token.",
    "Name it (for example \"Nexus StudioQA\"), pick an expiry, create it and copy the token now. Atlassian shows it once.",
    "Keep it in your clipboard. Do not paste it anywhere except the Studio (next step)."
   ],
   "connectInStudio": [
    "In the Studio, open Settings → Integrations → Connect Jira.",
    "Paste any link from your Jira (the home page, a board or an issue) and press Check connection. The Studio keeps the site address and the project key.",
    "When it asks, enter your Atlassian email and the token, and press Save & check.",
    "Pick the project in \"Bugs go to\", then turn on JIRA_ENABLED."
   ],
   "verify": [
    "Check connection shows \"Signed in as <your name>\" and \"<KEY> takes Bug tickets\". The check only reads; it never opens a ticket.",
    "Open Settings → Integrations → Tickets and press Create test ticket. It files one ticket labeled nexus-test and is the only click there that calls Jira.",
    "Open that ticket in Jira and confirm it has the labels auto-generated, nexus-studioqa-automation and nexus-test. Delete it when you are done."
   ],
   "keys": [
    {
     "key": "JIRA_ENABLED",
     "title": "Create Jira tickets for failures",
     "default": "false",
     "secret": false,
     "validFormat": "true or false",
     "howToCheck": "Turn the integration on, then run Create test ticket."
    },
    {
     "key": "JIRA_BASE_URL",
     "title": "Jira site address",
     "default": "",
     "secret": false,
     "validFormat": "https://<site>.atlassian.net",
     "howToCheck": "Check connection shows the site; a pasted link fills it."
    },
    {
     "key": "JIRA_EMAIL",
     "title": "Jira sign-in email",
     "default": "",
     "secret": false,
     "validFormat": "The email of the Atlassian account that owns the token",
     "howToCheck": "Check connection shows \"Signed in as …\" with this email."
    },
    {
     "key": "JIRA_API_TOKEN",
     "title": "Jira access token",
     "default": "",
     "secret": true,
     "validFormat": "One line, no quotes, no spaces",
     "howToCheck": "Check connection: HTTP 401 means the email/token pair is wrong."
    },
    {
     "key": "JIRA_PROJECT_KEY",
     "title": "Jira project for Bug tickets",
     "default": "QA",
     "secret": false,
     "validFormat": "The project key, usually capital letters, for example QA",
     "howToCheck": "The project dropdown lists it; \"takes Bug tickets\" confirms the type."
    },
    {
     "key": "JIRA_DONE_TRANSITION",
     "title": "Jira status when test passes",
     "default": "Done",
     "secret": false,
     "validFormat": "The exact name of a workflow transition, matched in any case",
     "howToCheck": "A clean pass moves the ticket; if the workflow has no such transition it only gets a comment."
    }
   ],
   "errors": [
    {
     "symptom": "\"That is not a link\" or \"A Jira link starts with https://\"",
     "cause": "The pasted text is not a full web address, or it starts with http://.",
     "fix": "Copy the address bar while you are on your Jira site. It must start with https://."
    },
    {
     "symptom": "HTTP 401",
     "cause": "The email or the token is wrong, the token expired or was revoked, or the email is not the account that created the token.",
     "fix": "Create a new token at id.atlassian.com with the account whose email you saved, then save both again in Settings."
    },
    {
     "symptom": "HTTP 403",
     "cause": "The sign-in works, but Jira says that account may not do it: usually a missing Create issues, Add comments or Create attachments permission in the project.",
     "fix": "Ask the project admin for those permissions, or choose another project. Nexus StudioQA cannot grant them."
    },
    {
     "symptom": "HTTP 404",
     "cause": "The site address or the project key does not exist, or that account cannot see the project (Jira answers 404 for projects it hides).",
     "fix": "Paste any link from the right site and choose the project from the list."
    },
    {
     "symptom": "\"That address answered, but not with a Jira account\"",
     "cause": "The address is not a Jira Cloud site (for example a Server or Data Center address, or another web page).",
     "fix": "Use the https://<team>.atlassian.net address of your Jira Cloud site."
    },
    {
     "symptom": "\"<KEY> has no issue type named Bug\"",
     "cause": "The project has no issue type called Bug, so no ticket can be filed.",
     "fix": "In Jira, open Project settings → Issue types and add Bug, or choose another project."
    },
    {
     "symptom": "\"could not reach Jira (ENOTFOUND)\" or \"did not answer within 20 s\"",
     "cause": "This PC cannot reach the site: a typo in the address, a VPN or proxy, or no network.",
     "fix": "Fix the address, then open the site in a browser on the same PC. Retry the check."
    },
    {
     "symptom": "Everything checks out, but no ticket appears",
     "cause": "JIRA_ENABLED is false; or the verdict was FLAKY or an environment verdict; or it was a sandbox run; or an open Bug already exists for that test (a repeat failure comments instead); or a Bug with the same title was filed in the last 24 hours.",
     "fix": "Turn on JIRA_ENABLED, read \"One issue per test\" on the integrations page, and use Create test ticket to prove the connection."
    },
    {
     "symptom": "A passing test does not close its ticket",
     "cause": "The workflow has no transition named like JIRA_DONE_TRANSITION, so the ticket only gets the comment.",
     "fix": "Set JIRA_DONE_TRANSITION to the exact name of the transition button in your workflow."
    }
   ]
  },
  {
   "id": "azure",
   "name": "Azure Boards",
   "guide": "https://nexusstudioqa.com/docs/azure-boards-setup",
   "does": "Files one work item per failing test, comments on it when the test fails again, and sets it to a done state when the test passes clean. The same token also publishes test results and queues pipelines.",
   "needs": [
    "An Azure DevOps Services organization: https://dev.azure.com/<organization> or https://<organization>.visualstudio.com (Azure DevOps Server on your own machines is not supported).",
    "The name of the project that will receive the work items.",
    "A personal access token (PAT) with Work Items → Read & write, and Build → Read & execute if you also use Run in CI.",
    "To know your project's process, because it decides the work item type: Basic has Issue, Epic and Task (no Bug); Agile, Scrum and CMMI have Bug."
   ],
   "getCredentials": [
    "Open dev.azure.com, then User settings → Personal access tokens → New Token.",
    "Pick your organization, set an expiry, and under Scopes choose Custom defined.",
    "Tick Work Items → Read & write (add Build → Read & execute for Run in CI), create the token and copy it now. It is shown once.",
    "Keep it in your clipboard. Do not paste it anywhere except the Studio (next step)."
   ],
   "connectInStudio": [
    "In the Studio, open Settings → Integrations → Connect Azure DevOps.",
    "Paste any link from Azure DevOps (a board, a work item or the project page) and press Check connection. The Studio keeps the organization and the project.",
    "When it asks, enter the PAT and press Save & check. Pick the project in \"Work items go to\".",
    "If the check says the project has no work item type named Bug, set AZURE_BOARDS_WORK_ITEM_TYPE to one of the types it lists (in a Basic project, Issue), and AZURE_BOARDS_DONE_STATE to a state that process has (Basic: Done).",
    "Turn on AZURE_BOARDS_ENABLED."
   ],
   "verify": [
    "Check connection shows \"The token sees N projects\" and \"<project> takes <type> work items\". The check only reads; it never files a work item.",
    "Open Settings → Integrations → Tickets and press Create test ticket. It files one work item tagged nexus-test with a screenshot attached.",
    "Open it in Azure Boards, confirm the tag and the attachment, and delete it when you are done."
   ],
   "keys": [
    {
     "key": "AZURE_BOARDS_ENABLED",
     "title": "Create Azure work items for failures",
     "default": "false",
     "secret": false,
     "validFormat": "true or false",
     "howToCheck": "Turn on after Check connection passes, then run Create test ticket."
    },
    {
     "key": "AZURE_DEVOPS_ORG_URL",
     "title": "Azure DevOps organization address",
     "default": "",
     "secret": false,
     "validFormat": "https://dev.azure.com/<organization> or https://<organization>.visualstudio.com",
     "howToCheck": "Check connection shows the organization; a pasted link fills it."
    },
    {
     "key": "AZURE_DEVOPS_PROJECT",
     "title": "Azure DevOps project name",
     "default": "",
     "secret": false,
     "validFormat": "The project name, exactly as Azure DevOps shows it",
     "howToCheck": "Check connection lists the projects the token sees."
    },
    {
     "key": "AZURE_DEVOPS_PAT",
     "title": "Azure DevOps access token",
     "default": "",
     "secret": true,
     "validFormat": "One line, no quotes, no spaces",
     "howToCheck": "Check connection: \"refused the token\" means it is wrong, expired or from another organization."
    },
    {
     "key": "AZURE_BOARDS_WORK_ITEM_TYPE",
     "title": "Azure ticket type for failures",
     "default": "Bug",
     "secret": false,
     "validFormat": "A type the project's process has: Bug (Agile, Scrum, CMMI) or Issue (Basic)",
     "howToCheck": "Check connection says \"<project> takes <type> work items\" or lists the types the project has."
    },
    {
     "key": "AZURE_BOARDS_DONE_STATE",
     "title": "Azure state when test passes",
     "default": "Resolved",
     "secret": false,
     "validFormat": "A state of that work item type: Resolved (Agile bug), Done (Basic issue)",
     "howToCheck": "A clean pass moves the item; if the process refuses the state it only gets a comment."
    },
    {
     "key": "AZURE_PIPELINE_ID",
     "title": "Azure pipeline to run in CI",
     "default": "",
     "secret": false,
     "validFormat": "The numeric id of an Azure pipeline (only for Run in CI)",
     "howToCheck": "nexus ci-remote --provider=azure queues that pipeline; needs Build → Read & execute."
    }
   ],
   "errors": [
    {
     "symptom": "\"Azure DevOps refused the token\" (HTTP 203 or 401)",
     "cause": "The PAT is wrong, expired, revoked, copied incompletely, or was created in a different organization.",
     "fix": "Create a new PAT in the same organization as AZURE_DEVOPS_ORG_URL with Work Items → Read & write, and save it again."
    },
    {
     "symptom": "HTTP 403",
     "cause": "The PAT is valid but lacks a scope, or your user lacks permission in that project.",
     "fix": "Edit the PAT's scopes (Work Items → Read & write; Build → Read & execute for Run in CI), or ask the project admin for access."
    },
    {
     "symptom": "HTTP 404",
     "cause": "The organization or the project name does not exist, or the project was renamed.",
     "fix": "Paste a link from the right project and choose it from the list."
    },
    {
     "symptom": "VS402323 \"Work item type Bug does not exist\"",
     "cause": "The project's process has no work item type with that name. A Basic project has Issue, Epic and Task, not Bug.",
     "fix": "Set AZURE_BOARDS_WORK_ITEM_TYPE to a type the check lists (Basic: Issue) and AZURE_BOARDS_DONE_STATE to one of its states (Basic: Done), then Check connection again."
    },
    {
     "symptom": "\"<project> has no work item type named …\"",
     "cause": "The same cause as VS402323, caught by Check connection before anything is filed.",
     "fix": "Set AZURE_BOARDS_WORK_ITEM_TYPE to one of the types listed in that message, or choose another project."
    },
    {
     "symptom": "\"That is not an Azure DevOps link\"",
     "cause": "The address is not on dev.azure.com/<organization> or <organization>.visualstudio.com, or it starts with http://.",
     "fix": "Copy the address bar from Azure DevOps Services. Azure DevOps Server is not supported."
    },
    {
     "symptom": "\"could not reach Azure DevOps (…)\" or \"did not answer within 20 s\"",
     "cause": "This PC cannot reach Azure DevOps: a VPN or proxy, or no network.",
     "fix": "Open dev.azure.com in a browser on the same PC, then retry the check."
    },
    {
     "symptom": "A passing test does not set the done state",
     "cause": "The process refuses AZURE_BOARDS_DONE_STATE for that type, so the item only gets the comment.",
     "fix": "Set AZURE_BOARDS_DONE_STATE to a state of that type (Basic: Done; Agile bug: Resolved)."
    },
    {
     "symptom": "Everything checks out, but no work item appears",
     "cause": "AZURE_BOARDS_ENABLED is false; or the verdict was FLAKY or an environment verdict; or it was a sandbox run; or the test already has an open work item (a repeat failure comments instead).",
     "fix": "Turn on AZURE_BOARDS_ENABLED and use Create test ticket to prove the connection."
    }
   ]
  },
  {
   "id": "slack",
   "name": "Slack",
   "guide": "https://nexusstudioqa.com/docs/slack-setup",
   "does": "Posts the run summary to a channel, and with NEXUS_SLACK_NOTIFY=true one message per failing, flaky, chaos or visual-regression test. A message about a failure links its Jira ticket when there is one.",
   "needs": [
    "A Slack workspace where you can add an app.",
    "One Incoming Webhook URL for the channel that should get the messages."
   ],
   "getCredentials": [
    "In Slack, create an app with an Incoming Webhook (https://api.slack.com/messaging/webhooks) and pick the channel.",
    "Copy the webhook URL. It starts with https://hooks.slack.com/services/. The URL is itself the secret.",
    "Keep it in your clipboard. Do not paste it anywhere except the Studio (next step)."
   ],
   "connectInStudio": [
    "In the Studio, open Settings → Integrations → Slack.",
    "Paste the webhook URL and press Save & send test. A test message goes to the channel.",
    "Turn on SLACK_ENABLED. For one message per failing test, also turn on NEXUS_SLACK_NOTIFY."
   ],
   "verify": [
    "Send test message answers \"Sent.\" and the message appears in the channel.",
    "Run any test. The run summary arrives in the channel."
   ],
   "keys": [
    {
     "key": "SLACK_ENABLED",
     "title": "Send alerts to Slack",
     "default": "false",
     "secret": false,
     "validFormat": "true or false",
     "howToCheck": "Turn on after the test message arrives."
    },
    {
     "key": "SLACK_WEBHOOK_URL",
     "title": "Slack channel for alerts",
     "default": "",
     "secret": true,
     "validFormat": "https://hooks.slack.com/services/… (nothing else is accepted)",
     "howToCheck": "Send test message posts to the channel."
    },
    {
     "key": "NEXUS_SLACK_NOTIFY",
     "title": "Slack alert per failure",
     "default": "false",
     "secret": false,
     "validFormat": "true or false",
     "howToCheck": "One message per failing test arrives, not only the run summary."
    }
   ],
   "errors": [
    {
     "symptom": "\"No webhook\"",
     "cause": "SLACK_WEBHOOK_URL is empty.",
     "fix": "Paste the webhook URL in Settings → Integrations and save."
    },
    {
     "symptom": "\"SLACK_WEBHOOK_URL is not a Slack Incoming Webhook\"",
     "cause": "The value does not start with https://hooks.slack.com/services/.",
     "fix": "Copy the webhook URL again from your Slack app's Incoming Webhooks page."
    },
    {
     "symptom": "HTTP 404 \"no_service\" or HTTP 403 \"invalid_token\"",
     "cause": "The webhook was revoked or deleted, or the app was removed from the workspace.",
     "fix": "Create a new Incoming Webhook and save the new URL."
    },
    {
     "symptom": "HTTP 404 \"channel_not_found\" or HTTP 410 \"channel_is_archived\"",
     "cause": "The channel the webhook posts to was deleted or archived.",
     "fix": "Create a new webhook for an active channel."
    },
    {
     "symptom": "\"could not reach Slack (ENOTFOUND)\" or \"did not answer within 20 s\"",
     "cause": "This PC cannot reach Slack: a VPN or proxy, or no network.",
     "fix": "Check the network from the same PC and retry."
    },
    {
     "symptom": "The test works but failures do not post",
     "cause": "SLACK_ENABLED is false, or only the run summary is on: per-test messages need NEXUS_SLACK_NOTIFY=true.",
     "fix": "Turn on both switches."
    }
   ]
  },
  {
   "id": "teams",
   "name": "Microsoft Teams",
   "guide": "https://nexusstudioqa.com/docs/teams-setup",
   "does": "Posts the run summary to a Teams channel, and with NEXUS_TEAMS_NOTIFY=true one message per failing test.",
   "needs": [
    "A Teams channel where you can add a workflow.",
    "One Workflows webhook URL for that channel."
   ],
   "getCredentials": [
    "In Teams, open the channel's ··· menu → Workflows and add \"Post to a channel when a webhook request is received\".",
    "Copy the webhook URL it gives you. It ends in logic.azure.com (older connectors: webhook.office.com). The URL is itself the secret.",
    "Keep it in your clipboard. Do not paste it anywhere except the Studio (next step)."
   ],
   "connectInStudio": [
    "In the Studio, open Settings → Integrations → Microsoft Teams.",
    "Paste the webhook URL and press Save & send test. A test message goes to the channel.",
    "Turn on TEAMS_ENABLED. For one message per failing test, also turn on NEXUS_TEAMS_NOTIFY."
   ],
   "verify": [
    "Send test message answers \"Sent.\" and the message appears in the channel.",
    "Run any test. The run summary arrives in the channel."
   ],
   "keys": [
    {
     "key": "TEAMS_ENABLED",
     "title": "Send alerts to Microsoft Teams",
     "default": "false",
     "secret": false,
     "validFormat": "true or false",
     "howToCheck": "Turn on after the test message arrives."
    },
    {
     "key": "TEAMS_WEBHOOK_URL",
     "title": "Teams channel for alerts",
     "default": "",
     "secret": true,
     "validFormat": "An https://…logic.azure.com or …webhook.office.com URL",
     "howToCheck": "Send test message posts to the channel."
    },
    {
     "key": "NEXUS_TEAMS_NOTIFY",
     "title": "Teams alert per failure",
     "default": "false",
     "secret": false,
     "validFormat": "true or false",
     "howToCheck": "One message per failing test arrives, not only the run summary."
    }
   ],
   "errors": [
    {
     "symptom": "\"No webhook\"",
     "cause": "TEAMS_WEBHOOK_URL is empty.",
     "fix": "Paste the webhook URL in Settings → Integrations and save."
    },
    {
     "symptom": "\"TEAMS_WEBHOOK_URL is not a Teams webhook\"",
     "cause": "The value is not an https URL on logic.azure.com or webhook.office.com.",
     "fix": "Copy the URL again from the workflow's \"Post to a channel when a webhook request is received\" trigger."
    },
    {
     "symptom": "An HTTP 4xx or 5xx answer from Teams",
     "cause": "The workflow was turned off or deleted, or its owner left or lost the license, so it no longer runs.",
     "fix": "Open the workflow in Teams (Workflows → manage), turn it on or create a new one, and save the new URL."
    },
    {
     "symptom": "\"could not reach Teams (ENOTFOUND)\" or \"did not answer within 20 s\"",
     "cause": "This PC cannot reach Microsoft: a VPN or proxy, or no network.",
     "fix": "Check the network from the same PC and retry."
    },
    {
     "symptom": "The test works but failures do not post",
     "cause": "TEAMS_ENABLED is false, or only the run summary is on: per-test messages need NEXUS_TEAMS_NOTIFY=true.",
     "fix": "Turn on both switches."
    }
   ]
  },
  {
   "id": "telegram",
   "name": "Telegram",
   "guide": "https://nexusstudioqa.com/docs/telegram-setup",
   "does": "Sends alerts on failure (one per test with NEXUS_TELEGRAM_NOTIFY=true) and the reports and files you choose to share, through a bot of your own. There is no shared bot.",
   "needs": [
    "A Telegram account.",
    "A bot of your own, created once with @BotFather, and its token.",
    "A phone or Telegram app to scan the pairing QR.",
    "Before you switch it on: Telegram can receive files such as reports and PDFs, and they go to Telegram's servers. In a regulated environment, ask your compliance team first."
   ],
   "getCredentials": [
    "In Telegram, open https://t.me/BotFather and send /newbot. Give the bot a name and a username.",
    "BotFather answers with the bot token (for example 123456:ABC…). Copy it.",
    "Keep it in your clipboard. Do not paste it anywhere except the Studio (next step)."
   ],
   "connectInStudio": [
    "In the Studio, open Settings → Integrations → Connect Telegram.",
    "Paste the bot token and save. The pairing QR appears.",
    "Scan the QR with your phone and tap Start in Telegram. Within seconds the Studio shows \"alerts go to chat …\" and the bot says \"Connected to Nexus StudioQA.\"",
    "Turn on TELEGRAM_ENABLED. For one alert per failing test, also turn on NEXUS_TELEGRAM_NOTIFY."
   ],
   "verify": [
    "After the scan, the bot sends \"Connected to Nexus StudioQA. Failed tests will be reported here.\" to your chat.",
    "The Studio shows \"alerts go to chat\" with the chat masked."
   ],
   "keys": [
    {
     "key": "TELEGRAM_ENABLED",
     "title": "Send alerts to Telegram",
     "default": "false",
     "secret": false,
     "validFormat": "true or false",
     "howToCheck": "The pairing QR needs it on."
    },
    {
     "key": "TELEGRAM_TOKEN",
     "title": "Telegram bot access code",
     "default": "",
     "secret": true,
     "validFormat": "The bot token from BotFather, like 123456:ABC…, one line",
     "howToCheck": "The QR appears only if Telegram accepts it."
    },
    {
     "key": "TELEGRAM_CHAT_ID",
     "title": "Telegram chat for alerts",
     "default": "",
     "secret": false,
     "validFormat": "Filled by the QR pairing; do not type it",
     "howToCheck": "The Studio shows \"alerts go to chat …\"."
    },
    {
     "key": "NEXUS_TELEGRAM_NOTIFY",
     "title": "Telegram alert per failure",
     "default": "false",
     "secret": false,
     "validFormat": "true or false",
     "howToCheck": "One alert per failing test arrives."
    }
   ],
   "errors": [
    {
     "symptom": "\"Telegram is off\"",
     "cause": "TELEGRAM_ENABLED is false, and pairing needs it on.",
     "fix": "Turn on TELEGRAM_ENABLED and press Connect Telegram again."
    },
    {
     "symptom": "\"No bot token\"",
     "cause": "TELEGRAM_TOKEN is empty.",
     "fix": "Paste the token from BotFather in Settings → Integrations and save."
    },
    {
     "symptom": "\"Telegram: Unauthorized\" (or \"Not Found\")",
     "cause": "The bot token is wrong, was revoked in BotFather, or was cut when copied.",
     "fix": "Send /token to BotFather to get the token again (or create a new bot), and save it."
    },
    {
     "symptom": "\"The QR expired before it was scanned\"",
     "cause": "The QR is valid for a few minutes only.",
     "fix": "Press Connect Telegram to make a new one and scan it right away."
    },
    {
     "symptom": "The QR was scanned but the Studio still waits",
     "cause": "The scan opened the chat but Start was not tapped, or the Studio window was closed.",
     "fix": "Tap Start in the bot's chat. If it still waits, make a new QR."
    },
    {
     "symptom": "\"could not reach Telegram (ENOTFOUND)\" or \"did not answer within 20 s\"",
     "cause": "This PC cannot reach api.telegram.org: a VPN, firewall or proxy, or no network.",
     "fix": "Check the network from the same PC and retry."
    },
    {
     "symptom": "No alert arrives after a failure",
     "cause": "TELEGRAM_ENABLED is false, no chat is paired, or per-test alerts are off (NEXUS_TELEGRAM_NOTIFY).",
     "fix": "Pair a chat, and turn on both switches."
    }
   ]
  },
  {
   "id": "github",
   "name": "GitHub Issues",
   "guide": "https://nexusstudioqa.com/docs/github-issues-setup",
   "does": "Opens one GitHub issue per failing test, comments on it when the test fails again, and closes it when the test passes clean. GitHub takes no file uploads, so the issue names the evidence folder instead of attaching the screenshot.",
   "needs": [
    "A GitHub account that can open issues in the repository (a collaborator, or the owner).",
    "A repository with Issues switched on (repository Settings → Features → Issues).",
    "A fine-grained personal access token with Issues → Read and write on that repository, or a classic token with the repo scope."
   ],
   "getCredentials": [
    "Open https://github.com/settings/personal-access-tokens/new (a fine-grained token).",
    "Name it, set an expiry, and under Repository access choose Only select repositories, then pick the repository that will receive the issues.",
    "Under Permissions → Repository permissions set Issues to Read and write. Nothing else is needed.",
    "Generate the token and copy it now. GitHub shows it once. Do not paste it anywhere except the Studio (next step)."
   ],
   "connectInStudio": [
    "In the Studio, open Settings → Integrations → Connect GitHub Issues.",
    "When it asks, enter the token and press Save & check. The Studio shows who the token belongs to and how many repositories it reaches.",
    "Pick the repository in \"Issues go to\". The list only offers repositories the token can reach and that have Issues on.",
    "Turn on GITHUB_ISSUES_ENABLED."
   ],
   "verify": [
    "Check connection shows \"signed in as <you>\" and \"<owner/repo> takes issues\". The check only reads; it never opens an issue.",
    "Open Settings → Integrations → Tickets and press Create test ticket on the GitHub destination. It opens one issue labelled nexus-test.",
    "Open it on GitHub, confirm the label, and close or delete it when you are done."
   ],
   "keys": [
    {
     "key": "GITHUB_ISSUES_ENABLED",
     "title": "Create GitHub issues for failures",
     "default": "false",
     "secret": false,
     "validFormat": "true or false",
     "howToCheck": "Turn on after Check connection passes, then run Create test ticket."
    },
    {
     "key": "GITHUB_ISSUES_TOKEN",
     "title": "GitHub access token",
     "default": "",
     "secret": true,
     "validFormat": "One line, no quotes, no spaces",
     "howToCheck": "Check connection: \"refused the token\" means it is wrong, expired or revoked."
    },
    {
     "key": "GITHUB_ISSUES_REPO",
     "title": "GitHub repository for issues",
     "default": "",
     "secret": false,
     "validFormat": "owner/repo, like acme/web",
     "howToCheck": "Pick it from the list; the Studio only saves a repository the token reaches and that has Issues on."
    }
   ],
   "errors": [
    {
     "symptom": "\"GitHub refused the token (401)\"",
     "cause": "The token is wrong, expired, revoked or copied incompletely.",
     "fix": "Create a new token with Issues → Read and write and save it again."
    },
    {
     "symptom": "HTTP 403",
     "cause": "The token lacks the Issues permission, the repository was not selected for it, or the rate limit is spent.",
     "fix": "Edit the token: set Issues to Read and write and select the repository. If it is the rate limit, wait a few minutes."
    },
    {
     "symptom": "HTTP 404",
     "cause": "The repository does not exist, was renamed, or the token cannot see it (private repositories must be selected on a fine-grained token).",
     "fix": "Pick the repository from the list, or add it to the token's repository access."
    },
    {
     "symptom": "HTTP 422",
     "cause": "GitHub rejected a field of the issue, most often an assignee who is not a collaborator, or a title or label GitHub refuses.",
     "fix": "Clear the assignee in Settings → Integrations → Tickets, or add that person as a collaborator."
    },
    {
     "symptom": "\"<repo> has Issues switched off\"",
     "cause": "The repository has the Issues feature disabled.",
     "fix": "Turn on Settings → Features → Issues in the repository, or choose another one."
    },
    {
     "symptom": "\"could not reach GitHub (…)\" or \"did not answer in time\"",
     "cause": "This PC cannot reach api.github.com: a VPN or proxy, or no network.",
     "fix": "Open github.com in a browser on the same PC, then retry the check."
    },
    {
     "symptom": "Everything checks out, but no issue appears",
     "cause": "GITHUB_ISSUES_ENABLED is false; or the verdict was FLAKY or an environment verdict; or it was a sandbox run; or the test already has an open issue (a repeat failure comments instead).",
     "fix": "Turn on GITHUB_ISSUES_ENABLED and use Create test ticket to prove the connection."
    }
   ]
  }
 ]
}
