Udrul Microsoft Copilot Managed Runtime-apps med GitHub-handlinger

Du kan udrulle Copilot-administrerede kørselsapps med GitHub Actions uden at gå gennem den platformsadministrerede buildpipeline. Byg hver app med din egen værktøjskæde, og udrul det eksterne artefakt direkte via Microsoft Copilot Managed Runtime CLI (ms).

Tre GitHub-handlinger i lageret microsoft/Managed-Apps (under stien github-actions/ ) gør arbejdet:

• install-ms-cli installerer Copilot Managed Runtime CLI på løberen.
• ms-app-pack Bygger appen og pakker den i en artefakt, der kan installeres.
• ms-app-deploy Installerer artefaktet i dit miljø.

Når du har fuldført trinnene i denne artikel, installeres hver push til lagerets primære gren automatisk i dit miljø.

Forudsætninger

Før du installerer en app fra GitHub Actions:

1. Opret en app med "repoType": "none". Kør ms app create--repo none lokalt for at oprette appen og generere dens ms.config.json (stemplet med "repoType": "none"). Dette trin kræver, at @microsoft/managed-apps-cli versionen 0.7.0 eller nyere er installeret lokalt. Arbejdsprocessen installerer CLI på løberen for dig.
2. Brug et GitHub-lager , der indeholder din appkilde (herunder ms.config.json) og arbejdsprocesfilen. Du skal have tilladelse til at administrere lagerets hemmeligheder under Handlinger.
3. Konfigurer en tjenesteprincipal med tilladelse på appens miljø. Du opretter en i trin 1.
4. Installation af eksterne artefakter er som standard ikke tilladt. Se Udrulning af eksterne artefakter.

Trin 1: Opret og konfigurer tjenesteprincipalen

Arbejdsprocessen godkendes som tjenesteprincipal ved hjælp af OAuth 2.0-klientens legitimationsflow. Konfigurer tjenesteprincipalen én gang pr. lejer.

Registrer et program i Microsoft Entra ID

1. Log på portalenAzure.
2. Gå til Microsoft EntraIDApp-registreringer>>+ Ny registrering.
3. Angiv et navn (f.eks.), managed-apps-spnvælg Kun firmaer i denne organisationsmappe, lad omdirigerings-URI'en være tom, og vælg derefter Registrer.
4. På siden Oversigt skal du kopiere program-id (klient) og mappe-id (lejer) til senere.
5. Gå til Certifikater & hemmeligheder>+ Ny klienthemmelighed. Angiv en beskrivelse, vælg udløbsdato, og vælg derefter Tilføj. Kopiér straks kolonnen Værdi . Du kan ikke se hemmeligheden igen, når du forlader denne side.

Giv tjenesteprincipal-tilladelse til appens miljø

Den nøjagtige tildeling afhænger af, om miljøet er Dataverse-aktiveret.

Dataverse-aktiverede miljøer

1. Log på Power Platform Administration.
2. Vælg Miljøer, og vælg derefter appens miljø.
3. Gå til Indstillinger>Brugere + tilladelser>Programbrugere.
4. Vælg + Ny appbruger, vælg + Tilføj en app, søg efter applikations-id'et (klient), og vælg derefter Tilføj.
5. Angiv afdelingen, tildel sikkerhedsrollerne Systemadministrator og Systemtilpasser , og vælg derefter Opret.

Ikke-Dataverse-miljøer

Ikke-Dataverse-miljøer (sandkasse-SKU) er ikke vært for programbrugere. Tildel rollen som EnvironmentAdmin direkte via Business Application Platform (BAP) API'en.

Få et adgangstoken fra en bruger, der har EnvironmentAdmin rollen i appens miljø:

az login --tenant <your-tenant-id>
az account get-access-token --resource https://service.powerapps.com/ --query accessToken -o tsv

Udsted derefter en POST-anmodning til BAP API'en for at tilføje rolletildelingen. Til produktion skal den bruges https://api.bap.microsoft.com som grundlæggende URL-adresse.

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": []
}

Trin 2: Føj hemmelighederne til dit GitHub-lager

Vælg Indstillinger> forhemmeligheder og variabler>Handlinger> i dit lagerNy lagerhemmelighed, og tilføj derefter disse tre hemmeligheder fra appregistreringen:

Trin 3: Tilføj installationsarbejdsprocessen

Føj følgende arbejdsproces til dit lager på .github/workflows/deploy-managed-app.yml. Erstat apps/my-app med stien til din 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/Managed-Apps/github-actions/install-ms-cli@v1

    - name: Pack app
      uses: microsoft/Managed-Apps/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/Managed-Apps/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 }}

Filteret paths: kører kun arbejdsprocessen, når filerne i appens mappe ændres. Giv hver app sin egen arbejdsprocesfil og paths: filter i et monorepo med flere apps.

Det er alt, hvad du har brug for til standardarbejdsprocessen: ms-app-pack Bygger og klargør artefaktet og ms-app-deploy installerer det. Det næste afsnit beskriver handlingerne mere detaljeret, herunder hvordan du implementerer en færdigbygget artefakt.

Reference: GitHub-handlingerne

Referer til hver handling som microsoft/Managed-Apps/github-actions/<name>@v1. Mærket v1 flyttes til den nyeste version. Fastgør et uforanderligt mærke, f.eks @v1.0.1 . for reproducerbare builds.

ms-app-pack og ms-app-deploy godkend med tjenesteprincipalen, så overfør disse nødvendige input til hver handling fra de hemmeligheder, du tilføjede i trin 2:

install-ms-cli

Installeres @microsoft/managed-apps-cli på løberen og føjer den ms binære fil til PATH. Det fungerer uden input til offentlig npm. Hvis du vil installere fra et privat feed (f.eks. Azure DevOps-artefakter) eller fastgøre en version, skal du angive de valgfrie input:

Handlingen output, cli-versionden installerede CLI-version.

ms-app-pack

Bygger og pakker appen ved at køre ms app pack. Pack kører buildCommand fra ms.config.json (standard til npm run build) og skifter artefaktet under <working-directory>/.ms/packed/. Brug denne handling før ms-app-deploy , så build- og pakningsfejl kan ses som deres egne trin i arbejdsprocessen.

Angiv working-directory (valgfrit, standardværdien er lagerroden) til den mappe, der indeholder ms.config.json og package.jsonsamt de tre input fra tjenesteprincipalen.

ms-app-deploy

Installeres i appens miljø ved at køre ms app deploy. Handlingen læser appId, environmentId, og repoType fra ms.config.json og vælger automatisk installationstilstanden. Hvis du vil installere en færdigbygget artefakt og springe buildet over, skal du angive artifact-path:

- uses: microsoft/Managed-Apps/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 }}

Valgfri input ud over de tre input til tjenesteprincipalen:

Handlingens app-idoutput , environment-id, commit-sha, og app-play-uri for udrulningen.

Fejlfinding

Relateret indhold

• Copilot Managed Runtime CLI-kommandoreference (prøveversion)
• microsoft/Managed-Apps Lager
• Kom i gang med Power Platform API'en
• Forbindelsesreference til Power Platform for Admins