Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
È possibile distribuire le app di runtime gestito di Copilot con GitHub Actions senza passare attraverso la pipeline di compilazione gestita dalla piattaforma. Crea ogni app con la tua toolchain e distribuisci l'artefatto esterno direttamente tramite l'interfaccia a riga di comando di Microsoft Copilot Managed Runtime (ms).
Tre GitHub Actions nel microsoft/Copilot-Managed-Runtime repository (sotto il github-actions/ percorso) fanno il lavoro:
-
install-ms-cliinstalla l'interfaccia della riga di comando di Copilot Managed Runtime nel runner. -
ms-app-packcompila l'app e la comprime in un artefatto distribuibile. -
ms-app-deployDistribuisce l'artefatto nell'ambiente.
Dopo aver completato i passaggi descritti in questo articolo, ogni push al ramo principale del repository viene distribuito automaticamente nell'ambiente.
Nota
La distribuzione di artefatti esterni è per le app che non usano la pipeline di compilazione e distribuzione gestita dalla piattaforma predefinita. Un'app che utilizza la distribuzione di artefatti esterni ha "repoType": "none" nel suo ms.config.json.
Prerequisiti
Prima di distribuire un'app da GitHub Actions:
- Creare un'app con
"repoType": "none". Eseguims app create--repo nonelocalmente per creare l'app e generarlams.config.json(contrassegnato con"repoType": "none"). Questo passaggio richiede che la versione0.7.0o un@microsoft/cmr-cliversione successiva sia installata localmente. Il flusso di lavoro installa automaticamente l'interfaccia della riga di comando sul corridore. - Usa un repository GitHub che contiene l'origine dell'app (incluso
ms.config.json) e il file del flusso di lavoro. È necessaria l'autorizzazione per gestire i segreti delle azioni del repository. - Configurare un'entità servizio con l'autorizzazione per l'ambiente dell'app. Ne crei uno nel passaggio 1.
- La distribuzione di artefatti esterni non è consentita per impostazione predefinita. Consulta Distribuzione di artefatti esterni.
Importante
L'organizzazione è responsabile della convalida degli artefatti creati esternamente e della protezione della pipeline per soddisfare i requisiti di sicurezza, conformità e catena di approvvigionamento del software.
Passaggio 1: Creare e configurare l'entità servizio
Il flusso di lavoro esegue l'autenticazione come entità servizio usando il flusso delle credenziali client OAuth 2.0. Configurare l'entità servizio una volta per tenant.
Registrare un'applicazione in Microsoft Entra ID
- Accedere al portale di Azure.
- Vai a Microsoft Entra IDRegistrazioni>app>+ Nuova registrazione.
- Immetti un nome (ad esempio,
managed-apps-spn), scegli Account solo in questa directory organizzativa, lascia vuoto l'URI di reindirizzamento e quindi seleziona Registrati. - Nella pagina Panoramica copiare l'ID applicazione (client) e l'ID directory (tenant) per un secondo momento.
- Passare a Certificati & segreti>+ Nuovo segreto client. Immettere una descrizione, scegliere una scadenza e quindi selezionare Aggiungi. Copiare immediatamente la colonna Valore . Non potrai più visualizzare il segreto dopo aver lasciato questa pagina.
Concedere all'entità servizio l'autorizzazione per l'ambiente dell'app
La concessione esatta dipende dal fatto che l'ambiente sia abilitato per Dataverse.
Ambienti abilitati per Dataverse
- Accedere all'interfaccia di amministrazione di Power Platform.
- Selezionare Ambienti, quindi selezionare l'ambiente dell'app.
- Passare a Utenti impostazioni>+ autorizzazioni>Utenti dell'applicazione.
- Selezionare + Nuovo utente dell'app, selezionare + Aggiungi un'app, eseguire una ricerca in base all'ID applicazione (client) e quindi selezionare Aggiungi.
- Impostare la business unit, assegnare i ruoli di sicurezza Amministratore di sistema e Personalizzazione sistema , quindi selezionare Crea.
Ambienti non Dataverse
Gli ambienti non Dataverse (sandbox-SKU) non ospitano utenti dell'applicazione. Concedere il ruolo di amministratore dell'ambiente direttamente tramite l'API BAP (Business Application Platform).
Importante
Usare l'ID oggetto dell'entità servizio (da Portale di Azure applicazioni>aziendali> Panoramica dell'app>), non l'ID oggetto della registrazione dell'app. Si tratta di GUID diversi e l'uso di quello errato restituisce un 400 Principal not found errore.
Ottenere un token di accesso da un utente che ha il EnvironmentAdmin ruolo nell'ambiente dell'app:
az login --tenant <your-tenant-id>
az account get-access-token --resource https://service.powerapps.com/ --query accessToken -o tsv
Quindi inviare una richiesta POST all'API BAP per aggiungere l'assegnazione di ruolo. Per la produzione, utilizzare https://api.bap.microsoft.com come URL di base.
POST https://<bap-base-url>/providers/Microsoft.BusinessAppPlatform/scopes/admin/environments/<environment-id>/modifyRoleAssignments?api-version=2021-04-01
Authorization: Bearer <user-token>
Content-Type: application/json
{
"add": [
{
"properties": {
"roleDefinition": {
"id": "/providers/Microsoft.BusinessAppPlatform/scopes/admin/environments/<environment-id>/roleDefinitions/EnvironmentAdmin"
},
"principal": {
"id": "<service-principal-object-id>",
"type": "ServicePrincipal",
"tenantId": "<tenant-id>"
}
}
}
],
"remove": []
}
Nota
Invece di chiamare direttamente l'API BAP, è possibile usare l'azione Modifica assegnazione ruolo ambiente del connettore Power Platform per amministratori, che è utile quando si concede il ruolo da un flusso cloud Power Automate. Per l'accesso a livello di programmazione alle stesse funzionalità di amministrazione, vedere Introduzione all'API di Power Platform.
Passaggio 2: aggiungi i segreti al repository GitHub
Nel repository, selezionare Impostazioni>Segreti e variabili>Azioni>Nuovo segreto del repository, quindi aggiungere questi tre segreti dalla registrazione dell'app:
| Nome segreto | Valore |
|---|---|
PP_SP_CLIENT_ID |
ID applicazione (client). |
PP_SP_CLIENT_SECRET |
Valore del segreto client. |
PP_SP_TENANT_ID |
ID directory (tenant). |
Passaggio 3: Aggiungere il flusso di lavoro di distribuzione
Aggiungi il seguente flusso di lavoro al tuo repository in .github/workflows/deploy-managed-app.yml. Sostituire apps/my-app con il percorso dell'app.
name: Deploy Copilot Managed Runtime app
on:
push:
branches: [main]
paths:
- 'apps/my-app/**'
- '.github/workflows/deploy-managed-app.yml'
workflow_dispatch:
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
- name: Setup Node 24
uses: actions/setup-node@v5
with:
node-version: '24'
- name: Install app dependencies
working-directory: apps/my-app
run: npm install
- name: Install ms CLI
uses: microsoft/Copilot-Managed-Runtime/github-actions/install-ms-cli@v1
- name: Pack app
uses: microsoft/Copilot-Managed-Runtime/github-actions/ms-app-pack@v1
with:
working-directory: 'apps/my-app'
app-id: ${{ secrets.PP_SP_CLIENT_ID }}
client-secret: ${{ secrets.PP_SP_CLIENT_SECRET }}
tenant-id: ${{ secrets.PP_SP_TENANT_ID }}
- name: Deploy app
uses: microsoft/Copilot-Managed-Runtime/github-actions/ms-app-deploy@v1
with:
working-directory: 'apps/my-app'
app-id: ${{ secrets.PP_SP_CLIENT_ID }}
client-secret: ${{ secrets.PP_SP_CLIENT_SECRET }}
tenant-id: ${{ secrets.PP_SP_TENANT_ID }}
Il paths: filtro esegue il flusso di lavoro solo quando i file all'interno della directory dell'app cambiano. In un monorepository con più app, assegna a ogni app il proprio file di flusso di lavoro e paths: filtro.
Importante
Il npm install passaggio deve essere eseguito nella directory di lavoro dell'app prima del passaggio del pacchetto.
ms-app-pack Compila l'app eseguendo npm run build, che richiede node_modules la presenza. Utilizzare lo stesso working-directory per npm install, ms-app-pack, e ms-app-deploy.
Questo è tutto ciò di cui hai bisogno per il flusso di lavoro standard: ms-app-pack crea e organizza l'artefatto e ms-app-deploy lo distribuisce. La sezione successiva illustra le azioni in modo più dettagliato, incluso come distribuire un artefatto predefinito.
Riferimento: GitHub Actions
Fai riferimento a ogni azione come microsoft/Copilot-Managed-Runtime/github-actions/<name>@v1. Il tag passa alla versione più recente. Aggiungi v1 un tag non modificabile, ad esempio @v1.0.1 per le build riproducibili.
ms-app-pack ed ms-app-deploy eseguire l'autenticazione con l'entità servizio, in modo da passare questi input necessari a ogni azione dai segreti aggiunti nel passaggio 2:
| Input | Descrizione |
|---|---|
app-id |
ID client dell'entità servizio. |
client-secret |
Segreto dell'entità servizio. |
tenant-id |
ID tenant Microsoft Entra ID. |
install-ms-cli
Si installa @microsoft/cmr-cli sul runner e aggiunge il ms file binario al PATH. Funziona senza input per l'npm pubblico. Per eseguire l'installazione da un feed privato (ad esempio, Azure DevOps Artifacts) o per aggiungere una versione, impostare gli input facoltativi:
| Nome | Impostazione predefinita | Descrizione |
|---|---|---|
version |
latest |
Semver o latest. Aggiungere una versione specifica per la riproducibilità. |
registry-url |
https://registry.npmjs.org |
URL del Registro di sistema npm. Sostituiscilo per i feed interni. |
registry-auth-token |
(vuoto) | Token di connessione o PAT per i registri privati. |
npm-package-name |
@microsoft/cmr-cli |
Eseguine l'override per testare build alternative. |
L'azione restituisce cli-versionla versione CLI installata.
ms-app-pack
Compila e comprime l'app eseguendo .ms app pack Il pacchetto esegue il buildCommand from ms.config.json (impostazione predefinita su npm run build) e mette in scena l'artefatto in <working-directory>/.ms/packed/. Usare questa azione prima in ms-app-deploy modo che gli errori di compilazione e creazione di pacchetti siano visibili come passaggio del flusso di lavoro.
Impostato working-directory (facoltativo, il valore predefinito è la radice del repository) sulla directory che contiene ms.config.json e package.json, più i tre ingressi dell'entità servizio.
ms-app-deploy
Si distribuisce nell'ambiente dell'app eseguendo .ms app deploy L'azione legge appId, environmentId, e repoType da e seleziona ms.config.json automaticamente la modalità di distribuzione. Per distribuire un artefatto predefinito e saltare la compilazione, imposta:artifact-path
- uses: microsoft/Copilot-Managed-Runtime/github-actions/ms-app-deploy@v1
with:
working-directory: 'apps/my-app'
artifact-path: '../app.zip'
app-id: ${{ secrets.PP_SP_CLIENT_ID }}
client-secret: ${{ secrets.PP_SP_CLIENT_SECRET }}
tenant-id: ${{ secrets.PP_SP_TENANT_ID }}
Input facoltativi, oltre ai tre input dell'entità servizio:
| Nome | Impostazione predefinita | Descrizione |
|---|---|---|
working-directory |
(radice repo) | Percorso della directory che contiene ms.config.jsoni file . |
commit-sha |
$GITHUB_SHA |
Commit SHA per le app supportate da git. Si escludono a vicenda con artifact-path. |
artifact-path |
(vuoto) | Percorso verso un artefatto predefinito .zip . Valido solo per repoType: 'none' le app. Si escludono a vicenda con commit-sha. |
app-name |
(a partire da ms.config.json) |
Eseguire l'override del nome dell'app. |
Risultati dell'azione app-id, environment-id, commit-sha, e app-play-uri per la distribuzione.
Risoluzione dei problemi
| Sintomo | Causa | Correzione |
|---|---|---|
| L'azione segnala che l'accesso non è stato eseguito. | L'azione non ha ricevuto tutti e tre gli input dell'entità servizio. | Pass app-id, client-secret, e tenant-id a entrambi ms-app-pack e ms-app-deploy. |
External artifact deployment is disabled for this environment |
La distribuzione di artefatti esterni non è abilitata. | Consulta Distribuzione di artefatti esterni. |
Forbidden — 'Repositories.MicrosoftApps.Deploy.Write' (Ambiente Dataverse) |
All'entità servizio mancano i ruoli Dataverse richiesti. | Assegnare entrambi i ruoli di amministratore di sistema e di personalizzazione del sistema all'utente dell'applicazione. |
400 Principal not found (ambiente non Dataverse) |
È stato usato l'ID oggetto della registrazione dell'app anziché l'ID oggetto dell'entità servizio. | Usare l'ID oggetto dalle applicazioni aziendali, non dalle Registrazioni app. |
ms.config.json not found in working-directory |
working-directory non punta alla directory che contiene ms.config.json. |
Impostato working-directory su quel percorso. Il paths: filtro, npm install il passaggio e le azioni devono usare lo stesso percorso. |
npm error code E401 Incorrect or missing password |
È configurato un registro privato, ma il token di autenticazione ha l'ambito o l'organizzazione errata. | Assicurati che registry-auth-token sia un PAT con l'ambito e l'organizzazione giusti per quel feed. |