Connections and access

When a run cannot reach something outside its sandbox, a repository, a connected tool, or a document source, the fix is almost always to reconnect. The platform holds the credential for each connection and uses it on your behalf, so you do not paste a token in twice; you re-authorize the connection and the platform refreshes its own copy. This page covers the connections a run leans on and how to restore each. If a run is parked waiting on one of these, you will have arrived from its blocked state on flows and runs.

Which connection is which

A run reaches four kinds of thing outside its sandbox, and each fails in its own scenario below. A repository provider (GitHub or Azure DevOps) is how a run clones your code. A connected tool is an MCP server the agent calls while it works. A document source (like Google Drive or OneDrive) is where an imported context document was pulled from. The first two are what a blocked run waits on; the third surfaces when an import or refresh fails. If you are not sure which you are on, the run's blocker note or the failing surface names it, and every one of them offers Test Connection to confirm.

GitHub or Azure DevOps authorization failed

What you see. A repository provider shows a problem, or a Test Connection on a repository reports that access was refused. Work that needs the provider cannot reach it.

Why it happens. A connection's credential can expire, be revoked, or stop covering the repository you are pointing at. For GitHub, the connection runs through a GitHub App, and most failures trace to the App rather than to a bad password: the App is not installed for the repository's owner, it is installed but limited to a set of repositories that does not include this one, or it is installed without the permission the work needs. For Azure DevOps, the connection uses a personal access token, and a failure usually means the token expired, was revoked, or does not carry the scopes the work needs.

How to fix it. Open the provider or the repository's detail page and run Test Connection; it names the specific cause rather than a generic failure. Then:

• The credential expired or was revoked. Reconnect the provider to re-authorize and refresh the stored credential.
• The GitHub App is not installed, or this repository is not in its set. Install the App for the owner, or add the repository to the App's selected repositories, then Reauthorize the provider. If your organization enforces single sign-on, the App may also need its authorization approved for the org before the token can see the repository.
• The GitHub App is missing a permission. Grant the App the access the work needs on the repository, then reauthorize. A permission change takes effect on the next attempt; you do not have to rebuild anything.
• An Azure DevOps token expired or lacks scope. Generate a new token with the scopes the work needs and reconnect. Check the token is from the right organization's Azure DevOps instance, since a token from another org will be refused.

On GitHub Enterprise, the connection points at your own GitHub instance rather than github.com, so a failure names that instance; the causes and fixes above are otherwise the same.

A repository could not be cloned

What you see. A run shows blocked with a note that it needs access to a repository, naming the repository it could not reach.

Why it happens. A run works against a fresh clone of your repository inside its sandbox, and the clone needs a credential that can reach that repository. When the credential is missing, expired, or does not cover the repository, the platform parks the run rather than failing it, so the work waits where it stopped instead of starting over. The underlying cause is the same family as the authorization failures above: an expired credential, a GitHub App that is not installed or does not include this repository, or an account that does not have access to it.

How to fix it. The blocked run links the fix. Authorize or reconnect the repository's connection, then resume the run; it rechecks access and clones from where it left off. If reconnecting alone does not clear it, run Test Connection on the repository to see which of the causes above applies, fix that, and resume. Because the run was parked rather than failed, nothing before the clone is lost.

A connected tool will not connect or its sign-in expired

What you see. A connected server shows that it needs sign-in, a Test Connection on it reports it could not be reached or was refused, or a run is blocked waiting on it.

Why it happens. A connected server reaches the platform over a transport and signs in one of a few ways, and a failure is either an authorization gap or a reachability problem. The sign-in can be missing because no one has authorized the server yet, or expired because a token aged out and could not be refreshed. Separately, an http or sse server can be unreachable because its address is wrong, it is down, or a network path is closed. A server's sign-in is held per person or per workspace depending on how it authorizes, so one person can be signed in while another is not.

How to fix it. Open the server's config and run Test Connection; it tells you whether the problem is sign-in or reachability.

• It needs sign-in, or the sign-in expired. Use Authenticate or Reauthorize to run the server's sign-in flow again, a browser sign-in or a device code depending on the server, which refreshes the stored credential.
• It could not be reached. Check the server's address and that it is running and reachable from the platform; this is a connectivity fix, not a sign-in one.
• It connects and signs in but offers no tools. The server is reachable and authorized but advertised an empty tool list. Check that the server is configured to expose the tools you expect, and that the connection has not narrowed the set down to none.

A run blocked on a connected tool clears once the server is reachable and signed in again: resolve it here, then resume the run.

A document import or refresh failed

What you see. Importing or refreshing a context document from a source like Google Drive or OneDrive fails, or asks you to reconnect.

Why it happens. A context document imported from a connected source keeps a connection to that source so it can be refreshed. When that connection's sign-in expires and cannot be renewed on its own, the source moves to a state that needs you to sign in again before it can list or pull files. Documents you already imported stay where they are; it is the live connection to the source that needs restoring.

How to fix it. Open the document source and Reconnect it to sign in again. Once the connection is restored, import or refresh the documents you need. A document you keep as a static copy is unaffected by the source connection; reconnecting matters when you want to pull the latest from the source.

Clearing a blocked clone, start to finish

A nightly run on the invoice export plan shows blocked in the morning, with a note that it needs access to the repository it was going to clone. The run did not fail and it did not start over; it parked in front of the clone and waited.

The note links straight to the repository's connection. You open it and run Test Connection. It does not report a bad password; it reports that the GitHub App is installed for the owner but its selected repositories do not include this one. Someone added the repository after the App was first set up.

The fix is at the source. You add the repository to the App's selected repositories on GitHub, come back, and Reauthorize the provider so the platform refreshes its copy. Test Connection now passes. You resume the run; it rechecks access, clones, and continues from the step it stopped on.

One blocked note, one named cause, one reconnect. Nothing before the clone was lost, and the run picked up where it parked.

Still blocked after reconnecting

If you reconnected at the source and the run still will not move, run Test Connection once more and read the cause it names; reconnecting refreshes the credential, but an App installation that still excludes the repository, or a token still missing a scope, reports the same cause again. Quote the run's identifier and the connection it named so anyone looking with you lands on the same place. If the diagnostic passes but the run stays blocked, your account contact can pick it up from the run identifier and the blocked step.

Why connections are restored, not re-entered

Every fix on this page is a reconnect rather than a re-paste, and that is deliberate. When you connect a provider, the platform stores the credential and uses it on your behalf, and it never shows the value back to you or asks you to type it a second time. So when a connection lapses, the move is to re-authorize at the source, which lets the platform refresh its own copy, rather than to handle the secret yourself. It keeps a credential from being copied into places it should not live, and it means restoring access is a sign-in, not a secret-management chore.

For a current user, the loop is the same across all four: open the connection, run Test Connection where it is offered to see the exact cause, reconnect or reauthorize at the source, and resume the run if one was waiting.

For an administrator, the provider connections are the ones to keep current. A GitHub App's installation and repository selection, and an Azure DevOps token's scope and expiry, are where access quietly lapses, and Test Connection is the fastest way to confirm where.

For a prospect, the takeaway is that access is held as connections the platform manages, not as secrets scattered through configuration. Restoring access is a sign-in, and the diagnostic tells you exactly what to sign in to.