Troubleshooting connections
Merge Pilot depends on its connections in both directions: it calls GitLab, GitHub and Jira with the connection's credentials, and they call Merge Pilot back with webhooks. This page lists what goes wrong on either side, why, and what to do. How connections work is described in Connections.
Where to look first
- Test connection on the connection's row: checks that Merge Pilot can reach the provider with the saved credentials (see Test connection).
- The provider's own webhook delivery log: GitLab's project webhook, the GitHub App's deliveries, or Jira's webhook. Merge Pilot answers each delivery with a short JSON body that says what it did, for example
{"status": "accepted"}or{"status": "ignored", "reason": "invalid_signature"}. The reasons are listed below. - The audit log: each merge request event or tracker event Merge Pilot accepted is written as
webhook_accepted; an accepted VCS event that could not be queued aswebhook_job_failed(see Audit log → Webhooks). Nowebhook_acceptedentry for an event means it never arrived or was ignored. - The webhook log (API only):
GET /api/v1/webhook-logslists the deliveries Merge Pilot recorded for the company, newest first, withsource(vcsortracker),event_type,repo_id,mr_number,status_codeanderror. Deliveries refused for a wrong secret are recorded asauth_failed(invalid webhook signature), at most one a minute per connection. Platform admins, company admins and auditors can read it. Deliveries are kept 5 days. - The connection's row: a delivery refused for a wrong secret shows as Last refused webhook: wrong secret, <date and time>, and is in the audit log as
webhook_refused(see Refused webhooks).
Test connection fails
The test answers one sentence: what failed, and what the provider (GitLab, GitHub or Jira) or the network answered.
| Message | What failed | Usual causes and what to do |
|---|---|---|
| Merge Pilot could not reach … at <host>: the host name does not resolve. | Reaching the server | The URL is wrong: correct it (enter the token again when the host changes) |
| Merge Pilot could not reach … at <host>: the connection was refused (nothing listens at that address and port). / …: it did not answer in time. | Reaching the server | The server is down, or a firewall or proxy is in the way. Check the URL's port, and that Merge Pilot's network can reach the server |
| Merge Pilot could not reach … at <host>: its TLS certificate is not trusted (…). | Reaching the server securely | Use a certificate both sides trust, or Skip TLS verification for a self-hosted GitLab |
| GitLab refused the connection's credentials (it answered 401 Unauthorized: …): enter a valid token or key. | Signing in | The token was revoked or expired: create a new one for the bot user and save it in Token |
| Jira refused the connection's credentials (it answered 401 Unauthorized: …): enter a valid token or key. | Signing in | The token or password is wrong or expired; for Jira Server or Data Center with a personal access token, choose Personal access token (see Jira) |
| GitHub refused the connection's credentials (it answered 401 Unauthorized: …): enter a valid token or key. | Signing in as the GitHub App with its private key | The App was deleted on GitHub, or the App ID and private key under Use an existing GitHub App do not belong together. Create the App again from the connection (remove it first), or enter a new private key |
| … accepted the credentials but refused the request for lack of permission (it answered 403 Forbidden: …): give the account the rights the connection needs. | A permission | The GitLab token lacks the api scope, or the Jira account may not use the API: give it the rights (see the provider's page under Connections) |
| … did not find what Merge Pilot asked for (it answered 404 Not Found: …): check the connection's URL. | The address | The URL points to something that is not the provider's server, or misses a path the server needs: correct URL |
| … had a server error (it answered 5xx …): try again later. | The provider itself | Wait, then test again |
| … is limiting Merge Pilot's requests (rate limit): test the connection again in a few minutes. | The provider's rate limit | Wait, then test again |
| GitHub Enterprise Server 3.12 or newer is required (this server runs …). | The server's version | Upgrade GitHub Enterprise Server to 3.12 or newer |
| The GitHub App is not installed on any organization or account yet. | Where the App is installed | Select Install on GitHub on the connection and install it on the organizations whose repositories Merge Pilot should gate (see Install the App) |
| The GitHub App of this connection has not been created yet: use Create GitHub App in the connection settings. | The App | Create the App (see Create the GitHub App) |
The test does not check the token's rights on each repository. Those are reported by the change management setup, step by step (see Change management setup fails).
Test passes but the row stays red
Test connection says the connection works, yet the row still shows a problem in red. The test passes when the provider answers; the row shows what Merge Pilot found with the credentials its work uses. They differ in these cases:
| Row says | Why the test passes | What to do |
|---|---|---|
| The VCS refuses Merge Pilot's credentials (GitHub) | The test signs in as the GitHub App, which works, but GitHub refuses an installation's token. The installation shows Token refused under the App | Open the installation's settings on GitHub: check that the App is still installed and not blocked there. Refresh the App's installations, then test again. The line goes once every installation Merge Pilot can use works |
| The API rate limit is used up: background work waits for its reset | The test needs only a few calls; the limit stays until the time the VCS gave for its reset | Wait: the line goes at the first check after the reset |
| The GitHub App lacks permissions Merge Pilot needs | The test reads the permissions as last refreshed from GitHub | Have the App's owner add the permissions and each installation accept them (see GitHub App problems), then refresh the App |
A suspended installation, or one removed on GitHub, does not keep the row red: it shows Suspended or Removed on GitHub on its own line under the App (see Connection health → GitHub App installations).
Saving a connection is refused
The connection dialog shows the reason; through the API every such problem answers 400 with it.
| Message | Why | What to do |
|---|---|---|
| … a GitLab connection needs a bot user (the account Merge Pilot approves merge requests with) | Bot username is empty | Enter the GitLab user name of the account that owns the token (see GitLab) |
| … enter a webhook secret: Merge Pilot accepts a webhook only when it carries the connection's secret | No webhook secret was saved for a GitLab or Jira connection | Enter a long random string (at least 32 characters) |
| enter the token again when changing the connection URL | The URL now points to another host, and the saved token is never sent to a different host | Type the token (or the GitHub App's private key) again with the new URL |
| a GitHub cloud connection uses https://github.com; choose on-premises for GitHub Enterprise Server / github.com is a cloud connection; choose cloud as the deployment type / enter the address of your GitHub Enterprise Server | The deployment type and the address do not go together | Choose Cloud for github.com, On-prem with the server's address for GitHub Enterprise Server |
| the GitHub App private key is not a valid PEM key: … / enter the GitHub App ID together with its private key | The App credentials entered by hand are incomplete | Paste the private key file GitHub generated, with the App's ID |
| A URL refused when saved | Loopback addresses (such as localhost), link-local addresses, cloud metadata addresses and host names that do not resolve are refused | Use the provider's real address. Private network addresses are allowed |
Webhooks do not arrive
When GitLab, GitHub or Jira cannot reach Merge Pilot, its delivery log shows the failure and Merge Pilot shows nothing: merge requests do not appear or do not move, and the audit log has no webhook_accepted entries.
- The Application URL. Every webhook URL starts with the Application URL a platform admin sets under Settings → General. It must be reachable from GitLab, GitHub and Jira (for github.com, from the internet). Compare the URL in the provider's webhook with the connection's Copy webhook URL.
- GitLab: Merge Pilot creates the project webhook itself, when a repository is watched or set up for change management. When it is missing or wrong, open the repository's page and use Sync CM or Re-run CM setup on the CM status card, which writes it again (see Setup status and repair). On the Projects page, Background work says when the webhooks of some repositories could not be updated (… webhook could not be updated: see its page.).
- GitHub: the App's webhook delivers the events of every repository the App is installed on. A repository the installation does not reach sends nothing: add it to the installation's selected repositories on GitHub, then select Refresh on the connection.
- Jira: the webhook is created by hand in Jira (see The Jira webhook).
A lost webhook is not fatal for merge requests Merge Pilot already knows: the periodic re-check reads CI runs, tracker decisions, merges and closes again (see The periodic re-check), and Resync on a merge request does it at once. A merge request Merge Pilot has never seen is picked up at its next event (a push, an edit, a label).
Webhooks arrive but are ignored
What Merge Pilot's answer to a webhook means
| Answer in the provider's delivery log | Why | What to do |
|---|---|---|
403, license expired or invalid | No valid Merge Pilot license: webhooks are refused, and every page shows No license is installed, so new merge requests are not being processed. (or The license is …) | A platform admin activates a license (see License). Then redeliver, or let the periodic re-check catch up |
ignored, invalid_signature | The delivery did not carry the connection's secret (the connection's row shows Last refused webhook: wrong secret, …, and the audit log webhook_refused): GitLab's X-Gitlab-Token, the GitHub App's X-Hub-Signature-256, or Jira's X-Hub-Signature (or ?token= for unsigned Jira deliveries) | Make the secret in the provider and in the connection the same: type it again in the connection's Webhook secret (GitLab, Jira) and in the provider's webhook. For an App registered by hand, the App's webhook secret must be the connection's. See How webhooks are verified and How the webhook is authenticated |
ignored, unknown_connection | The URL names a connection that does not exist, was deleted, or belongs to another company | Use the connection's Copy webhook URL |
ignored, no reason | The connection is inactive (its Active switch is off), or the URL's company is unknown | Turn the connection on, or correct the URL |
ignored, company deactivated | The company is deactivated | A platform admin reactivates it |
ignored, unknown_repository | The repository is not watched or under change management in Merge Pilot | Watch it, or put it under change management (see Repositories) |
ignored, target branch not matched | The merge request's target branch is not one of the project's target branch patterns, or else the company's | Add the branch to the patterns (see Branch patterns) |
ignored, target branch excluded | The target branch is one of the project's excluded branches | Remove it from the project's excluded branches (see Project page → Branches) |
ignored, duplicate_delivery | This delivery was already processed: Merge Pilot processes each delivery once | Nothing. Redelivering an event that was accepted does nothing; to run things again, use Resync on the merge request |
ignored, unsupported event type or unsupported action | An event Merge Pilot does not use | Nothing |
ignored, not an actionable transition or own transition (Jira) | A Jira change that is not a decision, or Merge Pilot's own move | Nothing |
ignored, unknown_work_item (Jira) | The issue is not a change approval Merge Pilot knows | Nothing |
503, … lookup failed, or 500, failed to queue / job_creation_failed | Merge Pilot could not read or queue the event at that moment | Redeliver it from the provider's delivery log: a delivery that ended with a server error is processed when it comes again. For a known merge request, Resync or the periodic re-check also catches up |
429, rate limit exceeded, please try again later | More webhook deliveries from one address within a minute than the installation allows (6,000 a minute by default) | Redeliver the refused deliveries from the provider's log once the minute has passed |
GitHub pushes are not received
A GitHub App created before Merge Pilot asked for push events lacks them. The connection says The App does not receive push events, so changes pushed without a pull request are found only by the head check. Turn on the Push event in the App's settings on GitHub, then select Refresh (see Events the App subscribes to).
GitHub App problems
| What you see | Why | What to do |
|---|---|---|
| GitHub only sends events to an address it can reach from the internet, and … is not one. when creating the App | The Application URL is empty, not a full http(s):// address, or a local address (localhost, a .local name, a name without a dot, a loopback or private network IP) | A platform admin sets an internet-reachable Application URL under Settings → General (see Create the GitHub App) |
| This GitHub App setup expired or was already completed. Start it again. | The registration link is valid for one hour and once | Select Create GitHub App again |
| "…" is not a valid GitHub organization name when creating the App | The organization field holds something GitHub does not allow in an organization name | Enter the organization's login as in its GitHub address (letters, digits and hyphens), or leave it empty to create the App under your own account |
| the GitHub App of this connection has not been created yet: use Create GitHub App first on Refresh | There is no App to read installations of | Create the App first (see Create the GitHub App) |
| Try again. If it fails again, check the App on the connection (Test connection, and its settings on GitHub), or contact your Merge Pilot administrator. | The App setup failed for a reason GitHub did not name | Try again; Test connection on the connection says what fails |
| This connection already has a GitHub App. | A connection holds one App | Remove the current App from the connection first (trash icon), then create a new one |
| Merge Pilot could not read where the App is installed. Use Refresh on the connection. | After installing, the installations could not be read | Select Refresh on the connection |
| GitHub offers only the App's owner when installing | The App is private: it installs only on the account it was created under | Make the App public in its GitHub settings (Advanced), or remove it here and create it under the organization, or with Let other organizations install it |
| An installation marked Suspended | GitHub suspended the installation | An owner of that account unsuspends it on GitHub, then Refresh |
| … belongs to a personal GitHub account, where a collaborator always gets write access: only Write can be chosen when joining a project | The repository belongs to a person, not an organization: GitHub gives its collaborators write access and no other role | Join with Write, or ask the repository's owner on GitHub |
| your organization does not allow adding outside collaborators: ask an owner (GitHub: …) when joining a project | The repository's organization lets only its owners add people from outside it | An owner of the organization adds you on GitHub, or makes you a member of the organization (members join at once) |
| Merge Pilot did not give you this access: it is managed in GitHub (…), so leave it there when leaving a project | Your access comes from a team, the organization, or a repository admin on GitHub, not from joining in Merge Pilot | Leave the team, or ask the repository's admins on GitHub |
| The App lacks permissions Merge Pilot needs. on the connection | The App itself does not have a permission Merge Pilot asks for, or has a lower level (usual for an App registered by hand); the warning lists the features that do not work | The App's owner adds the permissions in the App's settings on GitHub (Permissions and events), each installation accepts them, then Refresh (see Permission warnings) |
| … has not accepted the App's new permissions yet. on the connection | The App has new permissions that this installation's owner has not approved yet; the warning lists the features that do not work | The account's owner opens the warning's link (the installation's settings page on GitHub) and accepts the new permissions. The warning disappears when GitHub reports it; otherwise Refresh |
| the GitHub App needs the "…" … permission (…); grant it in the App's settings and accept it on the installation | The operation needs that App permission, and the App lacks it or the installation has not accepted it | Look at the connection's permission warnings: they say which of the two and link to the installation |
| the GitHub App needs the "Administration" repository permission (read and write); … when joining or leaving a project | The installation has not accepted the App's Administration permission | An organization owner accepts the App's new permissions on the installation (the connection's warning links to it) |
| GitHub refused the ruleset: the Merge Pilot App needs the Administration (write) permission on this repository. Accept the App's new permissions in the organization's GitHub settings. | The organization has not accepted all the permissions the App asks for | An organization owner accepts the App's new permissions on the installation (the connection's warning links to it), then set the repository up again |
| GitHub refused the ruleset: rulesets on private repositories need GitHub Team (or Pro) or Enterprise. … | The repository's plan has no rulesets | Upgrade the plan, or keep the repository watched |
| this repository already has the maximum of 75 rulesets on GitHub when protecting a branch | GitHub allows at most 75 rulesets per repository in total; each branch Merge Pilot protects uses one, so does change management, and rulesets made by others count too | Unprotect a branch you no longer need, or remove an unused ruleset on GitHub |
| GitHub refused the ruleset: rulesets on private repositories need GitHub Team (or Pro) or Enterprise. when protecting a branch | The repository is private and its plan has no rulesets | Upgrade the plan; until then branches of private repositories cannot be protected from Merge Pilot on GitHub |
| Force pushes are still blocked. Force pushes to "…" are still blocked on GitHub by the ruleset "…" after Allow force push | Rulesets add up on GitHub and the strictest rule applies: another ruleset (often the change management ruleset, with Block force pushes on) also targets the branch | Nothing, if force pushes should stay blocked. Otherwise change the named ruleset: for the change management one, turn its Block force pushes step off and set the repository up again |
| … still blocked on GitHub by the branch's classic branch protection. or The branch's classic branch protection on GitHub also blocks force pushes. after Allow force push | The branch also has a classic branch protection rule on GitHub (outside rulesets) that does not allow force pushes | Nothing, if force pushes should stay blocked. Otherwise allow force pushes in that branch protection rule on GitHub |
| Could not read the variables and secrets of environment … above the Variables list | GitHub did not answer for that environment (for example it was deleted on GitHub a moment ago); it is left out, the rest is listed | Reload the tab; if it stays, check the environment on GitHub |
| Could not read the repository's environments … above the Variables list, or on the Environment field | The App may not read the repository's environments (a permission not accepted yet, named in the message), or GitHub did not answer | Accept the App's new permissions on the installation; otherwise try again |
| the ruleset "Merge Pilot protected: …" was changed on GitHub (…); change or remove it there, or Changed on GitHub on the Branches tab | Someone changed the branch's protection ruleset on GitHub (its branches, enforcement, bypass list or rules), so it is no longer what Merge Pilot made; Merge Pilot does not change or delete it | Change it back or remove it on GitHub. Once removed, the branch can be protected again from the Branches tab |
| branch "…" contains a pattern character ( ? [ ] ); give one branch by its exact name*, or "…" is not a branch | On GitHub the Branches tab works on one branch by its exact name; patterns and other refs (tags) are refused | Give the branch's name (refs/heads/<name> also works) |
| GitHub variable names may contain only letters (A-Z), digits (0-9) and underscores (_), … must not start with a digit, … must not start with GITHUB_ or … values are limited to 48 KB | The name or value breaks GitHub's rules for Actions variables and secrets; nothing was sent to GitHub | Rename the variable or shorten the value |
| GitHub refused the variable: … | GitHub refused the new variable for a reason of its own, given in its words | Change what GitHub names and try again |
| branch "…" is not protected by Merge Pilot when unprotecting or changing force pushes | The branch is protected on GitHub by something else (for example the change management ruleset), or not at all | Change that protection on GitHub; Merge Pilot changes only the rulesets it created for the Branches tab |
| the GitHub App's installation does not reach the repository: … (step Event delivery) | The App is not installed on the repository's account, or the installation does not include it | Add the repository to the App's installation on GitHub, then Refresh and try again |
Operations on a repository are refused
Merge Pilot does what people ask it to do on the VCS (variables, branch protection, tokens, joining, change management) with the connection's own account, when the connection's rule for the operation lets them (see Permissions). Company admins are never refused for these reasons. On the project page, Not available to you here shows the same reasons before anyone tries.
| Message | Why | What to do |
|---|---|---|
| this connection does not let people <operation> through Merge Pilot (for example … change repository variables …) | The connection's rule for the operation is off | A company admin turns the operation on in the connection's settings (Permissions), or does it for you |
| your Merge Pilot role cannot <operation> through this connection | The rule is on, but does not name your Merge Pilot role (User or Policy manager) | A company admin adds your role to the rule |
| this needs at least <role> on this repository in <GitLab or GitHub> (you have <role>) | Your linked account's role on the repository is below the rule's minimum | Ask for that role on the repository on the VCS, or ask a company admin to lower the rule's minimum |
| you have no access to this repository in <GitLab or GitHub>: this needs at least <role> on it | Your linked account cannot see the repository. GitLab's Minimal access counts as none; on a public GitHub repository, reading it without being a collaborator counts as none | Join the repository (if the connection allows it), or ask for access on the VCS |
| this needs at least <role> in <GitLab or GitHub> on one of the company's repositories in this group (GitHub: organization) | Group or organization variables: none of your company's repositories in that group gives you the rule's minimum | Get the role on one of those repositories |
Link your <GitLab or GitHub> account in My profile to use this. (400, code link_required) | Your role on the repository is read through your linked account, and there is none | Link your account in My profile |
could not verify your <GitLab or GitHub> access (502) | Merge Pilot could not read your role on the repository from the VCS just now | Try again; if it stays, check the connection (Test connection) |
this connection is turned off: ask a company admin (409) | The connection's Active switch is off: every change through it is paused, company admins' too. Leaving, cancelling an invitation and revoking a token still work | A company admin turns the connection on (see Connections) |
…; the group has too many repositories to check: Merge Pilot read your role on 25 of the company's N there, so ask for it on the group itself or ask a company admin (403) | GitLab group operations: your role in the group is not enough, and the group holds more of your company's repositories than Merge Pilot reads your role on (25) | Ask for the role on the group itself on GitLab, or ask a company admin |
<group> is shared with other groups (…): joining it would also give access there; ask a company admin when joining a GitLab group (403) | The group is invited into other groups on GitLab, so its direct members get access there too | A company admin joins you, or join the company's projects one by one |
this token is revoked already (409) when revoking a token | Someone revoked it a moment before you | Nothing: reload the Tokens tab |
| GitLab has more items than Merge Pilot reads, so the list is incomplete (more than 5000) | A list Merge Pilot decides with (a project's members with those of its groups, a merge request's commits, approval rules, protected branches, label events) has more than 5,000 items on GitLab. Merge Pilot does not decide on part of a list, so the operation fails | Reduce the list on GitLab (for example members given through very large groups), or ask your Merge Pilot administrator |
Read only: on a group variable, and Merge Pilot does not change this variable: every repository in the organization can use it, not only the company's (or every private repository …, repositories that are not the company's in Merge Pilot can use it too, the group holds projects that are not the company's in Merge Pilot, and they can use it too) when deleting it (403) | The variable reaches repositories of other teams, so Merge Pilot does not change it | Change it on GitHub or GitLab, with someone who owns it there |
this branch is under change management; only a company admin can change its protection when unprotecting a branch or changing force pushes (403) | The branch is one change management relies on, so only company admins change its protection, whatever the connection's rules say | Ask a company admin. On GitLab, after unprotecting it, run change management setup on the repository again to protect it and link its approval rule again |
Merge Pilot does not add you to this group, because a role in it reaches every project of the group and its subgroups, and the group holds projects that are not the company's in Merge Pilot when joining a GitLab group (403) | A group role would give you access to other teams' projects | Join the company's projects one by one, or ask the group's owners on GitLab |
Merge Pilot does not create this variable, because every project of the group and its subgroups could use it, and the group holds projects that are not the company's in Merge Pilot when creating a GitLab group variable (403) | Other teams' projects could use the variable | Create it on the company's projects, or on GitLab with someone who owns the group |
no variable named <key> that the company's repositories can use (404) when deleting a group variable | None of the company's repositories can use it: it belongs to another team, and is not listed | Nothing to do in Merge Pilot |
| Merge Pilot did not give you this access when leaving a GitHub repository you joined earlier | You left the company or were deactivated since, and Merge Pilot no longer tracks that access | Leave it on GitHub; a company admin sees it under Company → People |
| <GitLab or GitHub> answered <status>: … (for example the VCS refused the operation: GitHub answered 403: Resource not accessible by integration) | The VCS refused the call Merge Pilot made for you; the rest is the VCS's own words | Act on what the VCS says |
| There are multiple variables with provided parameters. Please use 'filter[environment_scope]'. when deleting a GitLab variable | Several variables share the key and the delete did not name one scope | Delete it from the Variables tab, which names the variable's environment scope; for group variables on GitLab Free, delete it in GitLab |
no variable named <key> with environment scope <scope> (404) when editing a GitLab variable | No variable of that key has that environment scope; Merge Pilot changes no other one instead | Edit it from the Variables tab, which names the variable's scope; reload the tab if it was changed on GitLab |
several variables are named <key>: name the environment scope of the one to change (400) | Several GitLab variables share the key and the edit did not name one scope | Edit it from the Variables tab |
What the project page offers
| What you see | Why | What to do |
|---|---|---|
| The Branches tab without Protect | The connection lets you unprotect branches or change force pushes, but not protect them: the tab shows for any of the three, each control only for its own rule | A company admin turns on Protect branches for your role, or protects the branch for you |
| The group's variables Read only: this needs at least <role> in <GitLab or GitHub> on one of the company's repositories in this group, while the repository's own variables can be changed | Changing a group's variables is judged by the group: the rule's minimum on one of your company's repositories in it | Get that role on one of those repositories, or ask a company admin |
| The Tokens tab, but no Create token | You may no longer create tokens, but tokens you asked for are still there: you can revoke them | Revoke them when they are no longer needed |
| This <GitLab or GitHub> connection is turned off: Merge Pilot operations are paused. You can still leave and revoke your tokens. | A company admin turned the connection off | Leave or revoke what you need to; for anything else, ask a company admin to turn the connection on |
| Merge Pilot read the first N branches in the time a request has: search for the branch to find it above the Branches list | GitLab answered too slowly to list every branch within the time one request has | Search for the branch by name |
| Leave project asks to confirm, naming a role you cannot get back here | Through Merge Pilot you can join again only with up to Developer (GitHub: Write) | Leave only if you want to give the higher role up: getting it back needs someone who manages access on the VCS |
| No GitLab groups button on the Projects page, and no Join project on a project page | You are an auditor (auditors change nothing), or the connection does not let your role join | Ask a company admin |
a hidden variable stays masked or hidden is chosen when a variable is created and cannot change (400) | GitLab hides a variable only when it is created, and a hidden variable cannot be unmasked or unhidden | Keep it masked; to unhide it, delete it and add it again |
GitLab answered 400: {"value":["is invalid"]} when adding or editing a masked or hidden variable | The value does not meet GitLab's masking rules (one line, no spaces, at least 8 characters) | Change the value, or turn Masked off |
<GitLab or GitHub> variables cannot be files, … have no description, … have no raw option, … cannot be hidden; use a secret, or GitLab has no write-only secrets: use a masked or hidden variable (400) | The option does not exist on that VCS | Leave the option out; use what the VCS has (GitLab: masked or hidden; GitHub: a secret) |
Merge Pilot's account was refused by <GitLab or GitHub>; check the connection (502) | The VCS refused the connection's own account: the GitLab bot user's token is revoked or expired, or the GitHub App's credentials are no longer accepted | A company admin checks the connection (Test connection) and gives it a new token, or fixes the App |
access_level must be 10 (Guest), 20 (Reporter) or 30 (Developer) or access_level cannot be above your own role on this repository (…) (400) when creating a project access token | Merge Pilot never gives a token Maintainer or Owner, nor a role above yours | Choose a lower role |
scope "…" is not allowed for project access tokens (or … for deploy tokens), choose at least one scope, expires_at is required, expires_at must be a date after today, expires_at can be at most 365 days from today, name is required (400) | The token's scopes, expiry or name are not ones Merge Pilot accepts | Fix the field; the dialog lists the allowed scopes |
| the VCS refused the operation: GitLab answered 403: … when creating a token | GitLab asks the account that creates tokens to be a Maintainer or Owner of the project; on GitLab.com, project access tokens also need Premium or Ultimate | Give the bot user Maintainer on the project, or check the GitLab.com subscription |
only who asked for this token, a company admin or someone allowed to create … can revoke it: … (403) | You did not ask for the token, and the connection's rule for its kind does not let you | Ask the person who created it, or a company admin |
<GitLab or GitHub>'s API rate limit is reached: try again in <N> seconds (429) | The VCS's API rate limit for the connection's account is used up for now | Try again after the time given |
Saving the rules is refused
| Message | Why | What to do |
|---|---|---|
| invalid permissions: <operation>: role "…" cannot be given operations (only user, policy_manager) | A rule named a role other than User or Policy manager (company admins may always; auditors only read) | Keep User and Policy manager only |
| invalid permissions: <operation>: min_access must be one of … | The minimum is not one of the VCS's roles (for example Guest on GitHub, or a turned-on rule without a minimum) | Choose one of the listed roles |
| invalid permissions: <operation>: min_access does not apply (0) | Joining and listing one's own repositories have no minimum | Leave it at 0 |
| invalid permissions: create_access_tokens: GitHub has no project access tokens or deploy tokens | The token operations exist on GitLab only | Leave them off on a GitHub connection |
Change management setup fails
The setup writes its steps to the repository one by one and reports the step that failed with the provider's reason (see When it fails). When a required step fails, what the run wrote is removed again.
| Message or step | Why | What to do |
|---|---|---|
| GitLab refused the approval rule; approval rules need GitLab Premium or Ultimate: … | GitLab Free has no approval rules, so the merge gate cannot be written | Use GitLab Premium or Ultimate for repositories under change management; Free repositories can be watched |
| A GitLab step refused with a permission error | The bot user is not a Maintainer of the project | Give the bot user the Maintainer role on the project (see Before you start) |
| An optional step failed, with a warning naming a setting | The setup succeeded without it | Turn the named setting on by hand in GitLab (Settings → Merge requests), or fix the cause and Re-run CM setup |
The live state of each step is on the repository's CM status card (see Setup status and repair).
Rate limits
GitLab and GitHub limit how many API calls Merge Pilot may make. Reaching the limit is not a failure:
- A job that hits the limit waits in Retry on the Jobs page until the limit resets (at most 2 hours) without using an attempt (see How jobs run).
- Background work (bulk operations, state syncs, imports of past merge requests) keeps a share of the limit for live merge requests and pauses first. The Projects page's Background work shows … task waits for a VCS rate limit to reset: the rest of its calls are kept for live merge requests., and a bulk operation Waiting for the VCS's API rate limit until …: the rest of its calls are kept for live merge requests.
- Scans and project analyses wait for the reset and go on; they do not fail.
Nothing needs to be done: the work goes on after the reset. If it happens often, split a large bulk operation, or ask the VCS administrator about the account's limits.
Deleting a connection is refused
The dialog says why and keeps Delete connection off:
- a VCS connection still has watched repositories or repositories under change management: take them out on the Projects page first;
- a tracker connection still receives change approvals: 1 VCS connection sends its change approvals to this tracker: link it to another tracker first (or N VCS connections send …). Link those VCS connections to another tracker, or none, in their settings.
Deleting a VCS connection stops Merge Pilot tracking the repository access people got by joining through it. That access stays on the VCS: it is listed under Company → People (see People).