Connect GitHub

Use Connect GitHub to link your account and choose the repositories Zof checks. This one flow handles the Zof GitHub App installation when needed. Setup takes about 5 minutes, plus any wait for approval. A company admin in Zof starts the connection. A GitHub organization owner may need to approve repository access before it can finish.

The console uses an OAuth App to sign you in and confirm your GitHub role. The Zof GitHub App is a separate GitHub App installed on your organization or personal account; it posts the Zof / Control check on the repositories you choose. Installing the Zof GitHub App does not approve the console's OAuth App for your organization.

Fix pull requests use another App, Zof Fix App. Once GitHub is connected, Fix pull requests on the Connection tab shows its recorded installation and write permissions separately. A run's fix drawer shows one line only when something is missing. A GitHub organization owner installs it or accepts Contents: write and Pull requests: write once for the installation, and includes the repositories that need fixes. Permitted members can then open fix pull requests using their own linked GitHub account and repository write access. After setup, come back to Zof and the status updates by itself, or choose Refresh Fix App status on the Connection tab. Refreshing does not open a pull request. See Fix a failure with Codex.

Create your Zof company

You can sign up with a verified personal or work email. If you do not have a company yet, name it and choose Create company. You become its admin. After you start a free trial or choose a plan, the next step, Connect GitHub, connects it straight away; choose Skip for now to do it later from Home or Integrations. The company starts empty, without demo data. If a company has already invited your verified email, Zof offers Join with that company's name first. See Get started.

Demo is read-only and offered only to eligible Zof staff accounts. Choose Leave demo to return to company setup or your existing company. Sign-ups are paused applies only to new company creation; it does not disable existing companies.

Before you start

• You're a company admin in Zof. Anyone can link their GitHub account, but only a company admin can connect GitHub to the company. See Who can do what.
• You're an admin of the GitHub organization the Zof GitHub App goes on, or the owner of the personal account. The Zof GitHub App connects to an organization or a user account, not to an enterprise account.
• Your primary email on GitHub is verified. Zof doesn't link a GitHub account whose email GitHub reports as unverified.
• You're on your company's main Zof address. If the card says "GitHub connections start on your company's main Zof address", ask your admin for it. If it shows a link to Integrations on another address, follow it.

Connect your GitHub account

1. On Home, click Connect GitHub: it's the first step for a new company, and the panel in place of the release tiles for a company that already has test runs. That panel's Connect GitHub, like the ones on New run, Admin › Users and Admin › Overview, opens the connect dialog in Integrations straight away. You can also start from the GitHub card in Integrations. While a step isn't done, the dialog says why Continue is off, for example "Link your GitHub account above to continue." Once your organization is connected, the dialog is a short summary instead (Organization connected, the repositories and where to manage them, and Done), with your own GitHub account as a separate optional block. Your GitHub link also shows as one line, with Disconnect, in Integrations and Settings › Profile, whether or not the company has GitHub connected.
2. If your GitHub account is already linked, pick the account to connect under GitHub account and choose Continue. Otherwise continue to GitHub.
3. On GitHub, approve the request. Zof asks for organization access (read:org) and your email addresses (user:email). It reads only your organizations, your role and your verified email. Zof needs the verified email before an admin can accept a system map draft, or stop or adopt a stored copy. Dismissing a draft doesn't need it.

When you click Link my GitHub account, GitHub asks which of your GitHub accounts to link; it asks the same when you sign in with GitHub. GitHub sends you back to the page where you started, including Home and the tab of the GitHub page you clicked from, to choose the organization or personal account to connect. Connection errors appear there too. If your GitHub account is already linked, Zof reuses that link. If the card says your GitHub link doesn't include organization access, click Reconnect GitHub and approve again.

If you linked GitHub before Zof asked for user:email, the System map screen says so the first time you accept a draft or stop or adopt a stored copy. Click Reconnect GitHub there and approve again. GitHub sends you back to the System map screen. If the link fails, you land on Integrations with the message.

Disconnect your personal GitHub account

Under Your GitHub account, the Connection tab shows Linked and "Linked as @username". Click Disconnect, read the confirmation, then choose Disconnect GitHub. Cancel or press Escape to keep the link.

This signs Zof out of your personal GitHub account. The Zof GitHub App stays installed for the company, and its company connection and repository checks stay in place. After success, the tab offers Link my GitHub account again.

You need a verified email with email sign-in available, so disconnecting cannot remove your only way back into Zof. While you are signed in, one confirmation is enough; you do not need a fresh sign-in. Disconnect is unavailable in demo mode.

If GitHub cannot confirm revocation, Zof keeps the link and asks you to retry. If GitHub access was revoked but the local link could not be removed, the message says so: retry Disconnect to finish. If the login cannot be read, the card says it is unavailable; it never guesses a username.

Connect an existing installation

Click Connect GitHub, then select the GitHub organization or personal account by name. Zof checks for its existing Zof GitHub App installation and connects it to your company. You do not need an installation ID or a repository-settings change.

The person finishing the connection must be a company admin in Zof and an admin of the selected GitHub organization, or the owner of the personal account. An installation already connected to another Zof company cannot be claimed.

Approve repository access

If the selected account has no Zof GitHub App installation, the same connection journey takes you to GitHub. Select the same account, choose all repositories or only the ones Zof should access, and confirm on GitHub.

If GitHub requires an organization owner's approval, send the request there. Zof saves the selected account so you can close the page and return after approval. A person who administers both the Zof company and that GitHub organization can then finish the connection from Home or Integrations. GitHub approval is still required; linking your personal account does not grant repository access.

The redirect from GitHub expires after 10 minutes, but your saved account selection lasts 30 days. Return to Home, choose Connect GitHub, and use Check again to resume after a delayed approval. You can also resume from Integrations. If the saved selection expires, choose the account again.

After connecting, Zof says your account "is connected. Discovering its selected repositories…" until it has read them. It checks progress every 10 seconds for up to 5 minutes. After that, use Check again. A completed connection does not by itself confirm that verification is configured or running.

Recover an unavailable connection

A company admin may see App removed in Integrations, and a notice on Home in place of the release tiles, when GitHub confirms that the installation is gone. Needs review means GitHub still lists the installation but Zof cannot confirm the account's installation. In either case, Fix now on the GitHub card opens the Health tab, and the GitHub page says what to do. The repository list may be out of date until then.

• For a missing installation, choose Replace unavailable connection on Home or in Integrations. This releases the unavailable company connection after another check with GitHub. Then use Connect GitHub to choose the account and complete its installation or connection. Until the connection is replaced, Home's Connect GitHub step asks you to replace it first instead of offering to continue with the old account. Replacing needs your own GitHub account linked: if it isn't yet, the box on Home and the Health tab offer Link my GitHub account first, which may ask you to sign in again, and then Replace unavailable connection. If the page links to Integrations on the setup site, follow that link to replace the connection there.
• For Needs review, click Contact support, which emails support@zofai.com, and quote the support reference on the Connection tab. A company admin cannot override this state.

To move to another GitHub account, uninstall the Zof App from the old account and replace the connection before you delete that account. Deleting it first can leave the connection waiting for a Zof review.

If replacement fails, check the current message before retrying. A replacement is not complete merely because you clicked the button. Disconnecting your personal GitHub login does not repair the company's installation.

Disconnect the company's GitHub

Disconnecting is uninstalling the Zof GitHub App on GitHub. On the GitHub integration page (Connection tab), choose Uninstall on GitHub to open the installation's settings, then uninstall it there. After you uninstall on GitHub, Zof shows Not connected. There is no Sync button: the repository list updates automatically from GitHub.

Change which repositories Zof checks

1. In Integrations, click Manage on the GitHub card. If it shows Fix now, do that first.
2. Under Repository access, click Choose repositories on GitHub.
3. On GitHub, add or remove repositories and save.
4. Back in Zof, reload the Configuration tab.

A repository you removed leaves the list.

What the status word means

The GitHub card and page read one word, from the connection, merge blocking on default branches, deliveries and recent merges.

Check that it worked

1. Open Integrations. The GitHub card reads Connected, or Setup incomplete until your repositories block merges. See What the status word means.
2. Open the card. The GitHub page says "Installed on" your organization.
3. Configuration lists the repositories you chose.
4. Open a pull request in one of them. A Zof / Control check appears on it.

If the badge reads "Waiting for GitHub", GitHub hasn't confirmed the install yet. If it reads "Suspended", the Zof GitHub App is installed but suspended on GitHub, and the check isn't running. A GitHub organization owner resumes it in the organization's GitHub settings. If the card shows Connect GitHub, the company has no connection even if your personal GitHub login is Linked.

If another company's free trial already used this GitHub account, GitHub still connects, but your company's trial ends and its credits are removed. The card then says "This GitHub account already had a free trial." See Free trial.

GitHub organization access

If GitHub refuses to show Zof your organization role, nothing is connected. An org owner checks access for the console's OAuth App, separately from the Zof GitHub App installation.

The same access decides which organizations Connect GitHub lists. A new organization doesn't appear until it allows the console's sign-in app. Grant or request access as below, then choose Check again under the list.

1. Open the organization on GitHub and choose Settings → Third-party access → OAuth app policy.
2. If OAuth App access restrictions are enabled, review the console sign-in app and approve its access. If it is not listed, the person connecting can open their own Settings → Applications → Authorized OAuth Apps, select the console app, and request organization access for the owner to approve.
3. Return to Integrations and use Check again, or Connect GitHub to choose the account again.

An inaccessible-membership message does not prove an OAuth App restriction or that you are not an admin. Check that Zof is linked to the intended GitHub account and ask an owner to check your membership and organization access. A confirmed non-admin gets the separate "Only an admin" message and needs an admin of both the GitHub account and Zof company to connect it.

If the install didn't finish

When GitHub sends you back, the card shows a message. Nothing was connected unless the message says so. Find the message below.

Other messages say what to do in their own words. A message that starts "GitHub setup didn't finish" ends with a code in brackets. If a message keeps coming back, email support@zofai.com with the message.

If linking your account fails

Not supported yet