Install access

Every project has an install-access mode that controls who can reach its install URLs.

Modes

• Public: anyone with a buildtree install URL can install the build. Default for new projects. Available on all plans, including Free.
• Private: testers verify their email before the install buttons appear. You add allowed emails (or domain wildcards) on the project. Available on Solo and above.

Set the mode from the project's Install access page.

How Private mode works

When a project is set to Private:

1. A tester opens an install URL or scans the QR code.
2. Instead of install buttons, the page shows an email input.
3. They enter their email and tap Send me a link.
4. If the email is recognised (see below), buildtree sends a one-time link valid for 30 minutes.
5. They open the link on the same device. We set a signed cookie carrying the grant (30 days).
6. The install page reloads and the install buttons appear.

The cookie covers all install URLs for that project (pinned, folder, release). Switching projects re-runs the verification.

What "recognised" means

An email gets a magic link if either of the following is true:

• The email matches an entry in the project's allowlist (literal or domain wildcard).
• The email belongs to a buildtree account that is a member of the project's organisation. This lets project owners and teammates install their own app in private windows without adding themselves to the allowlist.

For everything else, the request silently returns success but no email is sent. The shape of the response is identical, so the gate doesn't leak which addresses are recognised.

Logged-in org members skip the gate entirely

If the visitor is already signed in to the buildtree dashboard and is a member of the project's organisation, the install page recognises them via session and renders install buttons immediately, with no email step. The cookie grant flow is only for testers (or org members in incognito windows).

Allowlist patterns

Two pattern shapes are supported:

• Literal email: you@yourcompany.com matches that exact address.
• Domain wildcard: *@yourcompany.com matches anyone with @yourcompany.com as their email domain. Useful for whole-team access.

Paste a multiline list to add many at once:

you@yourcompany.com
teammate@yourcompany.com
*@dev.yourcompany.com

Patterns are stored lowercase; case doesn't matter on either side.

Always public

Once a project is Private, you may still want some builds to be publicly installable. Typical cases:

• A public beta branch that anyone can install.
• A release tag like v1.0 shared on social media.
• An uat checkpoint for external partners.

An always-public entry is an (environment, branch) pair. Builds whose environment and branch match an entry bypass email verification and render install buttons immediately. Always-public builds surface a green Public badge on the install page so testers see they didn't need to sign in.

branch = null (the env's branchless checkpoint) is a valid target — useful for "the latest uat build is always public" workflows.

Adding an always-public entry doesn't touch your allowlist. Email verification stays in effect for every other (env, branch) combination.

What about release URLs?

A release URL (/install/release/<project>/<tag>) follows the verification setting of the build it serves. If that build's env+branch is in your always-public list, the release URL is public. Otherwise it requires email verification.

To make v1.0 public on a Private project: add an always-public entry for the env+branch where v1.0 was uploaded. Or set the whole project to Public.

Audit trail

Every successful email verification logs the (project, email) grant. We don't surface this in the UI yet; for now, the install_grant_request table holds the data if you need to investigate access. A "who installed what when" feed is on the polish queue.

When to use what