Getting startedQuickstart
Deploy your first project
From a new account to a live site in a few minutes. You sign up, connect GitHub, GitLab or Bitbucket, import a repository and deploy it to its own address on theorbits.app.
Orbits builds your code and runs it in Abuja. Connect a Git repository once, and every push after that deploys on its own. This page takes you from nothing to a live URL.
1. Sign up
Go to orbits.africa/signup. There are two ways in:
- With your email. Enter your full name and work email and press Create account. Orbits emails you a sign-in link: open the email from Orbits and click Sign in to Orbits. The link works once and expires in 15 minutes. If it has expired, ask for another from the same page.
- With GitHub, GitLab or Bitbucket. Pick the provider, approve Orbits on its consent screen, and you come straight back signed in. Orbits needs a verified email address on the provider account. If that email already has an Orbits account, the provider is linked to it rather than making a second account.
There is no password. Next time, sign in at orbits.africa/login the same way: Continue with email, or the provider you used.
If your account has two-factor authentication on, Orbits asks for a code from your authenticator app after the link or provider step. See security.
2. Create your team
Everything in Orbits belongs to a team: projects, domains, variables and billing. On Create your team, give it a Team name and a Team URL (the part after orbits.africa/). You can invite teammates by email now under Invite teammates, or later from Members. Then press Create team.
Read more about teams, roles and the rest of the vocabulary in concepts.
3. Connect a Git provider
Open New project. The Import a Git repository step has a tab for each provider. Pick yours and press Continue to GitHub (or Continue to GitLab, Continue to Bitbucket).
Orbits uses a GitHub App. On GitHub, pick the account or organisation and which repositories Orbits can see, then you come back to Orbits. You can change the repository list later on GitHub; the GitHub integration page links to it as Change on GitHub.
Orbits connects to GitLab.com with your OAuth consent, asking for the api and read_repository scopes. It lists the GitLab projects where you are Maintainer or above, because it needs to add a webhook to the one you import.
Orbits connects to Bitbucket Cloud with your OAuth consent. It lists the repositories you administer, in every workspace you belong to.
Only team owners and admins can connect a provider. Self-managed GitLab is not available yet. For details on each provider, see deploying from Git.
4. Import a repository
The list shows the repositories Orbits can see, newest push first, each with the framework Orbits detected. Press Import next to the one you want. A repository already used by a project says so and offers to open it.
If a repository is missing, its provider connection can't see it: on GitHub, add it to the App's repository access.
5. Configure
The Configure step is filled in from the repository. Orbits reads package.json and the lock file, says what it found ("Detected from package.json and the lock file"), and you change anything that looks wrong.
| Field | What it is |
|---|---|
| Name | The project's name. It also becomes its address, shown under Address: <name>.theorbits.app. The address is unique across Orbits, so a taken name asks for another. |
| Region | Abuja (abj-1), the only region. See region. |
| Production branch | Pushes here go to production; other branches get previews. It starts as the repository's default branch. |
| Root directory | Where the app lives in the repository. ./ is the root. |
| Framework | What Orbits detected, or pick one. See frameworks. |
| Install command, Build command, Output directory | Prefilled from the detection. Leave them as they are unless your build needs something different. See build settings. |
| Environment variables | Variables the app needs, used by Production and Preview. Add them one by one, or press Import .env to read a .env file. You can change them later. |
Monorepos
When the repository root holds several apps (a Turborepo, Nx, Lerna, Rush, pnpm or npm, Yarn or Bun workspaces, or plain folders such as web/ beside server/), Orbits lists the apps it found under App and waits for you to pick one. Picking an app sets the root directory and reads that app's settings. If yours isn't listed, edit the root directory by hand. Import the same repository again, with another root directory, for each app you want to deploy.
In a monorepo every push builds every project made from the repository, even a push that only changes another app. To skip those builds, set Skip a build when in the project's settings afterwards (ignored build step).
6. Deploy
Press Deploy. The page follows the build as it happens: Queued, Cloning repository, Installing packages, Building, Uploading and Going live, with the build log underneath. You can leave the page; the build keeps running and shows up under Deployments. Cancel deployment stops it, and nothing goes live.
If the build fails, the page says what went wrong and where, and nothing went live. Fix the code or the settings and push again, or redeploy from the project.
When it's ready, the page shows your production address:
$ curl -I https://storefront.theorbits.appHTTP/2 200Every project gets https://<project>.theorbits.app for free, with a certificate. A few seconds after the deployment is live, Orbits takes a screenshot of the home page for the project card.
What happens on each push
From now on you don't need the dashboard to deploy:
- A push to the production branch builds a new production deployment. Production keeps serving the current one until the new build is ready, then switches over.
- A push to any other branch builds a preview, with its own address. See previews.
- On GitHub, GitLab and Bitbucket, each commit shows a status,
Orbits – <project>: pending while it builds, then passed or failed.
You can turn deploy-on-push and previews off in the project's settings under Git.
Next steps
Add your own domain
Serve the project on a domain you own, with a certificate Orbits issues and renews.
Read guide
Set environment variables
Keys and secrets per environment, encrypted, and how to apply a change.
Read guide
Work with deployments
Promote a preview, roll back production, redeploy, and read build logs.
Read guide
Deploy without Git
Send a folder from your machine with the CLI.
Read guide