UlikaDocs
Open Ulika

Getting started

  • Ulika documentation
  • How Ulika works
  • Requirements
  • Quickstart

Connect a site

  • Connect from the dashboard
  • Connect with the CLI
  • Connect with an AI agent
  • Approving a connection
  • Private previews
  • The GitHub App
  • Connect Vercel

Integrations

  • GitHub integration
  • Vercel integration
  • Netlify
  • Claude Code
  • Codex
  • MCP tools

Editing

  • The editor
  • The style panel
  • Sections and pages
  • Mobile preview, autosave and drafts

Publishing

  • Publish your changes
  • History and restoring a version
  • When a publish fails

Team

  • Team roles
  • Inviting people

Projects

  • Project settings
  • Delete a project
  • Website code

Troubleshooting

  • Needs attention reasons
  • Vercel problems
  • GitHub problems
  • CLI errors and exit codes
  • Frequently asked questions

Security and privacy

  • Security and privacy overview

CLI

  • CLI reference
  • CLI changelog

Troubleshooting

GitHub problems

Fix GitHub problems when connecting or publishing a site: GitHub App access, permissions, branch protection, pull request conflicts and webhooks.

Last updated October 14, 2026

Ulika reaches your code through a GitHub App that you install on a GitHub account and limit to the repositories you choose. Almost every GitHub problem comes down to one of three things: the App cannot see the repository, the App does not have the permission for what it is trying to do, or your branch rules need a person. This page lists each one with the exact words you will see and the fix.

For the full list of reasons a connect run can stop, see Needs attention reasons. For how the App is set up, see GitHub App.

Before you start#

  • Nothing is written until you approve it. If a step stops, Ulika has not changed your repository, unless the message says a branch or pull request already exists.

  • Many fixes happen on GitHub, on the App's page. On GitHub, go to Settings > Applications > Installed GitHub Apps > Ulika > Configure (for an organisation: your profile picture, Your organizations, Settings, then GitHub Apps under Third-party Access, and Configure next to the App). That page lets you add or remove repositories, accept permission changes, suspend or uninstall the App.

  • Organisation accounts need an admin. Only an organisation owner can accept permission changes or change which repositories an App can see.

  • After you fix something on GitHub, come back to Ulika. The browser screens re-check when the tab regains focus. In the CLI, run the same command again; it picks up where it stopped.

Installing and connecting the App#

not-configured#

What you see. "Connecting a repository is not set up on this deployment yet." On the connect screen, Connecting a repository is not available here with an Unavailable badge and "No GitHub App is set up here yet, so Ulika cannot ask GitHub for your code." On a demo deployment you may see a Demo badge and sample repositories.

Why it happens. The Ulika you are using has no GitHub App registered, or only part of its configuration. In production Ulika never falls back to sample data.

How to fix it. Ask whoever runs your Ulika deployment to finish the GitHub App setup. Meanwhile you can connect from your own machine with ulika init --local, which reads the repository locally.

Retries by itself? No.

sign-in-not-configured#

What you see. "GitHub sign-in isn't configured on this deployment. An owner needs to add the app's client secret before a repository can be connected."

Why it happens. The deployment has the App but not the secret that lets people sign in with GitHub.

How to fix it. An owner of the deployment needs to add the GitHub App's client secret. There is nothing to change on your side.

Retries by itself? No.

GitHub did not let Ulika read your email address#

What you see. On the login page after choosing Continue with GitHub: "GitHub did not let Ulika read your email address. Accept the updated Ulika GitHub App permissions on GitHub (Settings → Applications), or sign in with your email."

Why it happens. The Ulika GitHub App needs the Email addresses permission to know who you are, and GitHub has not given it yet because you have not accepted the updated permissions.

How to fix it. On GitHub open Settings > Applications > Installed GitHub Apps > Ulika and accept the pending permission request, then try again. Or sign in with your email and password: if you came from a link such as Activate, you are taken there after you sign in.

GitHub isn't connected yet#

What you see. The card GitHub isn't connected yet with the text "If you've already installed Ulika on GitHub, check again. If not, open GitHub and install it." with two buttons.

Why it happens. You started connecting but have not finished installing the App, or you installed it on a different account.

How to fix it.

  1. Click Open GitHub again.

  2. Choose the account that owns the site's repository.

  3. Choose Only select repositories and pick the repository (selecting is safer; Ulika can only ever see what you select), then click Install.

  4. Return to Ulika and click I've installed it, check again if it does not continue by itself.

If Ulika is installed on more than one of your accounts, you will see Which GitHub account is this website on? with a Use this account button for each. Pick the one that owns the repository.

Retries by itself? The screen re-checks when you return to the tab.

installation-suspended#

What you see. "Access to this GitHub account is suspended. An account admin can restore it from the GitHub apps settings, then try again." Title: Access to GitHub is suspended. In ulika connect this is the attention reason installation-access.

Why it happens. Someone suspended the App on that GitHub account without uninstalling it.

How to fix it. On GitHub open Settings > Applications > Installed GitHub Apps > Ulika > Configure and click Unsuspend (an account admin does this; if the App's owner suspended it, you cannot unsuspend it yourself). Then try again.

Retries by itself? No.

installation-revoked#

What you see. "Ulika's access to GitHub was removed. Connect GitHub again to continue." Title: Ulika's access to GitHub was removed.

Why it happens. The App was uninstalled, or its authorization was revoked. When an installation is removed, agent logins that depended on it are revoked as well.

How to fix it. Install the App again from the connect screen (Open GitHub again), select the repositories, and continue. If an agent login was revoked, approve it again when asked.

Retries by itself? No.

repository-gone#

What you see. "That repository is no longer available to Ulika. It may have been renamed, transferred or removed from the installation. Pick it again." Title: That repository is no longer reachable.

Why it happens. The repository was renamed, transferred, deleted, or removed from the App's selected repositories. GitHub answers the same way for all of these, on purpose, so Ulika cannot tell them apart.

How to fix it. Check the repository still exists and that it is selected under the App's Repository access. Then pick it again in Ulika.

Retries by itself? No.

repository-not-in-installation in the browser#

What you see. In the CLI this is the attention reason repository-not-in-installation: "Ulika's GitHub App cannot see owner/name. Add it under Repository access for owner on GitHub, then run the command again." In the browser it appears as repository-gone above, or as an empty list of repositories to choose from.

Why it happens. The App was installed with Only select repositories and this repository was not one of them, or it was installed on a different account than the one that owns the repository.

How to fix it.

  1. Open Settings > Applications > Installed GitHub Apps > Ulika > Configure for the account that owns the repository.

  2. Under Repository access, add the repository (or choose All repositories) and save.

  3. Return to Ulika and continue (browser) or run the command again (CLI).

If the owning account is an organisation, an organisation owner may have to approve the App first.

Retries by itself? No.

permission-downgraded#

What you see. "Ulika can no longer read this repository's contents. Review the permissions granted to the app on GitHub, then connect again." Title: Ulika no longer has permission to read the code. In the CLI, app-permissions-not-accepted: "Accept Ulika's updated GitHub permissions".

Why it happens. The App's Contents permission was reduced after it was installed, or GitHub refused a call because the permission is missing. GitHub requires an account admin to accept permission changes.

How to fix it. Open the installation's Configure page on GitHub, accept the pending permission request, then connect again.

Retries by itself? No.

permission-missing#

What you see. "Ulika cannot write to this repository yet". Ulika was installed with read-only access. "Nothing was written."

Why it happens. Reading your code needs only Contents: Read. Writing the connector branch needs Contents: Read and write and Pull requests: Read and write. An App installed before writing was introduced has only read access. Ulika checks the permission map first, so you see this instead of a GitHub error.

How to fix it.

  1. On GitHub open Settings > Developer settings > GitHub Apps, click Edit next to the App, open Permissions & events and set Contents and Pull requests to Read and write. (If you are not the App's owner, ask them.)

  2. Accept the change on the installation: Settings > Applications > Installed GitHub Apps > Ulika > Configure.

  3. Try again.

Retries by itself? No.

app-permissions-not-accepted banner#

What you see. A banner Approve Ulika's updated GitHub permissions with a Review on GitHub button and the text "Ulika now asks to read your host's build results (commit statuses, checks and deployments), read-only, so it can confirm a preview without a Vercel connection. Until you approve, everything keeps working, and Ulika checks your live site after merging instead."

Why it happens. Ulika asks for three read-only permissions (Commit statuses, Checks, Deployments) so it can verify a build through GitHub. GitHub emails the installation owner a review request, and until it is accepted the App keeps its old permissions.

How to fix it. Click Review on GitHub and accept. The banner disappears by itself when you return to the tab. This is optional; without it Ulika verifies your live site after merging.

Retries by itself? The banner re-checks every time you return to the tab.

reapproval-required#

For organisation repositories, an agent's writes stop after seven days until someone approves again with ulika connect --reapprove. See Needs attention reasons.

Ulika's own limit: "You have read a lot of repositories just now"#

What you see. "You have read a lot of repositories just now. You can try again in about 3 minutes."

Why it happens. Reading a repository costs GitHub quota that your whole account shares, so Ulika limits how often a workspace can authorise, list, read and import within five minutes. It is not a GitHub error.

How to fix it. Wait for the time in the message. The ulika connect runs from agents have their own larger allowance and wait automatically instead of failing.

Retries by itself? Yes, in agent runs. In the browser, wait and try again.

rate-limited#

What you see. "GitHub is limiting requests right now. Wait a few minutes and try again." Title: GitHub is asking us to slow down. In a connect run: paused, continuing at 14:05.

Why it happens. GitHub's own rate limit, shared by everyone using the App, or a secondary limit on writes.

How to fix it. Nothing. Ulika waits for the time GitHub gives and continues.

Retries by itself? Yes.

unavailable#

What you see. "We could not reach GitHub just now. Try again in a moment." Title: GitHub could not be reached.

Why it happens. A network problem or a GitHub outage.

How to fix it. Check GitHub's status page and try again.

Retries by itself? Yes, up to five times with growing waits.

The approval page#

The page a ulika connect link opens checks GitHub live. Each notice below is shown in the page's own words. See Approving once for the normal path.

You seeWhat it meansWhat to do
Could not check right now, with Try againGitHub did not answer. Nothing was approved.Click Try again.
"GitHub did not find any installation"The Ulika app is not on your account.Install it on the account that owns your site, then check again.
"GitHub asked an owner"An organisation owner has to approve the install.Open the link again once they have.
"Ulika has started a lot of GitHub checks"Ulika's own limit, not GitHub's.Wait a few minutes and try again.
Install the Ulika app on GitHubThe app was suspended or removed.Install it again, then return to the page.
"You declined on GitHub"You cancelled the GitHub screen.Click Continue with GitHub again.
"Your GitHub account uses a different email"Your GitHub email is not the one on this Ulika account, so GitHub was not linked.Nothing. The accounts you approved with still count.
"This approval request is no longer open"The code expired, was used, or was denied.Run the command again for a new code.
"That GitHub check was no longer valid"The GitHub step expired, was already used, or was started in another browser.Click Continue with GitHub again.
Add your email to continueGitHub shared no verified email.Enter your email and confirm it. No second account is created.
"You can still approve"Ulika's budget for repository checks is spent.Approve anyway. If no repository was picked, the site ends in the attention list as ambiguous-repository, with the command to run: ulika connect <url> --repo owner/name.

Protected branches#

branch-protection#

What you see. In a connect run: "branch protection blocks the change". The sentence reads "Your branch protection requires a review or checks that Ulika cannot satisfy. Approve and merge PR #16 on GitHub; Ulika then checks your live site by itself."

Why it happens. Your default branch requires a review or passing checks that Ulika (a bot) cannot provide. Ulika never asks to bypass your rules, so a person has to merge.

How to fix it.

  1. Open the pull request from the link.

  2. Approve it if a review is required, wait for the checks, and merge it. A teammate with the right access can approve.

  3. Do nothing else: Ulika notices the merge, checks your live site and marks the connection live.

Retries by itself? After the merge, yes.

needs-merge#

What you see. When you publish: Waiting for the pull request to be merged. "Your branch is protected, so Ulika opened a pull request with this publication. It goes live as soon as it is merged on GitHub." with an Open the pull request button. Underneath: "To publish directly next time, add Ulika to the bypass list of this branch's ruleset (repository rules)."

Why it happens. Sites that publish through Git write one file, .ulika/content.json, to the default branch. Ulika tries a direct commit first. If your branch rules refuse, Ulika opens a pull request on a branch named ulika/content-... instead and asks GitHub to merge it automatically if your repository allows auto-merge. If it cannot, the publication waits for you.

How to fix it.

  1. Click Open the pull request and merge it.

  2. To publish directly in future, open your repository's Settings > Rules > Rulesets and add the Ulika GitHub App to the bypass list of the ruleset that protects the branch. This is your choice; Ulika will never do it for you.

Retries by itself? Yes. Once the pull request is merged, the release is checked on your live site and completes. Your drafts stay saved while you wait.

content-file-changed#

What you see. Your repository's .ulika/content.json was changed outside Ulika. "Nothing was published, and nothing on GitHub was overwritten. Your drafts are saved. Publish Ulika's version over that change, or look at it first." Buttons: Overwrite with Ulika's version and View the commit on GitHub.

Why it happens. Ulika remembers the version of .ulika/content.json it last wrote. If the file on your default branch is anything else (someone edited it or reverted it), Ulika refuses to overwrite it silently.

How to fix it.

  1. Click View the commit on GitHub and look at what changed.

  2. If you want Ulika's content to win, click Overwrite with Ulika's version. If the outside change matters, copy what you need first.

Retries by itself? No. It waits for your choice.

"The repository received several commits while publishing"#

What you see. "The repository received several commits while publishing, so nothing was published yet. Publish again in a moment; drafts remain saved."

Why it happens. Ulika only fast-forwards. If your branch keeps moving while it publishes, it re-reads and retries a few times, then gives up.

How to fix it. Publish again in a moment.

Retries by itself? Ulika retried a few times before showing this.

Pull request conflicts#

branch-exists#

What you see. That branch already exists: "Every name from ulika/setup upwards is taken in this repository. Delete or rename one of them, then try again."

Why it happens. The connector branch is named ulika/setup, with a suffix when taken. Every candidate name already exists.

How to fix it. Delete or rename old ulika/setup... branches in the repository (for example leftovers from earlier attempts), then try again.

Retries by itself? No.

repository-changed#

What you see. This repository changed since we read it: "New commits landed on the default branch since Ulika read it, so this diff no longer matches your code. Read the repository again, then review the connector."

Why it happens. Ulika starts the connector branch from the exact commit it analysed and refuses to write if your default branch has moved, because a pull request built on the old state could undo newer work. In ulika connect this is the source-changed reason.

How to fix it. Read the repository again in Ulika (or run the command again), then review the new diff.

Retries by itself? No.

source-changed#

What you see. "the source changed while connecting". Read the repository again in Ulika, review the connector, then run the command again. A line under it names the field Ulika could not locate. Also shown on a connected site as "Files this connector binds to changed on your default branch after Ulika read them. Merging would stop your next build".

Why it happens. Someone changed files the connector binds to between Ulika reading them and the merge. Merging could break your next build.

How to fix it. Re-scan the site in Ulika (or run ulika connect again) and create a new connector pull request. Close the old one.

Retries by itself? No.

head-moved#

What you see. The connector branch changed after Ulika wrote it: "Someone pushed a commit onto the ulika/setup branch after Ulika wrote it. Ulika only merges the exact commit it created and checked, so it stopped. Review the pull request on GitHub, or create a new connector pull request."

Why it happens. Every merge Ulika performs is pinned to the exact commit it created. An extra commit on the branch changes that.

How to fix it.

  1. Open the pull request and look at the extra commits.

  2. If they are fine, merge the pull request on GitHub yourself. Otherwise close it and create a new one.

Retries by itself? No.

abandoned#

What you see. The pull request was closed without merging. In ulika connect: pull-request-closed.

Why it happens. The connector pull request was closed, so the connector is not installed.

How to fix it. Create a new connector pull request (or run the command again with --reopen). Ulika detects the closure through GitHub's notifications, or at the next hourly check.

Retries by itself? No.

repository-connected-elsewhere#

What you see. This repository is connected in another workspace: "Another Ulika workspace already connected this repository, and two workspaces publishing into one repository would overwrite each other."

Why it happens. A repository is bound to one workspace at a time.

How to fix it. If you are a member of the other workspace, the message names it and the project: disconnect the repository or delete that project there, then connect it here. If you are not, Ulika does not say which workspace it is: sign in with the account that owns it, or ask that workspace's owner. See Needs attention reasons.

Retries by itself? No.

repository-id-unknown#

What you see. "GitHub did not return this repository's id, so Ulika cannot make sure no other workspace publishes into it. Nothing was written. Try again in a moment."

How to fix it. Try again in a moment.

Retries by itself? No.

Webhooks#

GitHub tells Ulika about things that happen where Ulika cannot see them: a connector pull request merged or closed, your host reporting a build, a push to the default branch, and the App's permissions being accepted or the App being suspended. Each message is signed by GitHub. Ulika checks the signature first, and the message only tells it where to look; Ulika then re-reads the real state from GitHub.

A merge or build is not noticed#

What you see. You merged the connector pull request (or a build finished) but Ulika still says it is waiting.

Why it happens. GitHub's notification did not arrive or was ignored. This can happen when a deployment's webhook is not configured.

How to fix it.

  1. Wait a short while. Ulika also checks pending connectors on a schedule, once an hour, so a missed notification is caught.

  2. In the browser, press Check again on the preview card. In the CLI, run the same command again; it re-checks right away.

  3. If you run your own Ulika deployment, confirm the GitHub App's webhook is Active, points at /api/github/webhook on your Ulika address, uses content type application/json, and has the same secret as ULIKA_GITHUB_WEBHOOK_SECRET. Without the secret the endpoint answers 503 and ignores everything. A wrong secret gets 401.

Retries by itself? Yes, hourly.

Events Ulika listens to#

The App should be subscribed to Pull request, Deployment status, Status, Check run and Push. Installation events are always delivered. Events about other things are ignored, and a repeated delivery is skipped.

If something still does not work#

  • Run ulika connect <your site> --check to see every blocker and warning at once, without writing anything.

  • Make sure you are signed in to the GitHub account that owns the repository when you install the App.

  • For a repository Ulika cannot read at all (too large, unusual layout), use the local scan: ulika init --local from the site's checkout. See CLI problems.

Was this page helpful?

PreviousVercel problemsNext CLI errors and exit codes

On this page

  • Before you start
  • Installing and connecting the App
  • not-configured
  • sign-in-not-configured
  • GitHub did not let Ulika read your email address
  • GitHub isn't connected yet
  • installation-suspended
  • installation-revoked
  • repository-gone
  • repository-not-in-installation in the browser
  • permission-downgraded
  • permission-missing
  • app-permissions-not-accepted banner
  • reapproval-required
  • Ulika's own limit: "You have read a lot of repositories just now"
  • rate-limited
  • unavailable
  • The approval page
  • Protected branches
  • branch-protection
  • needs-merge
  • content-file-changed
  • "The repository received several commits while publishing"
  • Pull request conflicts
  • branch-exists
  • repository-changed
  • source-changed
  • head-moved
  • abandoned
  • repository-connected-elsewhere
  • repository-id-unknown
  • Webhooks
  • A merge or build is not noticed
  • Events Ulika listens to
  • If something still does not work
Ulika documentationFAQ · CLI reference · Terms · Privacy