Skip to content

Getting started

This page takes you from "I just signed up" to "my testers can install the build". Budget about fifteen minutes.

1. Create your account

Sign up in the AppGantry web app with your name, email, and a password of at least 10 characters. You'll receive a verification email; click the link to activate the account.

The account is yours personally and travels with you between organizations. Until your email is verified, state-changing actions are refused; you can resend the verification email from the Check your email page or from Account settings.

Once you're in, consider turning on two-factor authentication or a passkey before you invite anyone else.

2. Create an organization

Every build, tester, and project lives inside an organization. It is the billing and membership boundary: your invoice, your members, your audit log, and your storage backend are all per organization.

The creation flow asks you to pick a plan first:

  • Team is the self-serve plan. You can either start a free trial (no card, time-limited, with usage caps and a small starter credit) or choose pay now to activate immediately.
  • Business adds SSO, longer default retention, and BYOSA. It only appears in the picker when Business self-serve signup is switched on for your account; if you don't see it, contact us.
  • Enterprise is not generally available: it is not in the plan picker, and it is not something you can arrange by contacting sales either. Register interest if you want to hear when it is.

See Plans & pricing for what each plan covers and Feature availability for what can be turned off in a given environment.

You can be in more than one organization

A developer account can belong to 5 organizations, a limit also shown on your Account settings page and listed under Feature limits. A consultancy typically runs one organization per client.

3. Create a project

Inside the organization, create a project for each app you distribute. A project targets one platform, and that choice is fixed after creation, so create separate projects for your iOS and Android apps.

The project name shows up in install links and tester invitations, so a clear name like "Acme iOS" beats the bundle identifier.

4. Upload your first build

Open the project and choose Upload build. Fill in the build number, version name, and (optionally) release notes, then pick your artifact:

Platform family Artifact Install path
Apple (iOS, tvOS, watchOS, visionOS) signed .ipa Over-the-air install; AppGantry generates the manifest
Android (phone/tablet, Wear OS) .apk Direct download and sideload install

.aab App Bundles are a Play Store publishing format rather than a directly installable artifact, so they are rejected at upload. Upload an .apk for AppGantry tester distribution, and publish store releases through the Google Play Console directly — publishing from AppGantry is not operational.

For Apple ad-hoc distribution, each test device's UDID has to be in the provisioning profile you signed with. See Enrolling test devices.

How the upload works

Uploads are two-phase, in the web app and over the API alike:

  1. The client asks AppGantry to initiate an upload and gets back a short-lived signed URL plus a pending-upload identifier.
  2. The client PUTs the bytes directly to that signed URL, so the artifact never streams through the API. Because that URL addresses Azure Blob Storage, the PUT must carry x-ms-blob-type: BlockBlob and must not carry an AppGantry Authorization header.
  3. The client completes the upload, reporting the SHA-256 it computed while streaming. AppGantry verifies the stored size and records the checksum as the build's integrity fingerprint, then promotes the pending row into a real build.

The signed URL and the pending upload both expire after 1 hour, a build artifact may be up to 500 MiB, and a project may hold at most 25 pending uploads at once. Those three, and every other ceiling, are owned by Errors → Feature limits and Authentication → Lifetimes. Abandoned pending uploads are swept up automatically, so a failed attempt doesn't leave anything behind.

The canonical description of this contract — including the exact initiate payload — is Uploading a build. Request and response shapes are in the interactive API reference, and a working example is in the CI guide.

5. Invite your testers

You can grant tester access at three levels: organization-wide, per-project, or per-channel. The fastest route for a first build is to add a tester to the project and let them install from the tester portal.

Invite your testers walks through all three, what your tester receives at each level, and the anonymous public install link. Tester groups are in Managing testers & groups.

6. (Optional) Set up a channel

A channel is a named distribution stream (Internal, Beta, Production). You publish a build into a channel as a release, and testers subscribe to the channel rather than to individual builds. Then a new release reaches everyone on that channel automatically, and you get rollback, mandatory updates, and per-release analytics.

A channel is also what the in-app updates SDK subscribes to: you create an SDK app on a channel, ship its app key in your binary, and the app checks that channel for a newer release from inside itself. If you want your testers to stop opening the tester portal to find out there is a new build, that is the next thing to set up.

See Channels & releases.

7. (Optional) Wire up CI

Most teams stop logging into the web app to upload builds after the first week. From CI you'll:

  1. Create a project access token with the Read + Download + Upload role.
  2. Run the two-phase upload against POST /api/v1/builds/initiate, the returned signed URL, and POST /api/v1/builds/{pending_upload_id}/complete.

The full recipe, including a working GitHub Actions job, is in CI with project access tokens.