Skip to content

BYOSA setup

This guide walks you through configuring AppGantry to store your build artifacts in your own Azure Blob Storage account instead of ours. The platform owns the metadata and audit trail; you own the bytes.

For an overview, see the BYOSA concepts page. BYOSA is most useful when you hit one of: heavy distribution (typically $100+/mo in download metering), a compliance requirement, or a data-residency constraint.

Prerequisites

You need:

  • An Azure tenant where you (or a tenant admin you can reach) can admin-consent applications.
  • An Azure subscription with billing enabled.
  • The Admin role on your AppGantry organization.
  • A Business organization.
  • An interactive AppGantry sign-in. Storage configuration rejects long-lived access tokens.

You don't need:

  • To share a storage account key with us.
  • To share a SAS token with us.
  • To configure a client secret or certificate.
  • To rotate anything on a schedule.

The trust model is secret-less: see Step 1 for how that works, and Security & disclosure for the wider picture.

Overview

Three steps, then a review:

  1. Consent. Admin-consent AppGantry's application into your Azure tenant.
  2. Grant. Create a storage account and container, and give the application permission to write blobs into that container.
  3. Submit. Enter your tenant ID, account URL, and container name in the organization's Storage backend page.

AppGantry then validates the target with live checks and completes the switch with you. Final activation is assisted, by design: switching where an organization's artifacts live is not a self-serve toggle.

Phase 1: Azure side

This creates an enterprise-application entry in your tenant. It carries no credentials. It exists so you can assign it a role on your storage container.

Have a tenant admin visit (replacing {your_tenant_id} with your Microsoft Entra tenant ID):

https://login.microsoftonline.com/{your_tenant_id}/adminconsent?client_id=63c04479-2f32-4a1d-909c-b546d98bc4c8

About that client ID

63c04479-2f32-4a1d-909c-b546d98bc4c8 is the application (client) ID of AppGantry's multi-tenant app, AppGantry BYOSA Access. It is a public identifier, not a secret. If you want to confirm it independently before consenting, check it against the identifiers we publish, or ask support through a channel you initiated.

The admin reviews the permission request and clicks Accept. After this, an enterprise app named AppGantry BYOSA Access appears under Azure Portal → Enterprise applications. Note its object ID; you'll grant a role to it in Step 3.

Tip

If your tenant has a Conditional Access policy that blocks consent, work with your AAD admins to allow it for this single client ID. Admin consent is a one-time event; the policy doesn't need to permit interactive sign-in for this app.

Step 2: create a storage account and container

Standard Azure procedure. Choose:

  • Region: close to where your developers and testers live.
  • Redundancy: LRS is fine for most cases; pick GRS if you need cross-region durability.
  • Performance tier: Standard (Hot access tier).

Then create a container inside the account:

  • Name: must satisfy Azure rules: 3-63 chars, lowercase alphanumeric and hyphens, must start with a letter or digit, no consecutive hyphens, not a reserved name. appgantry-builds is a good choice because support recognises it at a glance, but it's yours to pick.
  • Public access level: Private (no anonymous access). AppGantry mints time-limited signed URLs for every download.
  • Reserve the container for AppGantry. AppGantry writes under its own path scheme and assumes nothing else writes to the container.

Step 3: grant the app the right role

In the storage account's IAM blade:

  1. Navigate to your container (not the account root, ideally).
  2. Access Control (IAM) → Add → Add role assignment.
  3. Role: Storage Blob Data Contributor.
  4. Assign to: User, group, or service principal.
  5. Search for AppGantry BYOSA Access (the enterprise app from Step 1). Select it.
  6. Save.

Container scope, not account scope

Account scope works, and validation will pass against it, but it grants data-plane access to every container in the account. Container scope keeps the blast radius tight.

Reader is not enough

Storage Blob Data Reader allows retrieving blobs but not uploading them; validation fails at the marker-write step with a clear error.

Role propagation takes about 5 minutes. If you submit immediately after granting the role you may see a token-exchange or permission error. Wait and resubmit.

Phase 2: AppGantry side

Step 4: gather your three identifiers

Where to find it
Tenant ID Azure Portal → Microsoft Entra ID → Overview → Tenant ID
Account URL e.g. https://acmebuilds.blob.core.windows.net
Container name The container you created in Step 2

Step 5: submit the onboarding request

In the web app, open your organization → Storage backend, enter the three identifiers, and submit. AppGantry immediately runs live checks against your Azure setup before anything is committed:

  1. Token exchange — verifies admin consent landed and the trust is reachable.
  2. Container existence — verifies the container exists. AppGantry will not create containers in your tenant.
  3. Marker write — writes a small marker blob to verify write permission.
  4. Marker delete — removes the marker to verify delete permission.
  5. Residue check — confirms the marker is really gone, catching soft-delete retention swallowing the purge.

Step 6: watch the request through its states

The Storage backend page shows exactly where your request is:

State What it means What you do
Pending Validating your storage Wait
Validated Checks passed; awaiting review Wait
Approving Your organization is being switched Wait
Approved The switch is completing Wait
Validation failed Something on your Azure side needs fixing Follow the remediation steps and resubmit
Rejected The request was declined, with a reason Address the reason and resubmit

While a request is pending or validated you can withdraw it — useful if you realise you submitted the wrong container.

When validation fails, the page shows a summary, a concrete remediation checklist, and which stage failed. The most common cause by far is Storage Blob Data Reader instead of Contributor, followed by role propagation not having finished yet. Fix and resubmit; the form keeps your input so you're not retyping identifiers.

If the failure is on AppGantry's side rather than yours, the page says so and points you at support.

Failed attempts don't change your storage configuration, so there is no cost to iterating.

Once activation completes, every build upload lands in your container and every download streams through a time-limited signed URL minted against your storage account.

After setup

Verify

The Storage backend page shows your current configuration at any time, and has a Run diagnostics button that re-runs the same live checks end to end. Use it after an Azure change, after an outage, or whenever a download looks wrong. The result is the same summary, remediation, and failure-stage report you saw during onboarding.

Rotating to a different container or account

Contact support with the new identifiers.

Rotation strands existing builds

If you change the container or the account URL and your organization already has builds, those builds' downloads will stop working, because their stored paths point at the previous container. Support will confirm you accept that before proceeding. If you need existing downloads to survive the rotation, the blob data has to be copied between accounts first — support coordinates that.

Changing the tenant ID alone, with the same account and container, moves no bytes.

Teardown

To move back to hosted storage, contact support. Teardown is blocked by default while your organization has live builds, for the same reason rotation is: their downloads would break. You either remove the affected builds first or explicitly accept the breakage.

After teardown, clean up your own tenant:

  1. Azure portal → Enterprise applications → search for AppGantry BYOSA Access.
  2. Properties → Delete.
  3. Optionally remove the role assignment on your container.

AppGantry cannot remove the enterprise app from your tenant for you; it holds no directory permissions there.

Troubleshooting

Validation runs five checks in order — token exchange, container existence, marker write, marker delete, residue check — and the page names the one that failed. That stage is the fastest diagnosis you have, so read it before changing anything.

Failing stage or symptom Cause Fix
Token exchange fails Admin consent hasn't landed in your tenant, or it was granted for a different application Re-run the consent URL in Step 1 as a tenant admin, and confirm AppGantry BYOSA Access appears under Enterprise applications
Consent itself is blocked A Conditional Access policy is refusing consent for this client Have your Entra admins allow that one client ID. Consent is a one-time event and does not need interactive sign-in permitted for the app
Container existence fails The container name is wrong, or it exists in a different account Check the name character for character, and that the account URL matches the account you created it in. AppGantry will not create a container in your tenant
Marker write fails The role assignment is Storage Blob Data Reader, not Contributor. This is the most common failure by a wide margin Reassign as Storage Blob Data Contributor in Step 3
Any stage fails immediately after granting the role Azure role propagation hasn't finished Wait about five minutes and resubmit. The form keeps your identifiers
Marker delete fails The role can write but not delete — a custom role, or a narrower built-in one Use the built-in Storage Blob Data Contributor role rather than a hand-rolled equivalent
Residue check fails Blob soft-delete retention is keeping the marker after the purge Adjust the container's soft-delete policy, or accept it and talk to support before resubmitting
The request is stuck at Pending or Validated Those states are normal: validation is asynchronous, and final activation is assisted rather than instant Wait. If you submitted the wrong container, withdraw the request while it is in either state and start again
The request was Rejected The reason is shown on the page Address it and resubmit
The page says the failure is on AppGantry's side It is; you cannot fix it from Azure Follow the support pointer on the page rather than changing your storage configuration
Downloads break after a container or account change Existing builds' stored paths point at the previous container This is expected — see Rotating to a different container or account. Support coordinates a data copy if the downloads have to survive
Storage configuration is refused with 403 You used a personal or project access token Storage configuration needs an interactive sign-in whatever the scope
There is no BYOSA section at all The organization is not on Business, or you are not an Admin Check the plan and your role. See Feature availability

Failed attempts never change your storage configuration, so iterating costs nothing but time. When a fix isn't obvious, Run diagnostics re-runs the same five checks against your live configuration and reports the same failure stage.

See also