Deploy agents with pipelines and service principals
Each release of an agent needs a path to test and production that works the same way every time. In this unit, you learn how to set up a pipeline that promotes one managed artifact through its stages, run deployments as a service principal, control them with gated extensions, and finish the configuration that pipelines don't deploy.
Promote one managed artifact with a pipeline
Set up the pipeline's stages
Admins set up shared pipelines in a custom host, which is the pipeline host in your environment plan. They use a custom host because personal pipelines that makers create in the tenant-wide platform host can't be shared or extended.
In the host, admins configure each pipeline in the Deployment Pipeline Configuration app. A pipeline has three parts:
- Environment records: Each environment in the pipeline has a record with a type. Development Environment marks a source where makers build unmanaged solutions. Target Environment marks a destination, such as test or production, that receives managed solutions.
- Linked development environments: A pipeline links one or more development environments, and makers run the pipeline from them.
- Deployment stages: Each stage deploys to one target environment. A stage can name a previous stage, so a deployment to production can require a deployment to test first. A pipeline has from one through seven stages.
The development environment is never a stage. It's the source that every stage deploys from.
In the host, the Deployment Pipeline Administrator role has full control over pipeline configuration, and the Deployment Pipeline User role lets makers run pipelines that are shared with them. Without delegation, a deployment runs as the maker who requests it, so makers also need privileges to export solutions from development and import them into each target environment.
Deploy the artifact through the stages
Makers run pipelines from an unmanaged solution in a linked development environment. In Power Apps, open the solution and select Pipelines. On the standard harness, the Copilot Studio solution explorer also lists Pipelines under the solutions. Pipelines don't appear in the default solution, in managed solutions, or in target environments.
The pipeline exports a solution version when a maker first requests a deployment, and the host stores the artifact and blocks any changes to it. That same managed artifact moves through the stages in order. For example, suppose you deploy version 1.0.0.2 of the HR agent's solution to test and then to production. Production receives the package that test received, even if someone changed the solution in development without incrementing the version.
These rules also shape each deployment:
- Managed only: Pipelines deploy managed solutions. The host also stores the unmanaged export from each deployment, so you can download it to set up another development environment.
- Contents: A deployment carries every customization in the solution, plus the connections, connection references, and environment variable values for the target. It doesn't carry data stored in Dataverse tables.
- One solution per request: Each deployment carries one solution, although one pipeline can deploy several solutions.
- Earlier versions: With the Allow redeployments of older versions setting on, you can redeploy a past successful version from Run history. Redeploying overwrites the latest version and its data, and the loss can't be undone.
- Ownership: The identity that runs the deployment owns the deployed objects.
Control deployments with gated extensions
A gated extension inserts a custom step into a deployment to a stage. The deployment waits at that step until custom logic marks the step complete or rejected. A rejection stops the deployment. While a step is pending, makers see its status and can cancel their request up to the final step. Pipelines offer three gated extensions, which work alone or together:
- Is delegated deployment: Runs the stage as a service principal or the stage owner instead of the requesting maker, after an authorized identity approves the deployment.
- Pre-export step required: Runs custom validation when a maker submits a deployment request, before the pipeline exports the solution. Enable it only on a pipeline's first stage.
- Pre-deployment step required: Adds a custom step after a deployment is approved, such as a final approval.
Deploy as a service principal
Delegated deployment lets makers request deployments without elevated access, or any access, in target environments. The delegated identity then owns the deployed objects. The alternative delegate is the stage owner, a user account. A stage owner is simpler to configure, but it can't deploy solutions that contain connection references for OAuth connections.
To use a service principal, you need the Cloud Application Administrator or Application Administrator role in Microsoft Entra ID, and you must own the enterprise application, not only its app registration. The setup has four steps:
- Create an enterprise application, which is the service principal, in Microsoft Entra ID.
- Add the enterprise application as an application user in the pipeline host and in every target environment the pipeline deploys to.
- Assign the application user the Deployment Pipeline Administrator role in the host and the System Administrator role in each target environment. Lower-permission roles can't deploy plug-ins and other code components.
- On the pipeline stage, select Is delegated deployment, select Service Principal, enter the application's client ID, and then select Save.
Every delegated deployment stays pending until it's approved. You build the approval as a Power Automate cloud flow in the host environment. The flow starts from the OnApprovalStarted trigger and sends an approval request with the deployment details. It then uses the Dataverse Perform an unbound action step to call UpdateApprovalStatus, with a status of 20 to approve or 30 to reject. That step must use a Dataverse connection for the service principal, which requires the client ID and a secret.
Run custom logic on pipeline events
Flows in the host environment can also run the logic for the other gated steps. Each deployment step raises a pipeline event when it starts and when it completes, and gated extensions add events for their steps. A flow starts from the Dataverse When an action is performed trigger with an event such as OnDeploymentRequested, OnPreDeploymentStarted, or OnDeploymentCompleted. The flow completes or rejects its step by calling the matching action, such as UpdatePreDeploymentStepStatus.
Add a trigger condition on the pipeline or stage name so each flow runs only for the deployments it governs. Events also let you connect deployments to other systems, such as an internal system of record.
Finish configuration in each target environment
A deployment carries only what's in the solution, and some agent settings aren't solution-aware. Configure these settings in each target environment after deployment:
- Azure Application Insights settings
- Manual authentication settings
- Direct Line and web channel security settings
- Deployed channels
- Sharing with other makers and with users
On the GitHub Copilot harness, the authentication and web channel security settings are on the Safety & access tab of the agent's settings, and changes there take effect after you save and publish the agent.
Compare pipelines with other deployment tools
Copilot Studio supports several tools for automating agent deployments with continuous integration and continuous delivery (CI/CD), and each tool targets a different audience:
| Tool | Fits | Setup effort |
|---|---|---|
| Power Platform pipelines | Makers who deploy through a built-in, centrally managed process | Low |
| GitHub Actions for Power Platform | Developer and admin teams that automate solution and environment tasks across multiple environments | Moderate |
| Azure DevOps | Enterprise teams that need full ALM control, including source control and CI/CD | High |
Pipelines can't deploy to another tenant, so use Azure DevOps or GitHub Actions for Power Platform for cross-tenant deployments. The tools also work together. Use pipelines for core deployments, and extend them to integrate with other CI/CD tools when a team needs more control. When you extend pipelines, makers still deploy through the same pipeline experience.