Managed apps can be built directly with code, through Cowork, or through Copilot Studio. Share portable application source compatible with Copilot Managed Runtime, not the contributor's deployed app, repository identity, or connection configuration. These app sources are not Power Platform solution packages. Existing gallery agent/workflow submissions continue to use exploded solutions. For the shared repository setup, metadata, validation, and pull-request process, start with the contribution guide.
The standard first-party CLI flow does not require making your own Entra app registration, service principal, client secret, or access token. Tenant policies, licensing, app creation rights, connector consent, and data permissions still apply. Play access alone does not grant source export/edit access.
Complete the gallery repository setup first. This section prepares local or exported app source; later sections cover testing and installation.
Install the prerequisites in Microsoft's Managed Apps developer guide: Node >=24.11, npm, Git >=2.27 with a TLS-1.3-capable transport, and Git Credential Manager. Use the supported Git/GCM installation for your OS. Some Apple Git builds cannot negotiate the CLI's required TLS version; use a compatible Git installation, not certificate/TLS bypasses. The gallery itself still uses Node 22.
For a code-first app, start with your local source directory and ensure it meets the package, build, and license requirements below. You do not need an existing deployed app to prepare a submission; fresh managed-app testing is still required.
For an existing app in a platform-managed Git repository, export its source with the native CLI. From a working directory outside the gallery checkout, clone it into a new local directory:
npx --yes --package=@microsoft/managed-apps-cli -- ms auth login
npx --yes --package=@microsoft/managed-apps-cli -- ms auth status
npx --yes --package=@microsoft/managed-apps-cli -- ms app list
npx --yes --package=@microsoft/managed-apps-cli -- ms app clone ./my-app --app YOUR_APP_GUIDUse the native clone command for your app into a new local directory, following its help. Clone supports platform-managed repositories; do not extract browser tokens or substitute custom authentication.
For either starting point, return to the gallery checkout and prepare the submission, pointing the helper at your local app source:
npm run prepare:app -- /path/to/your-app-source my-app --dry-run
npm run prepare:app -- /path/to/your-app-source my-appThe helper never modifies the source directory, overwrites an existing submission, installs dependencies, signs in, or calls cloud services. It excludes Git history, local caches/build output, deployment/builder configuration, environment files, and common credential files. It reports original connections that need documentation. It is not a secret scanner or a guarantee of portability. Review every file, including generated clients, embedded URLs, sample data, screenshots, and lockfiles, for private information. Do not copy private or unlicensed source into the gallery.
Layout:
submissions/my-app/
metadata.json
README.md
app/
package.json
package-lock.json
LICENSE
src/
...portable source and, when safe, native generated clients
screenshots/ # optional PNGs
V1 supports npm-based web apps with a build script producing dist/index.html.
Provide an npm v2+ lockfile and a source license. Other build layouts/package
managers need an explicitly supported gallery contract; do not assume the
gallery's validation can infer them.
Complete the shared author/category/tag metadata and app setup:
{
"submissionType": "managed-app",
"name": "My app",
"description": "What this app helps people do.",
"tags": ["managed-app", "sharepoint"],
"author": "Your name",
"app": {
"prerequisites": ["An existing Team Ideas list with the documented columns."],
"connectors": [{
"connector": "shared_sharepointonline",
"mode": "table",
"dataSource": "teamideas",
"table": "Team Ideas",
"instructions": "Choose your connection and SharePoint site in the native CLI.",
"columns": [{
"name": "Title",
"type": "Single line of text",
"description": "Required built-in column."
}]
}]
}
}List every required connector binding. Use mode: "action" for action-mode
connectors and omit table/columns. dataSource records the generated logical
source the app expects; table documents the expected table/list name.
For SharePoint, use the native table picker: it resolves the chosen list to its
site-specific ID, which is not the display name. For other connectors, pass
their documented table identifier when required. Choosing a differently
named table can generate a different source/service name and break app imports.
Do not silently rewrite generated code or pretend arbitrary tables are compatible.
For Dataverse fixed tables, use shared_commondataserviceforapps, mode: "table",
and the logical table name (for example contoso_idea), not its display label.
There is no SharePoint-style dataset. The CLI defaults to the app's environment;
manual setup can pass --dataverse-environment-id when required. Custom Dataverse
tables/columns must already exist; an independently documented companion Power
Platform solution can supply schema. Gallery app creation does not provision it.
Never put site URLs, connection/reference IDs, environment/app/repository IDs,
sharedConnectionId, or credentials in setup metadata. The recipient binds
their own resources. Unknown setup keys fail validation.
Screenshots are strongly recommended in every app README. Show the main screen and, when useful, a key interaction so visitors can understand the app without installing it. Use synthetic/redacted data and descriptive alt text. For example:
## Screenshots
Also declare the primary image in gallery metadata:
{"screenshot":{"path":"screenshots/board.png","alt":"Meaningful description"}}.
Only PNG, at most 2 MiB and 4096 x 4096, is accepted. No remote screenshot URLs
or active SVG content. Use synthetic data, and label illustrative images clearly.
Inline Markdown references to local screenshots/<lowercase-hyphenated-name>.png
images are also published and rewritten to generated public image URLs for the
gallery; the original README stays GitHub-readable. Up to five images, including
the primary screenshot, are supported. Each must meet the same PNG size and
dimension limits; symlinks are rejected. Only the image declared in metadata
becomes the primary preview. README images stay outside the app source ZIP.
The README is required and becomes the detail-page guide. Focus on the app's
purpose, screenshots, usage, app-specific data requirements and permissions,
limitations, and customization. Include the exact list/table schema and how to
create it, but keep installation, authentication, CLI, build, and deployment
instructions in this shared guide rather than repeating them in each README.
App version comes from app/package.json.
Optional CSV, JSON, and plain-text supporting files can provide synthetic data or reference material. Declare them in metadata; they are separate downloads, never part of the app source ZIP or imported automatically.
Run the shared local checks, starting with
npm run check:submissions. Ingestion never executes app code, installs its dependencies,
or runs cloud operations. Separately test the app's source in a fresh managed
app with only its documented prerequisites as described below, then
open a pull request and complete the
managed app attestation.
Native Copilot uses static managed-app review guidance; review automation never installs or executes the submitted app. The shared PR task queue shows one prioritized next action and its owner, plus other known contributor requirements so they can be addressed together. Missing attestations precede routine branch updates. Behind-main branch updates belong to maintainers; actual conflicts remain contributor work. Contributor instructions mention the author, with a new notification on action changes rather than on routine reruns. CI authorization, formal approval, and merge remain manual; later maintainer actions are hidden until their prerequisites are satisfied. Checked attestations are not automated runtime tests.
The page's setup command reads the submission's app/ folder from the
gallery repository's published main branch. Editing a local submission does
not make that template available on GitHub. Do not claim a fresh GitHub-template
installation passed until that source is accessible.
Before publication, review the source ZIP or a separate copy of app/, and use
the native CLI's existing-project flow in that new directory:
npx --yes --package=@microsoft/managed-apps-cli -- ms app init --display-name "Local test app" --repo nativeThis is a local-source test, not a test of the public
GitHub-template command. Prepare the real list/table first and complete the
native connection, pack, and preview steps below. Unlike app create, an
initialized local project may not share the new repository's initial history.
If the initial push is rejected, fetch and inspect that history before
integrating it without overwriting remote work; do not force-push.
Do not create a temporary
installer backend, extract credentials, or bypass TLS.
The detail page groups the trust acknowledgement and support notice above Automated install, with command boxes for macOS · Bash and Windows · PowerShell. They sit side by side when the panel has room and stack on phones and in the desktop sidebar. Download and install manually and Manual setup guide & requirements appear below the commands. Check the trust acknowledgement to enable the download and commands. For automated setup, review the appropriate command and choose its Copy control or copy it manually. Unchecking the acknowledgement disables the download and clears and disables the commands again. Linux is not supported.
Managed-app detail pages do not display a download counter. The public download data still tracks the manual source ZIP's GitHub Release downloads across tracked versions, not command copies or automated installs. The shared installers remain on Pages and native app creation reads the GitHub template separately. See Gallery analytics. The data refreshes without rebuilding Pages and does not alter the source ZIP link or the native template/installer flow.
Paste the command into a terminal in the folder where you want the new app.
Node is not required to start: Bash/curl or Windows PowerShell 5.1+ downloads
the shared installer. Its URL is visible in the command. There are exactly two
installers under public/installers/, not generated installers per app.
The only submission-specific inputs are its slug and validated connector bindings;
the GitHub template path is derived from the slug.
Before any sign-in or cloud creation, installers check the
Microsoft prerequisites:
Node.js >=24.11, npm, Git >=2.27, and Git Credential Manager.
Compatible existing tools are reused. On macOS, setup also discovers an installed
Homebrew node@24 when an older Node shadows it in a new terminal; it adds the
compatible version to this setup process's PATH without reinstalling it.
Missing tools are installed only after
confirmation, using Homebrew on macOS and WinGet on Windows. The macOS installer
can run Homebrew's official installer, with separate confirmation, if Homebrew
is missing. Apple Git is replaced for this setup process by Homebrew Git
to support the managed repository's TLS 1.3 requirement; the Apple installation
is not removed. Windows uses Git for Windows, which normally includes GCM,
and offers the official GCM package separately only if GCM is missing.
Package-manager installation, administrator approval, and corporate restrictions
remain OS-owned. WinGet must already be available; if it is unavailable or
installation is blocked, follow Microsoft's prerequisite links and retry.
Cancelling stops setup. No execution-policy changes, TLS bypasses, forced
installation, or removal of existing tool installations are performed.
Installers update their process PATH, not the user's persistent PATH directly.
Official package installers can make their normal system/user changes.
If GCM is not configured, its native configure command requires separate
confirmation because it updates Git credential-helper settings.
After preflight, the installer only sequences ordinary native CLI, npm, and Git commands. There is no custom authentication, connector API, environment picker, source overlay, or archive installer. Native prompts retain terminal input/output.
The sequence is: native sign-in and account status, native app creation from the
GitHub template, each declared connection's native prompts, npm install,
native pack, Git commit/push to the new managed repository, hosted build, then
preview. It skips an unnecessary commit when there are no staged changes.
The user handles sign-in and the CLI's account/environment/connection/site/list
choices; the runner supplies only declared connector modes and fixed Dataverse
logical table names. SharePoint always uses the native table picker.
npx --yes --package=@microsoft/managed-apps-cli -- ms makes the first-party CLI
available through npm's project installation/cache, downloading it when needed,
without sudo or a global installation. The CLI creates the app and
platform-managed repository and scaffolds from the submission's GitHub folder.
Follow its prompts and check the displayed target account and environment.
A branch/tag template reference is used, not an arbitrary commit SHA.
Creation explicitly passes --repo native for a standalone platform-managed
repository. Run outside existing managed projects; the native CLI rejects that
combination rather than letting subsequent Git commands affect a shared project.
The template reads current published source from main. The separately
downloadable, content-addressed source ZIP is a snapshot from the gallery build;
it is not a checksum lock on future template downloads. Neither is a security
audit or a promise that executable source is safe. Review community source and
your organization's policies.
Setup executes dependency/build scripts and saves the connected source to the new platform-managed repository. It does not provision lists/tables, create an app registration, publish live, or share access. Prepare the documented data first. Git needs a configured commit identity and functioning Credential Manager. Setup does not change your Git author identity. GCM configuration changes are made only after the explicit confirmation described above.
The equivalent manual steps are below, also useful for resuming after an error.
Use your installed ms, or prefix each command with
npx --yes --package=@microsoft/managed-apps-cli --.
- Prepare Node, Git/GCM, and the sample's actual list/table/schema. Review its
instructions and trust notice. Authenticate and inspect the active account:
ms auth login ms auth status
- From outside any existing managed project, create from the native template:
The installed-CLI equivalent for Team Ideas is:
Optionally pass
ms app create ./team-ideas-board --repo native --template github:microsoft/copilot-studio-gallery/submissions/team-ideas-board/app#main
--environment-id YOUR_ELIGIBLE_ENVIRONMENT_GUID. Omission uses the platform's native default behavior; not every arbitrary environment is necessarily eligible. Check the CLI's displayed target. - Enter the new directory and add each declared data source. For Team Ideas:
Select or create a connection, select the site where you created the list, and select the list itself. A list saved under My lists belongs to your personal site, not the team SharePoint site. The native picker supplies the actual list ID; do not pass its display name as
cd team-ideas-board ms app add data-source --connector shared_sharepointonline --as table--table. The native CLI handles sign-in/consent. Other samples can use table or action mode as documented. For a fixed Dataverse table:ms app add data-source --connector shared_commondataserviceforapps --as table --table contoso_idea
- Install/build and validate through native pack:
Native creation/initialization can add the CLI to
npm install ms app pack
package.jsonwithout updating its lockfile.npm installreconciles that native change;npm ciwould fail on a mismatched lockfile. Save the updated lockfile with the source. This executes app dependency/build scripts and native validation. Resolve schema, generated client, policy, and shared-connection errors explicitly; never bypass them to obtain a successful-looking preview. - Optionally test locally with
ms app devand its authenticated Local Play link. Bare localhost alone does not establish a real connector session. - Save source and review hosted preview:
Include the new
ms.config.jsongenerated by native app creation and updated by connector binding. It must not be ignored: hosted builds need it committed in the new managed repository. This is your app's configuration, not the contributor's original configuration, which remains excluded from gallery submissions and source bundles.On first launch, the native player may ask Allow this app to access your data? Review the app and displayed connector account before choosing Allow. This is a separate user consent step, not an app registration; the setup runner does not grant it automatically. Until consent is given, the app cannot finish loading connector data.git add --all git commit -m "Install gallery sample" git push --set-upstream origin HEAD ms app build ms app play --mode preview - Only after reviewing preview, explicitly publish live if desired:
Live publication and sharing are different operations; the gallery never silently grants access. Use native sharing separately when appropriate.
ms app deploy ms app play --mode live
Native ms app add data-source selects/reuses connections or creates them
inline; SSO/browser behavior depends on the connector and authentication mode.
Users do not need a separate portal-based connection-creation step.
App binding is different from hosted-user authentication. Opening the player does not infer a site/table/schema or create missing data structures. Do not assume all connection setup can wait until first launch. Policies, gateways, custom connectors, shared credentials, consent, and licensing can impose additional prerequisites. Support means declared native flows, not a promise that every possible connector can deploy without configuration.
Shareable authentication may make the CLI write a sharedConnectionId.
Native pack/deploy requires a least-privilege allowedActions policy on shared
references: per-table get/post/patch/delete, or exact operation IDs for
action connectors. Follow Microsoft's
shared-connection policy reference.
The gallery deliberately does not invent a policy or grant every action.
For Team Ideas the intended operations are read/create/update, never delete.
Failures stop at the current stage with native error output. Cloud resources may already exist even if local setup fails; inspect the native creation output and your account's app list before retrying. Do not blindly create another app. The gallery does not automatically retry creation or delete partial resources.
Keep the new app directory and ms.config.json; from there use ms app info
and the matching native step above. Resolve connection/schema errors with native
add/refresh commands, then rerun pack. For a failed Git push, inspect Git's
message and existing history—do not force-push. For failed builds, fix the
reported dependency/type/policy error, save/push the fix, and rerun native build.
If preview cannot open automatically, use ms app play --mode preview again.
The browser must use the same account and tenant as the CLI. If its default
profile uses another account, the player can report App not found despite a
successful build. Open the printed preview URL in the matching browser profile;
do not change app permissions or extract credentials to work around it.
For account/tenant errors, use native ms auth status, ms auth switch, or
interactive login. Never inject tokens or disable TLS/certificate verification.
Browser consent and administrator-controlled policy cannot be bypassed.
Prepare newer source into a separate directory and review the diff. Apply code and schema changes intentionally to the recipient's existing app, regenerate clients when needed, and retain its identity, connections, and Git history. There is no automatic upstream synchronization or schema migration framework.