GitHub and builds

SDK Reference

Deploy on GitHub works with any SDK login: Google, GitHub or another SSO. The first time you connect GitHub, the SDK links your GitHub identity to your current account. It never creates a second account.

On this pageConnect a GitHub repository · Deploy on every push · Inspect builds

Project github and build commands find the project in the same order as deploy. First the [project] argument or --project, then VOID_PROJECT, then the linked project in .void/project.json.

void github link

void github link

Links your signed-in SDK account to GitHub in your browser. void github install does this for you when needed.

Existing GitHub sign-in

A GitHub identity can belong to only one SDK account. If it is linked elsewhere, sign in to that SDK account. Or authorize a different GitHub identity.

void github install

void github install

Opens the GitHub App install page in your browser. If your account has no linked GitHub identity, it first runs the GitHub link in the browser, then continues. After installing, run void github connect to link a repo to your project.

void github installations

void github installations

Lists all GitHub App installations linked to your account. Each entry shows the [id: <installation_id>] that --installation needs in non-interactive use.

void github join

void github join

Joins an existing organization installation in your browser. void github connect can do this for you in an interactive terminal. Before non-interactive setup, run join locally if needed.

It needs a signed-in SDK account. Your platform must also allow organization-installation sharing. Use void github installations to find the installation ID.

void github connect

void github connect [project] [options]

Connects a GitHub repo to an SDK project for automatic deploys. On every push to the chosen branch, the SDK builds and deploys your project.

The CLI opens your browser when it needs GitHub authorization. If no installation is available, run void github install.

Options

Flag	Description
--project <name>	Project name (alias for the positional argument)
--installation <id>	GitHub App installation ID (required when you have multiple installations)
--repo <owner/repo>	Repository full name — required unless the installation grants exactly one repo
--branch <name>	Branch to deploy from — required in non-interactive mode
--executor <type>	Build executor: container (default) or github_actions
--workflow <path>	Authorized deploy workflow file — defaults to .github/workflows/void-deploy.yml

Choose container for platform builds or github_actions for a deploy workflow. The CLI asks for the executor. For GitHub Actions, it also asks for the workflow file. Pass the matching flags to skip those prompts.

The workflow must be a .yml or .yaml file in .github/workflows/. Only that workflow can get the project's OIDC deploy token. Use a workflow just for deploys.

In CI, pass the project and branch. Also pass the installation and repo when they cannot be picked automatically. Organization connections need repo authorization in a local browser first.

void github connect my-app \
  --installation 42 \
  --repo owner/my-app \
  --branch main

You can connect only repositories your GitHub account can access.

A project has one GitHub connection. void github connect fails on a project that is already connected. To use a different repo, run void github disconnect first.

void github update

void github update [project] [options]

Changes the branch, executor or workflow of an existing connection. To change the repo, disconnect and connect again.

Options

Flag	Description
--project <name>	Project name (alias for the positional argument)
--branch <name>	New branch to deploy from
--executor <type>	New build executor: container or github_actions
--workflow <path>	New authorized deploy workflow file (under .github/workflows/)

The CLI asks for new settings and offers the current values as defaults. In CI, pass at least one of --branch, --executor or --workflow.

void github update my-app --executor github_actions

void github status

void github status [project]

Shows the connected repo, branch, executor and workflow. Container builds do not use the workflow file.

Options

Flag	Description
--project <name>	Project name (alias for the positional argument)

void github status my-app

void github disconnect

void github disconnect [project]

Disconnects a project from its GitHub repo and stops automatic deploys. Running builds are cancelled before the connection is removed. If there is no connection, the command says so and exits successfully. To switch repos, disconnect first, then run void github connect.

The CLI asks you to confirm before it removes anything. Pass --yes to skip the prompt. In a non-interactive shell such as CI, --yes is required.

Options

Flag	Description
--project <name>	Project name (alias for the positional argument)
--yes	Skip the confirmation prompt (required in non-interactive shells)

void github disconnect my-app --yes

Build

Use these commands to inspect Deploy-on-GitHub builds.

void build logs

void build logs [build] [--follow] [--output <file>] [--project <slug>]

Streams, tails or downloads the logs of a container build. Without a [build] argument, it uses the project's latest build.

Flag	Purpose	Default
--follow, -f	Live-tail: poll until the build finishes and its final logs are captured.	off
--output <file>, -o	Write logs to a file instead of stdout (appends while following).	stdout
--project <slug>, -p	Target project.	linked

Builds on GitHub Actions keep their logs on GitHub. For those, the command prints the Actions run URL. Only the last 10,000 log lines of a container build are kept.

--follow waits for the platform to confirm the final log tail. If it cannot, upgrade the platform runtime or read the kept logs without --follow. An unfinished final tail reports an error after two minutes. Retry to recover it.

Examples:

void build logs                     # print the latest build's logs
void build logs -f                  # follow the latest build until it finishes
void build logs bld_123 -o build.log  # download a specific build's logs

Next steps

NextCustom DomainsPreviousSecrets and EnvironmentZoneAll SDK Reference pages