Deploy from a private repo

Private repos deploy like public ones once nyxory can read them. How it reads them depends on where the repo lives:

Where the repo lives	How nyxory reads it
github.com	The nyxory GitHub App: a one-time install in your browser, then short-lived tokens. No deploy key, no PAT.
Any other Git host (GitLab, Bitbucket, self-hosted)	An HTTPS Git connection: a service account’s username and access token, stored once per workspace.
Gerrit connected to your instance	A read account per project: no token at all, the repository owner grants each project in Gerrit.

All three work on every plan.

Prereqs

• An agent connected to nyxory (see Connect your agent)
• For GitHub: admin access to the repo or org you want to connect
• For other hosts: you own the workspace, and you have a service account with read access to the repo

GitHub

1. Just prompt.

   deploy https://github.com/me/private-widget to nyxory

   Your agent calls nyx_brain, then tries the clone. For a public repo that’s the end of the story. For a private one, the clone bounces with an auth error.

2. The agent hands you an install link.

   On the bounce, the agent calls nyx_github_install_url and gives you a signed install URL. The link expires after 10 minutes. If it goes stale, the agent just mints a fresh one; the call is idempotent.

3. Install the app in your browser.

   Open the link, pick the repositories you want nyxory to reach (or select the whole org), click Install. It’s a regular GitHub App: repo-scoped, visible under your GitHub settings, revocable there at any time. You can also start the install from the console: GitHub in the workspace menu.

4. Tell your agent you’re done.

   It retries the clone via nyx_clone_repo. The repo lands in your project workspace and the deploy continues exactly like a public-repo deploy. If several installations cover the same owner, the agent disambiguates with nyx_github_list (installations, then kind: repos).

Builds clone the repo with a short-lived installation token (about an hour) that your Dockerfile never sees. Details in Builds & the execution surface.

Sharing in a workspace. A repo you deploy in a shared workspace is added to the workspace’s shared repositories automatically, so members can deploy it in their projects with your GitHub access. The owner manages that list under Team → Shared repositories and can remove a repo there.

Other Git hosts over HTTPS

For GitLab, Bitbucket, or a self-hosted Git server, the workspace owner connects the repository once in the console:

1. Open GitHub in the workspace menu. With HTTPS connections available, the page is titled Git connections.
2. Under Other Git repositories, click Connect repository and fill in a name, the Repository URL (HTTPS), the Service account username, and its Access token. An expiry date for the token is optional; the console shows it next to the connection.
3. Decide who may use it: Share with workspace lets every member deploy the repo in their projects; otherwise it stays Owner only.
4. Check main verifies the credentials can read the repo before anyone builds from it.

After that, prompt as usual. Your agent clones with nyx_clone_repo, passing the connection’s connection_id, and builds use the saved credentials for their clone step. Set an expiry and rotate the token on your side; nyxory doesn’t shorten its lifetime.

• Sign-in uses the username and the token together; a token alone is not enough. The service account only needs read access.
• The saved token is never displayed again. Edit credentials replaces it, Disable connection stops new builds through it while running apps stay up.
• SSH deploy keys for other hosts are not supported. Use HTTPS with a token.
• Auto-deploy works for these repos too: nyxory checks the watched branch about once a minute and builds each new commit. See Deploy on push.

Note: HTTPS Git connections are on for every workspace on the shared nyxory platform. On a dedicated instance they are switched on per instance.

Gerrit: one read account per project

If your instance is connected to a Gerrit server, the Git connections page names it, and repos there need no token. Instead, every project that uses a Gerrit repository gets its own read-only Gerrit account, which signs in over SSH with a key the console generates. The account can read nothing until the repository owner grants it.

1. Connect the repository. The workspace owner uses Connect repository as above. For a Gerrit URL the form asks only for a name and the URL: no username, no token.
2. Deploy as usual. On the first deploy the clone is refused: the agent reports the project’s account and a link to the repository’s access settings in Gerrit.
3. Grant it. The repository owner opens the link and, under Access, grants Read on refs/* to the group with the account’s name.
4. Clone again. Tell your agent it’s granted; it retries nyx_clone_repo and the deploy continues.

Once auto-deploy is set up for the app, its Auto-deploy panel shows the same state: Waiting for approval with the account and an Open access in Gerrit link, then Reads over SSH as the project’s account. A grant made while the panel waits is picked up within a minute, without asking the agent.

Because each project has its own account, granting one project a repository never opens it to another project, in the same workspace or elsewhere. See Projects & accounts.

Managing access

which GitHub accounts are connected to nyxory?

Your agent lists them via nyx_github_list. Revoking is a person’s call, not your agent’s:

• From the console: GitHub in the workspace menu lists the installations connected through nyxory, with a disconnect action per installation.
• From GitHub: Settings → Applications → Installed GitHub Apps → nyxory → Uninstall. Same effect.

After any of these, no new tokens can be minted for that installation. Outstanding short-lived tokens age out within the hour.

For HTTPS connections, Disable connection on the Git connections page is the revoke. For Gerrit, the repository owner removes the group’s Read grant in Gerrit.

Troubleshooting

Caution:

1. The install link 404s or errors. It expired (10-minute window). Ask your agent for a fresh one: nyx_github_install_url re-signs on every call.
2. Installed, but the clone still fails. Check the repo was actually included in the installation: ask your agent to run nyx_github_list with kind: repos for the installation. The repo’s full_name must appear there. If you picked “selected repositories” during install, add the missing repo from GitHub’s app settings.
3. Multiple orgs, wrong account. The install link binds to whichever GitHub account you’re logged into. Log into the right account (or use the org picker on GitHub’s install screen) and re-open a fresh link.
4. Org requires approval. In orgs where you’re not an admin, GitHub queues the install as a request. The clone succeeds as soon as an org admin approves the request. That approval lives on GitHub’s side, so nudge the admin rather than re-running the install.
5. HTTPS connection shows “Access failed” or “Credentials expired”. The token was revoked, expired, or lacks read access. Edit credentials with a fresh token, then Check main again.
6. Gerrit clone still refused, or the panel stays on “Waiting for approval”. The grant is missing or went to the wrong group. The group name is exactly the account name in the error or on the panel.
7. Still stuck? Ask your agent for the exact clone error and the output of nyx_github_list. That pair is what we’ll ask for in support.

Next steps

• Deploy a Next.js app: the full deploy walk-through
• Deploy on push: redeploy on every commit to the watched branch
• Builds & the execution surface: where the build token story comes from