🚚 Shipping Teams Apps Across Environments With the Teams Toolkit CLI in CI

The Teams Toolkit is almost always demonstrated as a VS Code experience: click Provision, click Deploy, click Publish, watch it light up. That’s a fine way to learn, and a terrible way to run a release. The moment two people are shipping the same app, or you need to promote a tested build from staging to production without surprises, the clicking has to go. Underneath the VS Code buttons is a CLI — teamsapp — and a declarative lifecycle file, and those are what let you run the whole thing in CI with no portal clicks. This post is about wiring that up properly.

The lifecycle file is the contract

Everything centers on teamsapp.yaml, which defines three lifecycle stages — provision, deploy, and publish — as ordered lists of actions. Provision creates cloud resources and the app registration; deploy pushes your code; publish puts the package into an app catalog. Each stage reads from environment variables, which is the hook that makes multi-environment delivery possible.

# teamsapp.yaml (skeleton)
provision:
  - uses: aadApp/create
    with:
      name: ops-assistant-${{TEAMSFX_ENV}}
    writeToEnvironmentFile:
      clientId: AAD_APP_CLIENT_ID
      objectId: AAD_APP_OBJECT_ID
  - uses: teamsApp/create
    with:
      name: ops-assistant-${{TEAMSFX_ENV}}
deploy:
  - uses: azureAppService/zipDeploy
    with:
      artifactFolder: dist
publish:
  - uses: teamsApp/publishAppPackage
    with:
      appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip

Notice ${{TEAMSFX_ENV}} woven through the names. That single variable is what keeps dev, staging, and prod from colliding — each environment gets its own app registration and its own named resources, with no branching in the file itself.

Per-environment .env files

The toolkit reads .env.{environment} files, so you keep one per environment and let the lifecycle resolve placeholders at runtime:

# env/.env.staging
TEAMSFX_ENV=staging
AZURE_SUBSCRIPTION_ID=...
BOT_DOMAIN=ops-staging.example.com

# env/.env.prod
TEAMSFX_ENV=prod
AZURE_SUBSCRIPTION_ID=...
BOT_DOMAIN=ops.example.com

Critically, secrets do not go in these files when they’re committed. The client secret or federated credential lives in your CI secret store and is injected as an environment variable at runtime. Anything sensitive in .env.* files goes in the .env.{env}.user variant that’s gitignored, or stays entirely in CI secrets.

Non-interactive auth is the real unlock

The single biggest difference between the VS Code flow and a CI flow is authentication. Locally, the toolkit pops a browser login. In CI there’s no browser, so you authenticate with a service principal (or, better, a federated credential / OIDC token from your CI provider) and pass it through environment variables the CLI understands:

export TEAMSAPP_M365_USERNAME=        # unused for SP auth
export AZURE_TENANT_ID=$TENANT_ID
export AZURE_CLIENT_ID=$SP_CLIENT_ID
export AZURE_CLIENT_SECRET=$SP_SECRET # from CI secret store, never committed

npx teamsapp provision --env staging --interactive false

The --interactive false flag is what stops the CLI from trying to open a login prompt and hanging your pipeline forever. Confirm the exact variable names and auth options against the current Teams Toolkit CLI docs when you set this up — the auth surface evolves, and this is precisely the kind of detail worth checking against the source rather than trusting a snippet.

Validate as a hard gate

Before deploy, run validation and fail the pipeline on any error. A malformed manifest that sideloads fine in dev can be rejected at publish time, and you want to catch that in CI, not in front of an admin reviewer.

npx teamsapp validate --env staging --interactive false

Treat a non-zero exit here as a stop. Manifest validation is cheap and the failures it catches — a bad icon size, an unsupported capability combination, a malformed deep link — are exactly the ones that are embarrassing to discover after a release goes out.

Promote, don’t rebuild

Here’s the principle that makes multi-environment delivery trustworthy: build the app package once, then carry that same artifact forward through staging and prod, swapping only the environment-specific manifest values. If you rebuild from source per environment, prod gets a different artifact than the one staging validated, and “it worked in staging” stops meaning anything.

A pipeline that respects this looks like:

build        -> produce appPackage.zip + dist (once)
provision:staging / deploy:staging / validate:staging
test against staging
publish:staging  (org catalog)
provision:prod / deploy:prod        (same dist artifact)
publish:prod     (gated by manual approval)

The deploy steps re-point resources per environment, but the code artifact is the one you already tested. Manifest values like the bot domain and client id come from the .env.prod placeholders, not from a rebuild.

I usually have an AI assistant draft the first version of the pipeline YAML from a description of my environments, then verify it against the toolkit docs:

Prompt: “Write a CI pipeline that runs teamsapp provision, validate, deploy, and publish for staging and prod environments, using service-principal auth with —interactive false, validating as a hard gate, and reusing one built artifact across both environments.”

Output (excerpt): A pipeline with a single build job producing the package, separate staging and prod deploy jobs that consume that artifact, teamsapp validate as a required step before each deploy, SP credentials sourced from secrets, and a manual-approval gate before the prod publish.

The model gets the stage structure and the promote-don’t-rebuild flow right; what I verify is the exact CLI flags and the auth variable names, because those are the parts that fail silently if they drift from the current toolkit version.

The approval you can’t automate away

For org-catalog publishing, many tenants require an admin to approve the app before it goes live. Don’t fight that — surface it as an explicit manual approval gate in the pipeline before the prod publish step, and keep the previous app package versioned so you can re-publish the last-good manifest if a release regresses. Automation that respects the human gate is the kind that gets adopted; automation that tries to bypass org governance is the kind that gets banned.

Where this fits

A CI-driven Teams Toolkit pipeline turns app delivery from a sequence of clicks into a reproducible, auditable release you can defend in a change review. For the surrounding manifest and app-catalog patterns, the Microsoft Teams category has the related guides, and the prompts library includes a teamsapp.yaml lifecycle prompt and a CI-pipeline prompt you can adapt so you’re not assembling the lifecycle from scratch. Build once, promote the same artifact, validate as a gate, authenticate with a service principal, and keep the admin approval explicit — that’s the recipe for shipping Teams apps like the production software they are.