Managing testers & groups¶
Testers are the people who install your builds. This guide covers granting access, organizing it at scale, and taking it away.
Before you start: managing organization-level testers and tester groups needs the organization Admin role. Project-level grants, and listing or removing a direct channel grant, need project Admin — or an organization Manager or Admin, whose access reaches every project. Channel invitations are the lighter case: they need Manage Testers on the project, which a Maintainer holds. When you're done you will know which grant level to use, how to run groups instead of one-by-one invitations, how long each kind of invitation lasts, and how to take access away.
Canonical page
This page is the canonical owner of tester access: grant levels, groups, invitation lifetimes, and revocation. Invite your testers is the first-run version and links here for the detail; if the two ever disagree, this page wins.
The three grant levels¶
A tester's access is a grant, attached at one of three levels:
| Grant | Reaches | Use it for |
|---|---|---|
| Organization | Every channel in every project | Your own team, QA, leadership |
| Project | Every channel in one project | People who work on one app |
| Channel | One channel | External testers, betas, clients |
Grants are additive, and a tester's channel list shows how each one was granted, so you always know which grant to remove.
Prefer the narrowest grant that works. An organization grant on a consultancy account is how a client ends up seeing another client's unreleased app.
Who can grant what¶
The role differs by level, and at the channel level it differs between handing out an invitation and managing the grants themselves. Minting and revoking an invitation are writes; listing the pending ones is a read on the same role, which is why they are separate rows:
| Action | Needs |
|---|---|
| Add or remove an organization tester, and anything to do with tester groups | Organization Admin |
| Add or remove a project tester | Project Admin |
| List or remove a direct channel grant | Project Admin |
| Mint or revoke a channel invitation | Manage Testers on the project, which a Maintainer holds. Over the API a personal access token also needs the manage_testers scope |
| List a channel's pending invitations | The same Manage Testers role, but it is a read-only call: a Read-scoped personal access token is enough |
An organization Manager or Admin satisfies the project-level rows without a per-project membership, because their access already reaches every project in the organization. A project Maintainer can invite someone to a channel but cannot add a project-level tester or remove a channel grant; that is deliberate, because those two reach further than the invitation does. See Authorization.
Organization members are a different object, and none of these rows covers them: inviting a teammate, resending or revoking that invitation, changing a role, and removing a member are all organization Admin work. See Organizations & members.
Inviting an individual tester¶
The level you invite at decides what actually happens, so the two flows are documented separately below. An organization or project grant is attached to an email address by AppGantry, with nothing for the recipient to click. A channel invitation is a short-lived link the recipient has to open and accept.
Inviting an organization or project tester¶
From the organization's or project's Testers page:
- Enter the email address.
- Send.
What happens next depends on whether that address already has an AppGantry account:
- It does. The grant attaches immediately. The tester is active from that moment and the app appears in their tester portal; there is nothing for them to accept.
- It doesn't. The entry becomes a pending tester grant, which never expires. It attaches on its own as soon as somebody signs up with that address and verifies it.
Any AppGantry account counts as one here, verified or not: what makes an entry pending is that no account at all holds the address at the moment you add it. Add somebody who has signed up but not verified their email and the grant attaches straight away — verifying is what lets them sign in and use it. An entry that is already pending is the other case: it waits, and the verification is what attaches it.
Neither case emails a link or a token. The message says the person has been added and points them at AppGantry; the grant is bound to the address itself, which is also why signing up with a different address shows them nothing.
Pending organization and project testers appear in the same list as active ones, with a Pending badge in the status column and Resend and Cancel buttons in place of the active row's View and Remove. Pending testers are not listed in a separate section, so there is no second list to look in. Resending is the fix for a lost email.
Resending a pending organization or project entry is throttled to about once every 5 minutes. Over the API that shows up as a 429; a 404 means there is no pending entry with that identifier, because it never existed, has already attached, or has been cancelled. Those three cases are deliberately indistinguishable from each other, so the endpoint cannot be used to probe who has an account. The 429 and the 404 are not: a 429 tells you the entry is there and was sent too recently — the window starts at the last send, and the notification that went out when you added them counts as one.
Inviting a channel tester¶
A channel invitation is a different mechanism, and whether the recipient already has an account makes no difference to it. From the channel's Testers section:
- Enter the email address.
- Send.
AppGantry always mints a single-use invitation link that expires in about 10 minutes, and the recipient has to open it and accept while signed in as the invited address. Acceptance is an explicit, authenticated step: opening the interstitial does not consume the invitation, and no access attaches until they accept.
An existing AppGantry account does not shortcut any of that, and an address with no account does not turn into a pending grant that attaches at signup — there is no durable pending entry at channel level at all. Nobody is waiting on the channel for someone who never accepts, so an invitation that goes unaccepted for ten minutes simply expires. Mint another when that happens: a channel invitation is issued afresh rather than re-sent, and nothing throttles issuing the next one.
Invitation lifetimes¶
Three different things get called an invitation, and they expire differently:
| What it is | Lifetime |
|---|---|
| Channel tester invitation — a single-use link to one channel | About 10 minutes. It is a click-now, install-now flow, and it is reissued rather than re-sent |
| Pending organization or project tester grant — added by email at org or project level | No expiry. It waits until the person creates an account and verifies their email, then attaches |
| Organization or project member invitation — a teammate joining with a role | 14 days. A resend (API-only) issues a fresh token and a fresh 14-day window; once the 14 days run out the invitation drops off the pending list, and an hourly sweep then deletes the row |
The 14-day number belongs to the member invitation only. A pending tester is not on a clock: if someone you added months ago finally signs up with that address and verifies it, their grant attaches then. Cancel the pending entry if you no longer want that to happen.
A member invitation is the opposite. When its 14 days run out it drops off the pending list, which shows only invitations that have not expired, and an hourly background sweep then deletes the row. Between those two moments a resend over the API — by an invitation id you already hold — revives it with a fresh token and a fresh 14-day window; the web app cannot, because the row it would act on is no longer listed. After the sweep there is nothing left to resend and the fix is to invite the person again.
If someone says a channel link is dead, mint a fresh invitation rather than debugging it — an expired, used, and unknown token all return the same "not found". There is no resend action on a channel invitation and no cooldown on issuing the next one; the ~5-minute throttle covers pending organization and project entries only. See Organizations & members for member invitations.
Tester groups¶
Inviting forty testers to six channels one at a time is not a plan. A tester group is a named set of testers plus a set of grants:
- Members: testers, and pending testers who haven't signed up yet.
- Grants: any mix of organization, project, and channel grants.
Joining the group confers all of its grants. Leaving removes them. Adding a grant to the group gives it to every member at once.
A layout that works:
| Group | Grants |
|---|---|
| Internal QA | Organization |
| Acme app team | Project: Acme |
| Acme public beta | Channel: Acme → Beta |
| Design review | Channel: Acme → Internal, Channel: Widget → Internal |
Then onboarding a new tester is one action: add them to a group.
Groups can be renamed, edited, and deleted. Deleting a group removes the access it conferred, so check who is in it first.
What testers see¶
Testers get a portal, not the developer app. Dashboard → My apps lists every release available to them, grouped by organization, project, and channel, and each row carries the version, platform, size, release date, whether the update is mandatory, and the install or download action.
My channels is a separate page rather than a section of My apps: View my channels, at the top of My apps, opens it. It lists the channels they can install from and how each grant was made, which is what tells a tester why an app they didn't expect is there.
They can also set a notification preference per channel, from My channels, so someone who wants every nightly build and someone who only wants stable releases can coexist on the same channel.
Testers cannot see your builds list, your members, your audit feed, other testers, or anything about other projects.
Installing¶
The tester opens the install link in Safari, on the device, and taps install. iOS installs the app directly.
The install capability is short-lived (about 15 minutes), so if they leave the page open overnight they need to start again.
Ad-hoc-signed builds only install on devices whose identifier is in the provisioning profile the build was signed with. See Enrolling test devices.
The tester downloads the .apk and opens it. Android will ask them
to allow installs from the browser they used; once allowed, the
install proceeds.
There's no device registration step on Android.
Both flows finish on the device: the itms-services:// hand-off
runs only in Safari on the iPhone or iPad, and the .apk is installed
by Android itself. Neither completes inside a desktop browser.
Starting on a desktop still works, because the install page hands off
with a QR code. Opened where the install cannot finish, the Apple
install page shows a QR of a short-lived, sign-in-free install page: the
tester scans it with the Camera app on the target iPhone or iPad,
and taps install in the Safari page it opens. The QR encodes that page
rather than the itms-services:// link itself, because iOS will not
open one of those from a camera scan, and because the device being
scanned onto has no session. The Android install page does the same with
its download link, so a scan pulls the .apk onto the phone. Tell a
tester to scan with the Camera app rather than a QR-scanner app: a
scanner app's built-in browser is a webview, and neither install runs in
one.
Anonymous install links¶
Making a channel public produces a link that installs the channel's current release with no sign-in at all. That's useful for a public beta, a conference demo, or a client who won't create an account.
Where the link is. Open the channel, tick Public channel under Channel settings, and save. The Public install link appears on that same page once the channel is public, with a copy field next to it. It is not shown while the channel is private, and there is nothing to generate — turning the setting on is what mints it.
It is also exactly as open as it sounds:
- Anyone with the link can install. Links get forwarded.
- Downloads still meter against your organization. Consider a spend cap.
- You get no per-tester attribution, because there is no tester.
Turning the channel private revokes the link immediately.
Removing access¶
| To remove | Do |
|---|---|
| One tester from one channel | Remove the channel grant |
| One tester from a project | Remove the project grant |
| One tester entirely | Remove the organization grant, and any project or channel grants they hold |
| A whole cohort | Remove the tester group, or empty it |
| Everyone, right now | Disable the release, or revoke the build |
Removal takes effect immediately for new installs. It does not uninstall the app from a device that already has it — nothing can — so if a build must not remain in someone's hands, revoke the build and treat the copy they hold as gone.
Troubleshooting¶
| Symptom | Cause | What to do |
|---|---|---|
| Resending is refused with 429 | The same pending organization or project entry was sent to within the last ~5 minutes — the notification sent when you added them starts the window, so an immediate resend is refused too | Wait. Nothing was sent, so the earlier email is still the live one |
| Resending is refused with 404 | There is no pending entry with that identifier — it never existed, it has already attached, or it was cancelled | Re-read the pending list. The three cases answer identically on purpose |
| A tester you added months ago has just appeared as active | Pending tester grants have no expiry, and one attaches when that person signs up with the address you invited and verifies it | Cancel the pending entry if you no longer want that. See Invitation lifetimes |
| A channel invite link is dead | Channel invitations last about 10 minutes and are single-use | Mint another one. There is no resend for a channel invitation, and nothing to diagnose on the old link |
| Someone you invited to a channel already has an account, and still has no access | A channel invitation never attaches by itself. It has to be opened and accepted, account or no account | Mint a fresh invitation and have them accept it, signed in as the invited address, within about 10 minutes |
| A member invitation you sent last month has vanished from the pending list | Member invitations live 14 days; after that they leave the list, and the hourly sweep deletes the row | Invite the person again. Until that sweep runs, a resend by the invitation's id still revives it over the API, but the web app offers no way to reach a row it no longer lists. See Organizations & members |
| There is no resend control on a channel invitation | Only pending organization and project entries have one | Revoke the pending invitation if you want it dead, then mint a fresh link |
| A tester can see an app you didn't grant them | An organization or project grant, or a tester group, reaches further than you meant | Open the tester and read which level granted each channel, then remove that grant |
| A tester can't find the build | They are looking in the developer app rather than Dashboard → My apps | Point them at My apps; testers never see your builds list |
| An Apple install greys out on the home screen | The device's identifier is not in the provisioning profile the build was signed with | Enroll the device, then re-sign and re-upload |
| Deleting a group removed more access than expected | A group's grants are conferred on every member | Check the membership before deleting; grants leave with the group |
| The public install link is missing | The channel is not public | Tick Public channel in the channel's settings and save |
Scaling up¶
- Groups, not individuals. Always.
- Channels are the boundary. Internal, Beta, and Production channels with different tester groups beat one channel with careful invitations.
- Turn off notifications for noisy channels rather than letting testers mute you by ignoring email.
- Review quarterly. Tester lists accumulate.
- Watch download volume. Testers are free; the bytes they download are not. See Plans & pricing.
See also¶
- Inviting testers: the short version.
- Channels & releases: what testers are following.
- Enrolling test devices: Apple ad-hoc distribution.
- First-build troubleshooting: when an install fails.