Connect a repo
TruStacks works against two kinds of repository. It reads your service repos and opens pull requests into one platform repo, the GitOps repo your ArgoCD watches. This page explains what you grant when you connect them. For the click-through, see the hosted quickstart.
Before you connect
- Create an Application first. Every repo belongs to an Application, and
the connect wizard refuses to start without one (“Create an Application
first”). Create it under Applications: a name, at least one target
cluster with a tier (
dev,uat, orprod), and a renderer (Helm or Kustomize). - Install the runner. Analyses and proposals run in your runner. See the runner Helm chart.
The two roles
| Role | What it holds | What TruStacks does with it |
|---|---|---|
| Service | Your application code | The Code Reviewer clones and reads it. TruStacks never commits to it. |
| Platform | Your GitOps tree: gitops/, argo-apps/, .github/workflows/, and environment-profile.yaml | The DevOps Engineer opens pull requests here. |
Generated delivery files never land in your service repo. The one file you add there yourself is a short caller workflow that runs the pipeline stored in the platform repo. See Platform repo layout.
Two rules shape how repos map to Applications:
- A service is a repo. One repository is one service. A monorepo with several deployable services connects as one service today; per-path services inside one repo are not supported yet.
- A repo belongs to exactly one Application. Connecting a repo that is already a member of another Application is refused.
The TruStacks GitHub App
You connect through a single shared GitHub App. You do not register an app, create OAuth credentials, or paste tokens.
- Go to Services and click + Connect repo (or type
/discoverin the Workspace chat). - Pick the role (Service or Platform), then GitHub.
- Click Install on GitHub. Choose Only select repositories and pick the repos you are connecting. All repositories works but grants the app every repo in the org, present and future.
- Back in TruStacks, pick the repo, the Application, and a name.
Repeat once per repo. You can change the grant later from your org’s Settings → GitHub Apps → TruStacks → Configure.
What the app is allowed to do
The app requests these repository permissions, and they apply to every repo in the installation grant:
| Permission | Access | Why |
|---|---|---|
| Contents | Read and write | Clone repos; push the proposal branch to the platform repo |
| Workflows | Read and write | Proposals add files under .github/workflows/ in the platform repo |
| Pull requests | Read and write | Open the proposal PR; poll whether it merged |
| Metadata | Read | Required by GitHub for every app |
“Read-only” for a service repo is a TruStacks setting, not a GitHub permission. TruStacks never writes to a repo bound as a service, but GitHub grants the app the same permissions on every repo you select. If you need a hard guarantee, keep service repos out of the installation grant you use for write, or enforce it with branch protection.
TruStacks never merges. Require approvals on the platform repo with branch protection or a ruleset, and leave the TruStacks app out of the bypass list.
Providers. GitHub, through the TruStacks GitHub App, is the only provider for hosted workspaces. Local development uses an in-cluster Gitea. GitLab and Azure DevOps are not connectable yet.
What crosses the network
- The runner clones and reads your code inside your cluster. It uses a GitHub App installation token that the control plane mints, valid for about an hour and sealed to your runner.
- The control plane reads one file directly:
environment-profile.yamlfrom the platform repo root, through the GitHub API. - Analysis results, generated artifacts, and verdicts flow back to the control plane. Your repository is not uploaded.
- The pull request goes through GitHub, opened by the runner.
The file contents the agents read are sent to your LLM provider under your key. See Architecture.
Troubleshooting
- “Create an Application first” · create one under Applications, then reconnect.
- The repo isn’t in the picker · add it to the app’s installation grant under your org’s GitHub App settings. A newly created platform repo is the usual miss.
- No pull request after “Promote to proposal” · open the proposal and read the timeline. A failed artifact check or a policy denial stops the run before any PR exists, and says which check or rule. Also confirm the Application has a platform repo bound.
- The first pipeline run fails with
workflow was not found· your platform repo is private and has not shared its workflows. See Platform repo layout.
Where to go next
- Platform repo layout · what lands where, and the caller workflow
- Proposal lifecycle · from analysis to deploy
- GitOps integration · pointing your ArgoCD at the platform repo
- Environment profile · declare what you run