🐞 `teamsApp/create` wiki documents `teamsAppTenantId` as a `writeToEnvironmentFile` output, but the v1.10/v1.11 YAML schemas do not permit it

[andrewconnell]

Describe the bug

The official ATK wiki documents teamsApp/create as writing both teamsAppId and teamsAppTenantId to the environment file via writeToEnvironmentFile:

writeToEnvironmentFile outputs:

• teamsAppId: The ID of the created or verified Teams app
• teamsAppTenantId: The tenant ID associated with the Teams app

Source: https://github.com/OfficeDev/microsoft-365-agents-toolkit/wiki/Available-actions-in-Microsoft-365-Agents-Toolkit#teamsappcreate

But the YAML schemas for v1.10 and v1.11 only permit teamsAppId. Adding teamsAppTenantId: SOME_VAR to a teamsApp/create action's writeToEnvironmentFile causes the VS Code YAML language server to flag it as an invalid property.

Schema source (v1.11): https://developer.microsoft.com/json-schemas/teams-toolkit/teamsapp-yaml/v1.11/yaml.schema.json

Relevant snippet from the schema:

"teamsApp/create": {
  "properties": {
    "writeToEnvironmentFile": {
      "properties": {
        "teamsAppId": { "$ref": "#/definitions/envVarName" }
      }
      // teamsAppTenantId is not declared
    }
  }
}

For comparison, aadApp/create in the same schema does expose a tenant id correctly via its tenantId output, writable to any env var the author chooses (we use AAD_APP_TENANT_ID in this project).

To Reproduce

1. In any ATK project with version: v1.11 or v1.10 in m365agents.local.yml, add teamsAppTenantId to the teamsApp/create action's writeToEnvironmentFile block, following the documented pattern:

   - uses: teamsApp/create
     with:
       name: my-agent${{APP_NAME_SUFFIX}}
     writeToEnvironmentFile:
       teamsAppId: TEAMS_APP_ID
       teamsAppTenantId: TEAMS_APP_TENANT_ID   # ← as documented in the wiki

2. Open the file in VS Code with the YAML extension active. Observe the language server flag teamsAppTenantId as not allowed by the schema:

   Property teamsAppTenantId is not allowed.
   

3. Cross-reference the schema file directly:

   $ curl -sL https://developer.microsoft.com/json-schemas/teams-toolkit/teamsapp-yaml/v1.11/yaml.schema.json \
       | jq '..|.teamsApp?//empty' -c | grep -o 'teamsAppTenantId'
   (no matches)
   

4. Confirm the wiki page still lists it as an output. The two sources disagree.

Additional finding — ATK writes TEAMS_APP_TENANT_ID anyway

Even though teamsApp/create doesn't expose teamsAppTenantId via writeToEnvironmentFile, ATK does populate TEAMS_APP_TENANT_ID in the environment by the end of provision. Observed in a clean atk provision --env local run's final Env output:

"AAD_APP_TENANT_ID":"c24e6842-...",
"TEAMS_APP_TENANT_ID":"c24e6842-...",   ← present, but no yml action wrote it
"TEAMS_APP_ID":"08d4ac64-..."

And the on-disk .env.local after provision:

AAD_APP_TENANT_ID=c24e6842-5db7-45ee-8afc-af300fb3e1cd
TEAMS_APP_TENANT_ID=c24e6842-5db7-45ee-8afc-af300fb3e1cd

TEAMS_APP_TENANT_ID is being populated by some internal ATK mechanism — likely from the authenticated M365 session's tenant — not through any documented writeToEnvironmentFile surface. Which means:

1. The value is available at runtime, but there is no documented, schema-valid way to configure the env var name for it. TEAMS_APP_TENANT_ID appears to be a hardcoded-by-convention name rather than something the yml author controls.
2. If you wanted to route this tenant id into a different env var, you can't — the write is implicit and the yml has no entry point for it.
3. Authors following the wiki end up with invalid yml that either fails schema validation (if v1.11) or silently does nothing (if the runtime tolerates unknown writeToEnvironmentFile keys).

Expected behavior

Pick one, and align wiki + schema + runtime on it:

1. Formally support teamsAppTenantId in the schema, matching the wiki. Then authors can route the value to a named env var via the documented interface:

   writeToEnvironmentFile:
     teamsAppId: TEAMS_APP_ID
     teamsAppTenantId: MY_TENANT_ID_VAR

2. Remove teamsAppTenantId from the wiki if the feature isn't intended to exist. Document that authors should use aadApp/create.tenantId instead (via AAD_APP_TENANT_ID or similar) when they need the tenant id.

3. Document the implicit TEAMS_APP_TENANT_ID injection if it's intended behavior. Authors can't rely on it today because it isn't mentioned in the schema or the wiki — it only shows up in actual env output, which means people discover it by accident.

Actual behavior

The wiki documents a feature the schema rejects. Authors who follow the wiki hit a language-server error. Authors who don't follow the wiki but inspect the generated env discover an undocumented TEAMS_APP_TENANT_ID with no corresponding yml surface. There is no clean, documented path between "I need the tenant id in my env" and "here is the supported way to do it on teamsApp/create."

The practical consequence (confirmed in this project): compile-time references to the tenant id should route through aadApp/create's documented tenantId output (e.g., AAD_APP_TENANT_ID), not anything on teamsApp/create. This works but is a discovery tax — the wiki's teamsApp/create section steers you down a dead end first.

Repro environment

• OS: macOS
• VS Code: v26.1
• Microsoft 365 Agents Toolkit: v1.11 schema (same issue confirmed in v1.10)
• Wiki commit: https://github.com/OfficeDev/microsoft-365-agents-toolkit/wiki/Available-actions-in-Microsoft-365-Agents-Toolkit (as of 2026-04-17)
• Schema: https://developer.microsoft.com/json-schemas/teams-toolkit/teamsapp-yaml/v1.11/yaml.schema.json

Workaround

When you need the tenant id at compile/build time, use aadApp/create's tenantId output, which is schema-valid and documented:

- uses: aadApp/create
  with:
    name: My App
    generateClientSecret: true
    signInAudience: AzureADMyOrg
  writeToEnvironmentFile:
    clientId: AAD_APP_CLIENT_ID
    objectId: AAD_APP_OBJECT_ID
    tenantId: AAD_APP_TENANT_ID          # ← schema-valid, documented, reliable
    authority: AAD_APP_OAUTH_AUTHORITY
    # ...

Then reference AAD_APP_TENANT_ID in whatever compile step or template needs a tenant id. Don't reference TEAMS_APP_TENANT_ID — it's written implicitly and not part of any author-controllable contract.

[m365-agent-toolkit-assistant]

👋 Hi @andrewconnell,

Thank you for reporting this issue! We want to let you know that:

⏱️ Our team will personally review your issue
🎯 You can expect a response within 2 business days

✨ This is an AI-generated initial response
🤖 AI-Generated Preliminary Analysis:

Classification: Bug — the docs and runtime behavior described here are inconsistent with the published v1.10/v1.11 YAML schema, so authors following the documented teamsApp/create contract hit invalid YAML.

• Your report shows a clear contract mismatch: wiki says teamsAppTenantId is a supported writeToEnvironmentFile output, but the v1.10/v1.11 schema only allows teamsAppId.
• Microsoft Learn guidance consistently documents aadApp/create.tenantId as the supported, schema-driven way to write a tenant ID to env files, e.g. tenantId: AAD_APP_TENANT_ID in writeToEnvironmentFile.
• That makes your workaround consistent with official guidance; relying on implicit TEAMS_APP_TENANT_ID appears undocumented.

Upgrade check: Unverified — I couldn’t confirm a changelog entry or newer schema fix from the repo data available here.

What to do now:

1. Use aadApp/create.writeToEnvironmentFile.tenantId for compile-time tenant ID needs.
2. Avoid teamsAppTenantId in YAML until schema/docs are aligned.
3. Ask maintainers to either add schema support or remove the wiki claim and document implicit TEAMS_APP_TENANT_ID.

Useful links:

• https://learn.microsoft.com/microsoftteams/platform/toolkit/provision#provision-actions
• https://learn.microsoft.com/microsoftteams/platform/toolkit/use-existing-aad-app#set-necessary-info-in-teamsfx-project

If you want, I can also help draft a maintainer-ready resolution comment.

---

Note: This is an automated first response generated by AI. A human team member will review your issue and provide a more detailed response soon. We appreciate your patience!