Troubleshooting
Every step of a GitHub Actions onboarding can stop for a reason you can fix yourself. Find the step you are on below.
Two things are worth trying before anything else. Retry run picks up from where the run stopped. Open the run log takes you to the GitHub Actions run for the full output.
Connecting the GitHub account
GitHub is not offered at all
UIGraph has to be set up with a GitHub App before anyone can use this route. If your instance is missing it, the step never appears and you are sent back to your services. Ask whoever runs your UIGraph instance to set it up, or use the UiGraph skill instead.
The onboarding step will not open
Only an admin of the UIGraph organization can import a repository. If you are not one, ask an admin to run it.
GitHub sends you back without connecting
The install has to finish on GitHub before UIGraph sees it. If the tab closed early, select Install GitHub App again.
If you signed in on GitHub as a user who cannot see the installation you picked, UIGraph will not accept it. Sign in as a user who has access to that account or organization, then install again.
Picking the repository
The repository is not in the list
The list only holds repositories the GitHub App can read. On GitHub, open the UIGraph app's settings for that account and add the repository to what it is allowed to see.
The repository is greyed out
Archived repositories cannot be imported. Unarchive it on GitHub first.
You are not sure which one to pick
Start with one repository. UIGraph documents it end to end, and you can bring in the rest afterwards.
Checking the secrets
The check says values are missing
The run needs a model to read your repository with. UIGraph looks for these on the repository and on the GitHub organization that owns it.
| Value | Where it goes |
|---|---|
AI_PROVIDER_API_KEY | Secret only |
AI_PROVIDER_MODEL | Secret or variable |
AI_PROVIDER_API_URL or AI_PROVIDER_NPM | Secret or variable, either one |
Use Open GitHub settings to add what is missing, then refresh the check. See AI Providers for what the values should be.
The check cannot read the secrets
UIGraph could not reach the Actions settings on that repository. This is usually a permissions problem. Check on GitHub that the UIGraph app still has access to the repository, then try again.
You added a value and the run is still waiting
If a value goes missing after the run is queued, the run waits rather than failing and names what it is waiting on. Add it on GitHub, then select Recheck.
The instance is missing its own settings
The run cannot start if your UIGraph instance has not been given its public address. Ask whoever runs your instance to finish its setup. See Environment Variables.
Creating Branch
UIGraph could not open the branch it works on.
- Check that UIGraph is still connected under your GitHub account.
- Check that the app is still allowed to write to this repository, not just read it.
- Check that the repository has a default branch. A repository with no commits at all cannot be imported.
Then select Retry run.
Preparing
GitHub could not start the run.
- Check that GitHub Actions is enabled on this repository. It is off by default on some organizations.
- Check that your organization allows the actions the workflows use.
Then select Retry run.
Installing
The tools that read your repository could not be installed. This is almost always temporary, so a retry often clears it. If it keeps happening, open the run log and check whether your runners can reach the internet.
Generating
Your repository could not be read through. This is the step that calls your AI provider, so it is the one that fails when a provider setting is wrong.
- Check that the key is valid and has not expired.
- Check that the model name is one your provider actually offers.
- Check that you set the endpoint or the provider package, and that it matches the key.
- Check that your provider is not rate limiting or out of credit.
Fix the value on GitHub, then select Retry run.
This is also the longest step. A few minutes is normal on a large repository.
Wrapping Up
What was found could not be saved back to your repository.
- Check that UIGraph can write to this repository.
- Check that your branch protection rules do not block the branch UIGraph works on.
The run also stops here on purpose if anything outside .uigraph.yaml and .uigraph/ changed. That guard exists so a run can never touch your source. If you hit it, open the run log to see what was written, then retry.
Uploading to UIGraph
The run could not reach UIGraph.
- Check that your UIGraph instance is reachable from GitHub. A private instance behind a firewall cannot be reached from GitHub's runners.
- Check that the UIGraph values on the repository were not removed or overwritten.
Then select Retry run.
Finishing Up
The run did not close out cleanly. Retry it, or open the run log to see what happened.
After onboarding
The pull request never opened
Onboarding commits to a branch of its own and opens a pull request from it. If the run finished but no pull request appeared, check on GitHub whether pull requests are enabled and whether one is already open from that branch.
Updates stopped after the merge
UiGraph Sync and UiGraph Artifact Update only run on your default branch. If you merged the onboarding pull request somewhere else, they will not run.
Both use the same values you set during onboarding. If you removed those secrets afterwards, both workflows fail.
The artifact pull requests keep piling up
UiGraph Artifact Update opens one pull request per push that changes your code. Merge or close them as they come in. It ignores pushes that only touch .uigraph.yaml, .uigraph/, or the UIGraph workflows, so it never reacts to its own output.