Preview Environments

Preview environments provide a controlled staging lane for pull requests. Each project can have one selected PR for staging at a time.

In the dashboard, choose a PR and click Submit & Deploy:

• TMA.sh validates the PR on GitHub.
• The PR is saved as the project’s staging target.
• A preview deployment is triggered immediately from that PR’s current head commit.

After that, new commits to the selected PR trigger automatic preview redeploys.

URL pattern

Preview deployments are served at:

pr{number}--{project}.tma.sh

For example, pull request #42 on a project called myapp is accessible at:

pr42--myapp.tma.sh

If your project includes API routes, preview API traffic is available at:

pr{number}--{project}--api.tma.sh/*

Lifecycle

A preview environment follows the lifecycle of the selected staging PR:

1. Select PR and submit

From Project Settings → Deployment, choose an open PR (or enter a PR number), then click Submit & Deploy.

Select PR → Submit & Deploy → Deployment created (type: preview)

2. Build

The preview deployment goes through the same build pipeline as production: dependency installation, build execution, output validation, asset upload, and route activation.

3. Bot assignment

Preview deployments can use a Telegram bot registered with environment: 'preview'. This bot is separate from the production bot, so testing interactions in preview does not affect live users.

There is one preview bot per project/environment. The same preview bot is reused across preview deployments, and its menu button URL is updated to the current preview URL (pr{number}--{project}.tma.sh).

4. Selected PR updated

When new commits are pushed to the selected PR branch, the preview deployment is rebuilt automatically. The URL stays the same (pr{number}--{project}.tma.sh) and serves the latest build.

5. Switch staging PR (optional)

If you switch staging from PR A to PR B and submit, PR A’s preview routing is removed immediately. Staging now points to PR B once its deployment is ready.

6. PR closed or merged

When the pull request is closed or merged:

• The KV routing entries for the preview are removed.
• The preview deployments are marked as cleaned.

There is no Telegram API call to deactivate the preview bot — it simply becomes unreachable because the routing entries no longer exist.

If the PR is merged, the production deployment is triggered separately by the push to the default branch.

Preview-scoped secrets

Secrets in TMA.sh are scoped by environment (production, preview, development). In practice, you define separate entries per environment (often reusing the same key name with different values).

This is useful for:

• API keys — Use test/sandbox API keys in preview, production keys in production.
• Database URLs — Point previews at a staging database.
• Feature flags — Enable experimental features only in preview.

Project secrets:
  DATABASE_URL (production) → postgres://prod-db/myapp
  DATABASE_URL (preview)    → postgres://staging-db/myapp
  STRIPE_KEY (production)   → sk_live_...
  STRIPE_KEY (preview)      → sk_test_...

Preview deployments only receive secrets scoped to preview. They never have access to production secrets.

Use cases

QA testing

Share the preview URL and bot with your QA team. They can test the Mini App in a real Telegram environment without affecting production.

Stakeholder review

Non-technical stakeholders can open the preview bot in Telegram and interact with the app directly. No setup, no local environment, no CLI tools required.

Branch experimentation

Run focused staging reviews on one PR at a time. Switch the staging target when you want to review a different branch.

Bot interaction testing

Using a preview bot, you can test bot commands, inline queries, and webhook handlers without affecting the production bot.

Comparison with production

Aspect	Production	Preview
URL	{project}.tma.sh	pr{number}--{project}.tma.sh
Trigger	Push to default branch	Submit selected PR, then PR updates
Bot	Production bot	Optional preview bot (environment: 'preview')
Secrets	Production-scoped	Preview-scoped
Custom domains	Supported	Not supported
Active target	One production deployment	One selected staging PR per project
Cleanup	Active production + latest retained window	Marked cleaned when PR is closed/switched; also subject to retention cleanup
Rollback	Supported	Not applicable

Disabling previews

Set staging PR selection to None in project settings. Pull requests will no longer trigger preview deployments until a PR is selected again.