GitHub connection

Connect GitHub when you want Apso Cloud to deploy the same generated source code your team reviews and owns. The CLI links the local project to an Apso service, completes GitHub authorization in the browser, and pushes the code during deployment.

Prerequisites

An authenticated CLI session
A local project with .apsorc
An Apso workspace and service
Permission to authorize GitHub for that workspace

Connect and deploy

Link the project

Link an existing local project to an existing service:


apso login
apso link --workspace your-team --service project-api

Create the platform service while linking when needed:


apso link --workspace your-team --create project-api

Authorize GitHub


apso github connect

The CLI opens an Apso authorization page and waits for the connection. If the project is not linked, pass the workspace ID explicitly:


apso github connect --workspace-id 123

Validate the generated service


apso schema validate
apso generate
apso migrate

Review and test the generated diff before deployment.

Push and deploy


apso deploy --repo your-org/project-api --branch main

By default, deployment can push the project through the platform GitHub connection. Use local Git credentials instead when your environment already has repository access:


apso deploy --repo your-org/project-api --branch main --local-git

Deployment behavior

Before triggering a build, apso deploy validates migrations and synchronizes local code to the connected repository. Use these controls deliberately:

Flag	Use
`--repo owner/name`	Select a repository when the service has no repository yet.
`--branch name`	Select the push branch. The default is `main`.
`--local-git`	Push with the machine’s Git credentials.
`--skip-push`	Redeploy code that is already synchronized.
`--skip-migrate`	Bypass the local migration check. Reserve this for a diagnosed exception.
`--yes`	Confirm migrations without an interactive prompt.
`--no-wait`	Trigger the build and return before it finishes.

Keep .env, service API keys, and provider secrets out of Git. Commit .apsorc, generated source, migrations, extensions, lockfiles, and tests so another developer can reproduce the service.

Verify the connection


apso status
apso logs
apso open

apso status shows the linked service and latest build. apso logs retrieves build output. apso open opens the service dashboard or endpoint.

Next steps

Review migration, repository, branch, and wait controls

Deploy command

Authenticate the CLI and validate the service in automation

CI/CD