Skip to content

Latest commit

 

History

History
169 lines (100 loc) · 10.5 KB

README.md

File metadata and controls

169 lines (100 loc) · 10.5 KB

Development Hub logo

A model-driven app that provides an enhanced development workflow for teams building Power Apps in a shared development environment. Enables continuous integration by automatically creating pull requests or commits for individual developer's changes.

For more context, read this introductory blog post.

Table of contents

Prerequisites

  • At least two Dataverse environments
  • An Azure DevOps organisation

One Dataverse environment acts as the development environment. The other environment(s) are referred to as 'master' environments. For more information on the purpose of a master environment, refer to the Solution Lifecycle Management document published by Microsoft. The relevant information can be found in the environment topologies for development approaches table.

Installation

Create flow connections

You will need to create two flow connections in your development environment. Within the Maker Portal, go to your environment and navigate to Data -> Connections. Create a new Approvals connection and a new Azure DevOps connection. Ensure the Azure DevOps connection is signed in as a user with access to the Azure DevOps project(s) used for source control.

Open the connections and note the connection names by taking them from the URLs, which will be in the format 'environments/environmentid/connections/apiname/connectionname/details'.

Deploy the package

Download the package files from the Releases tab and follow Microsoft's guide to using the Package Deployer here.

You must provide several runtime settings. Refer to the helper PowerShell script below:

$settings = [PSCustomObject]@{
  'ConnRef:devhub_sharedapprovals_6d3fc' = '<the connection name of the Approvals connection>'
  'ConnRef:devhub_sharedvisualstudioteamservices_d7fcb' = '<the connection name of the Azure DevOps connection>'
  'AzureDevOpsOrganisation' = '<the name of the Azure DevOps organisation>'
  'SolutionPublisherPrefix' = '<the prefix of the publisher (without leading underscore)>'
}
$settingsArray = $settings.PSObject.Properties | ForEach-Object { "$($_.Name)=$($_.Value)" }
$runtimePackageSettings = [string]::Join("|", $settingsArray)

Import-CrmPackage -PackageInformation $packages[0] -CrmConnection $conn -RuntimePackageSettings $runtimePackageSettings

Configuration

Register an Azure DevOps project

Register an Azure DevOps project by creating a new Project record.

Project

The name is the name of your Azure DevOps project. The name can't be updated after the record is created and must match the project name on Azure DevOps.

Register a Git repository

Register a Git repository within a project by creating a new Repository record.

Repository

The name must match the repository name on Azure DevOps and it must exist in the chosen project. The target branch is the branch you would like to either push to or create pull requests into (determined by the source control strategy).

To get the extract build definition ID, copy the scripts folder and azure-pipelines-extract.yml file into your repository and create a pipeline for the YAML file. The ID of the resulting build definition can then be used to populate this field.

The sample build script assumes that your repository structure includes a src folder at the root containing a solutions folder - which then contains folders that match your solutions' unique names.

You also need to ensure that permissions are configured correctly for this repository on Azure DevOps. Navigate to Project Settings -> Repositories in your Azure DevOps project. Select the relevant repository and assign the following privileges to the project Build Service user:

  • Contribute
  • Contribute to pull requests
  • Create branch

Register a master environment

Register a master environment by creating a new Environment record.

Environment

Enter a URL and name (this can be anything) for the environment as well as details about the app registration used to authenticate. Application users with the System Administrator role must be created in the development and master environments for the app registration. Follow Microsoft's guide here.

Register a solution

Register a solution within a repository by creating a new Solution record.

Solution

Manually create (or import) your unmanaged solutions in the master environment. Update the version numbers to match the solution in the master environment if you are migrating to the Development Hub with an existing solution.

Usage

Create an issue

Issue records must be created to begin working on a new feature or bug fix.

Issue

These records are instead used to group related development and aid in applying semantic versioning to solutions. The Development Hub does not replace a conventional issue tracker (e.g Azure Boards).

Set the Work Item ID field (in the Azure DevOps tab) and the commit or pull request will be linked to the work item.

Develop a solution

An issue with a To Do status will have a Develop button in the ribbon. Clicking this will create a development solution and transition the issue to In Progress. The Development tab will show details about the development solutions and solution merge history.

Development

The developer must add any new components or components to be modified into their development solution. Development solutions should contain just the components created or updated for that issue and no more. Adding all assets to a development solution will add all assets to the target solution when merged.

Only one developer should make changes to a component at a time. If a component appears in more than one development solution, it could result in either incomplete work being merged or solution merges failing due to missing dependencies. A warning will shown when approving a solution merge if there are potential conflicts with other development solutions.

Merge a solution

A Solution Merge record should be created when development is complete on an issue. This will transition the issue status reason to Developed.

Solution Merge

The solution merge is created in an Awaiting Review status. Comments can be as notes and the solution merge either approved or rejected.

An approved development solution will be merged into the target solution. If multiple solution merges have been approved, they will be queued. This means that an Approved solution merge will transition to either a Merging or Queued status. A Merged status will be reached when the solution merge has been committed to the target branch with a matching Solution-merge-id Git trailer in the commit message (this is automatically added).

When using the Pull request source control strategy, a pull request will be created automatically and the solution merge will transition to a status of Awaiting PR Merge.

A Feature issue will increment the minor version and a Bug issue will increment the patch version. Major version increments must be done manually.

Merge source code

If the solution to be merged has associated source code (e.g. you have made changes to plugin assemblies, web resources, tests or deployment logic) then you must provide the branch to be merged in the Source Branch field.

If your repository uses a Push source control strategy, ensure that you perform any manual Git merging required on your source branch before creating the solution merge or you may get merge conflicts that prevent the solution merge being committed. It is recommended to use a Pull request strategy for this reason.

Perform manual merge activities

Enabling the Manual Merge Activities field on the solution merge record will cause the merging process to pause before extracting and committing to source control. This is useful where you are merging changes by hand (e.g. where you need to delete components from the solution).

When the merging process is in a state where manual merge activities can begin, the solution merge will transition to an Awaiting Manual Merge Activities status. To notify the flow that the manual merge activities are complete, navigate to Action items -> Approvals within Power Automate and set the approval status to merged.

Handle a failed merge

If the merging process failed (e.g. due to missing dependencies) then the solution merge will transition to a Failed status. A note will be attached with a link to the failed flow run which can be used to diagnose the failure reason. A Retry button is available to retry the merge after the necessary steps have been taken.

In the example below, a dependency was missing from the target environment:

Failed Merge

Resources

Contributing

Refer to the contributing guide.