Onboard with GitHub Actions
Audience: An admin bringing a repository into UIGraph
Output: The repository documented in UIGraph, with the generated artifacts and three UIGraph workflows committed on a branch of its own.
UIGraph reads the repository through a GitHub App you install, and the run happens on your own GitHub runners. Your code never leaves GitHub.
Before you start
- You need to be an admin of the UIGraph organization.
- GitHub Actions has to be enabled on the repository.
- You need an API key for the AI provider that reads the repository.
Private repositories work. Archived repositories cannot be picked.
Step 1: Choose where UIGraph runs
On Where should UIGraph run? pick GitHub Actions.
The other choice, Start with a coding agent, hands the same job to Claude Code or Cursor on your own machine. That route is covered in Onboard a repo with the UiGraph skill.
Step 2: Connect the account that owns your code
Select Install GitHub App. GitHub opens in a new tab and returns to UIGraph once the install finishes.
UIGraph never asks for your password. Remove the app on GitHub whenever you want to revoke access, or use Disconnect next to the connected account.
Step 3: Pick the repository
Start with one repository. UIGraph documents it end to end, then you can bring in the rest.
Search by name. Each row shows the default branch, and private and archived repositories are marked.
Step 4: Add the values the run needs
UIGraph checks the Actions secrets and variables on the repository, and on the GitHub organization that owns it. Go ahead appears once everything is in place.
| Value | Where it goes | What it is |
|---|---|---|
AI_PROVIDER_API_KEY | Secret | The key the workflow uses to call your model provider. |
AI_PROVIDER_MODEL | Secret or variable | The model that reads the repository. |
AI_PROVIDER_API_URL or AI_PROVIDER_NPM | Secret or variable | Either one. The provider endpoint, or its npm package. |
AI_PROVIDER_API_KEY has to be a secret. The other values can be a secret or a variable, set on the repository or on the GitHub organization. See AI Providers for what to put in them.
Use Open GitHub settings to jump straight to the Actions secrets page, add what is missing, then refresh the check.
UIGRAPH_API_URL, UIGRAPH_GATEWAY_URL, and UIGRAPH_TOKEN are written to the repository when the run starts, so there is nothing for you to add. If you already set any of them yourself, UIGraph leaves yours alone.
Step 5: Watch the run
The run page follows along and refreshes on its own. You can leave it open or come back to it.
| Phase | What is happening |
|---|---|
| Creating Branch | UIGraph opens a branch of its own to work on. |
| Preparing | GitHub starts a fresh machine and puts your repository on it. |
| Installing | The tools that read your repository go into place. |
| Generating | Your pages, components, and API calls are read to work out how they connect. |
| Wrapping Up | What was found is checked and saved back to your repository. |
| Uploading to UIGraph | Your graph is sent to UIGraph and put together. |
| Finishing Up | The last checks run. |
Generating is the longest phase and normally takes a few minutes. When the run completes, UIGraph opens the service on the graph.
What lands in your repository
Everything is committed to a branch named uigraph/onboarding/.... Your default branch is left alone, and a pull request opens once the run finishes.
.uigraph.yamlat the root, seeded with your organization, the service name, the repository URL, and the owning team- the generated artifacts under
.uigraph/ .github/workflows/uigraph-onboarding.yml.github/workflows/uigraph-artifact.yml.github/workflows/uigraph-sync.yml
Nothing outside .uigraph.yaml and .uigraph/ is written. If the run touches anything else it stops instead of committing.
Review the pull request the same way you would any other change, then merge it.
Keeping it up to date
Once the pull request is merged, the two remaining workflows take over.
UiGraph Sync runs on every push to your default branch that touches .uigraph.yaml or .uigraph/. It installs uigraph-cli and pushes the artifacts to UIGraph.
UiGraph Artifact Update runs on every other push to your default branch. It reads what changed, updates the artifacts the change made wrong, and opens a pull request called UiGraph: update repository artifacts. It ignores pushes that only touch .uigraph.yaml, .uigraph/, or the UIGraph workflows, so it never chases its own output.
Both workflows use the same values you set in step 4.
When something goes wrong
The run page names the phase that failed and offers Retry run. Open the run log takes you to the GitHub Actions run for the full output.
| Phase that failed | What to check |
|---|---|
| Creating Branch | UIGraph is still connected and allowed to write to this repository. |
| Preparing | GitHub Actions is enabled on this repository. |
| Installing | Usually temporary. A retry often clears it. |
| Generating | Your AI provider settings. |
| Wrapping Up | UIGraph can write to this repository. |
| Uploading to UIGraph | This repository's UIGraph connection. |
| Finishing Up | Open the run log to see what happened. |
If a value from step 4 is still missing, the run waits instead of failing and tells you which one. Add it on GitHub, then select Recheck.
Troubleshooting goes through every step and what it can stop on.