Distribuire app di runtime gestito di Microsoft Copilot con GitHub Actions

È 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-cli installa l'interfaccia della riga di comando di Copilot Managed Runtime nel runner.
  • ms-app-pack compila l'app e la comprime in un artefatto distribuibile.
  • ms-app-deploy Distribuisce 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:

  1. Creare un'app con "repoType": "none". Esegui ms app create--repo none localmente per creare l'app e generarla ms.config.json (contrassegnato con "repoType": "none"). Questo passaggio richiede che la versione 0.7.0 o un @microsoft/cmr-cli versione successiva sia installata localmente. Il flusso di lavoro installa automaticamente l'interfaccia della riga di comando sul corridore.
  2. 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.
  3. Configurare un'entità servizio con l'autorizzazione per l'ambiente dell'app. Ne crei uno nel passaggio 1.
  4. 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

  1. Accedere al portale di Azure.
  2. Vai a Microsoft Entra IDRegistrazioni>app>+ Nuova registrazione.
  3. 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.
  4. Nella pagina Panoramica copiare l'ID applicazione (client) e l'ID directory (tenant) per un secondo momento.
  5. 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

  1. Accedere all'interfaccia di amministrazione di Power Platform.
  2. Selezionare Ambienti, quindi selezionare l'ambiente dell'app.
  3. Passare a Utenti impostazioni>+ autorizzazioni>Utenti dell'applicazione.
  4. Selezionare + Nuovo utente dell'app, selezionare + Aggiungi un'app, eseguire una ricerca in base all'ID applicazione (client) e quindi selezionare Aggiungi.
  5. 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.