From 6f8c7f379a98a3297aad0ddb6bbfdb8c7fdf66b8 Mon Sep 17 00:00:00 2001 From: Alexander Holstrup <117829001+aholstrup1@users.noreply.github.com> Date: Mon, 24 Jun 2024 11:33:51 +0200 Subject: [PATCH] Fix all issues found by pre-commit and add a pre-commit check to PRs (#1112) This PR should go in after https://github.com/microsoft/AL-Go/pull/955 This PR: * Fixes all the issues found by the pre-commit hooks (by running `pre-commit run --all-files`) * Adds a check on future AL-Go PRs to ensure the pre-commit hooks have been run. --------- Co-authored-by: Freddy Kristiansen --- .github/dependabot.yml | 2 +- .github/workflows/Deploy.yaml | 2 +- .github/workflows/pre-commit.yml | 17 +++ Actions/AL-Go-Helper.ps1 | 2 +- Actions/AddExistingApp/README.md | 6 +- Actions/AnalyzeTests/README.md | 8 +- .../BuildPowerPlatform/BuildPowerPlatform.ps1 | 2 +- Actions/BuildPowerPlatform/README.md | 4 + Actions/BuildPowerPlatform/action.yaml | 10 +- ...ReferenceDocumentation.HelperFunctions.ps1 | 2 +- Actions/BuildReferenceDocumentation/README.md | 4 + Actions/CalculateArtifactNames/README.md | 5 + .../CheckForUpdates.HelperFunctions.ps1 | 2 +- Actions/CheckForUpdates/README.md | 6 +- Actions/CreateApp/README.md | 4 + .../CreateDevelopmentEnvironment/README.md | 6 +- Actions/CreateReleaseNotes/README.md | 5 + Actions/Deliver/README.md | 4 + Actions/Deploy/README.md | 4 + Actions/DeployPowerPlatform/README.md | 4 + Actions/DeployPowerPlatform/action.yaml | 4 +- Actions/DetermineArtifactUrl/README.md | 4 + Actions/DetermineDeliveryTargets/README.md | 4 + .../DetermineDeploymentEnvironments/README.md | 6 +- Actions/DetermineProjectsToBuild/README.md | 5 + Actions/DownloadProjectDependencies/README.md | 5 + Actions/DumpWorkflowInfo/README.md | 4 + Actions/GetArtifactsForDeployment/README.md | 6 + .../IncrementVersionNumber.psm1 | 2 +- Actions/IncrementVersionNumber/README.md | 6 +- Actions/Packages.json | 2 +- Actions/PipelineCleanup/README.md | 4 + Actions/PullPowerPlatformChanges/README.md | 5 +- Actions/PullPowerPlatformChanges/action.yaml | 2 +- .../PullRequestStatusCheck.ps1 | 2 +- Actions/PullRequestStatusCheck/README.md | 6 +- Actions/README.md | 2 + Actions/ReadPowerPlatformSettings/README.md | 5 + .../ReadPowerPlatformSettings.ps1 | 2 +- Actions/ReadSecrets/README.md | 10 +- Actions/ReadSettings/README.md | 7 +- Actions/RunPipeline/README.md | 9 +- Actions/SECURITY.md | 16 +-- Actions/Sign/README.md | 4 + Actions/Sign/Sign.psm1 | 2 +- Actions/Troubleshooting/README.md | 6 +- Actions/VerifyPRChanges/README.md | 4 + Actions/WorkflowInitialize/README.md | 5 + Actions/WorkflowPostProcess/README.md | 7 +- .../1st party apps/NewBcContainer.ps1 | 2 +- README.md | 45 +++--- RELEASENOTES.md | 128 ++++++++++++++---- SECURITY.md | 18 +-- Scenarios/AddAPerformanceTestApp.md | 18 +-- Scenarios/AddATestApp.md | 20 +-- Scenarios/AddPowerPlatformProject.md | 23 ++-- Scenarios/AppDependencies.md | 3 +- Scenarios/Codesigning.md | 18 ++- Scenarios/Contribute.md | 26 ++-- Scenarios/CreateOnlineDevEnv.md | 16 ++- Scenarios/CreateOnlineDevEnv2.md | 8 +- Scenarios/CreateRelease.md | 12 +- Scenarios/EnableKeyVaultForAppSourceApp.md | 7 +- Scenarios/EnablingTelemetry.md | 3 +- Scenarios/GetStarted.md | 28 ++-- .../MigrateFromAzureDevOpsWithHistory.md | 82 ++++++----- .../MigrateFromAzureDevOpsWithoutHistory.md | 67 +++++---- Scenarios/PublishToAppSource.md | 10 +- Scenarios/RegisterProductionEnvironment.md | 12 +- Scenarios/RegisterSandboxEnvironment.md | 20 +-- Scenarios/SelfHostedGitHubRunner.md | 32 +++-- Scenarios/SetupCiCdForExistingAppSourceApp.md | 24 ++-- Scenarios/SetupCiCdForExistingPTE.md | 14 +- Scenarios/SetupPowerPlatform.md | 8 +- .../SetupServicePrincipalForPowerPlatform.md | 5 +- Scenarios/TryPowerPlatformSamples.md | 39 +++--- Scenarios/UpdateAlGoSystemFiles.md | 26 ++-- Scenarios/UseAzureKeyVault.md | 6 +- Scenarios/settings.md | 84 +++++++----- Schema/algoreposettingssyntax.json | 2 +- Schema/algosettingssyntax.json | 2 +- .../.github/workflows/CreateRelease.yaml | 2 +- .../DeployReferenceDocumentation.yaml | 10 +- Templates/AppSource App/README.md | 1 + Templates/AppSource App/SECURITY.md | 16 +-- .../.github/workflows/CreateRelease.yaml | 2 +- .../DeployReferenceDocumentation.yaml | 10 +- Templates/Per Tenant Extension/README.md | 1 + Templates/Per Tenant Extension/SECURITY.md | 16 +-- Templates/README.md | 5 + Tests/DetermineArtifactUrl.Test.ps1 | 2 +- Tests/DetermineDeliveryTargets.Test.ps1 | 2 +- .../DetermineDeploymentEnvironments.Test.ps1 | 2 +- Tests/PullRequestStatusCheck.Test.ps1 | 2 +- ...-ABA81736-12D9-ED11-A7C7-000D3A991110.json | 2 +- .../FlowOnlySolution/other/Solution.xml | 2 +- .../src/TestApp/Connections/Connections.json | 2 +- .../DataSources/customers %28v2.0%29.json | 2 +- .../salesOrderLines %28v2.0%29.json | 2 +- .../DataSources/salesOrders %28v2.0%29.json | 2 +- .../PowerAppOnlySolution/other/Solution.xml | 2 +- .../src/TestApp/Connections/Connections.json | 2 +- .../DataSources/customers %28v2.0%29.json | 2 +- .../salesOrderLines %28v2.0%29.json | 2 +- .../DataSources/salesOrders %28v2.0%29.json | 2 +- ...-ABA81736-12D9-ED11-A7C7-000D3A991110.json | 2 +- .../StandardSolution/other/Solution.xml | 2 +- Tests/runtests.ps1 | 1 - Workshop/AddAnApp.md | 15 +- Workshop/AutomatedTests.md | 10 +- Workshop/ContinuousDelivery.md | 15 +- Workshop/ContinuousDeployment.md | 15 +- Workshop/Dependencies1.md | 14 +- Workshop/Dependencies2.md | 15 +- Workshop/Dependencies3.md | 1 + Workshop/DevelopmentEnvironments.md | 4 +- Workshop/GetStarted.md | 6 +- Workshop/Index.md | 4 +- Workshop/Introduction.md | 51 +++++-- Workshop/KeepUpToDate.md | 4 +- Workshop/PerformanceTesting.md | 6 +- Workshop/Prerequisites.md | 9 +- Workshop/Projects.md | 29 ++-- Workshop/PublishToProduction.md | 10 +- Workshop/ReferenceDoc.md | 13 +- Workshop/Releasing.md | 15 +- Workshop/ScheduledTestRuns.md | 12 +- Workshop/TheDevelopmentProcess.md | 4 +- Workshop/Versioning.md | 15 +- _config.yml | 2 +- e2eTests/RemoveRepositories.ps1 | 2 +- .../Workflows/RunAddExistingAppOrTestApp.ps1 | 2 +- e2eTests/Workflows/RunCICD.ps1 | 2 +- e2eTests/Workflows/RunCreateApp.ps1 | 2 +- .../RunCreateOnlineDevelopmentEnvironment.ps1 | 2 +- e2eTests/Workflows/RunCreateRelease.ps1 | 2 +- e2eTests/Workflows/RunCreateTestApp.ps1 | 2 +- .../RunDeployReferenceDocumentation.ps1 | 2 +- .../Workflows/RunIncrementVersionNumber.ps1 | 2 +- .../Workflows/RunPublishToEnvironment.ps1 | 2 +- e2eTests/Workflows/RunTestCurrent.ps1 | 2 +- e2eTests/Workflows/RunTestNextMajor.ps1 | 2 +- e2eTests/Workflows/RunTestNextMinor.ps1 | 2 +- .../My App.Test/.vscode/launch.json | 2 +- .../appsourceapp/My App/.vscode/launch.json | 2 +- e2eTests/pte/My App.Test/.vscode/launch.json | 2 +- e2eTests/pte/My App/.vscode/launch.json | 2 +- 147 files changed, 932 insertions(+), 522 deletions(-) create mode 100644 .github/workflows/pre-commit.yml diff --git a/.github/dependabot.yml b/.github/dependabot.yml index caa59a5c7..4a23c5461 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -18,4 +18,4 @@ updates: schedule: interval: weekly ignore: - - dependency-name: "microsoft/AL-Go-Actions/*" \ No newline at end of file + - dependency-name: "microsoft/AL-Go-Actions/*" diff --git a/.github/workflows/Deploy.yaml b/.github/workflows/Deploy.yaml index c3bf0c155..64f3edc5d 100644 --- a/.github/workflows/Deploy.yaml +++ b/.github/workflows/Deploy.yaml @@ -32,7 +32,7 @@ on: description: 'Which version of BcContainerHelper to use? (latest, preview, private, a specific version number or a direct download URL like https://github.com/freddydk/navcontainerhelper/archive/master.zip). Leave empty to use latest (or preview for preview branches)' required: false default: 'latest' - + permissions: contents: read actions: read diff --git a/.github/workflows/pre-commit.yml b/.github/workflows/pre-commit.yml new file mode 100644 index 000000000..0675e1934 --- /dev/null +++ b/.github/workflows/pre-commit.yml @@ -0,0 +1,17 @@ +name: pre-commit + +on: + push: + branches: [ "main" ] + pull_request: + branches: [ "main" ] + +jobs: + pre-commit: + runs-on: windows-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + - uses: pre-commit/action@v3.0.1 + with: + extra_args: --all-files diff --git a/Actions/AL-Go-Helper.ps1 b/Actions/AL-Go-Helper.ps1 index 3fffc3743..b518e4e28 100644 --- a/Actions/AL-Go-Helper.ps1 +++ b/Actions/AL-Go-Helper.ps1 @@ -2367,4 +2367,4 @@ function Get-PackageVersion($PackageName) { else { throw "Package $PackageName is not in the list of packages" } -} \ No newline at end of file +} diff --git a/Actions/AddExistingApp/README.md b/Actions/AddExistingApp/README.md index d0bcf21e9..2596a7245 100644 --- a/Actions/AddExistingApp/README.md +++ b/Actions/AddExistingApp/README.md @@ -1,12 +1,15 @@ # Add existing app + Add an existing app to an AL-Go for GitHub repository ## INPUT ### ENV variables + none ### Parameters + | Name | Required | Description | Default value | | :-- | :-: | :-- | :-- | | shell | | The shell (powershell or pwsh) in which the PowerShell script in this action should run | powershell | @@ -19,4 +22,5 @@ none | directCommit | | true if the action should create a direct commit against the branch or false to create a Pull Request | false | ## OUTPUT -none \ No newline at end of file + +none diff --git a/Actions/AnalyzeTests/README.md b/Actions/AnalyzeTests/README.md index 0e5dbd11f..48990379a 100644 --- a/Actions/AnalyzeTests/README.md +++ b/Actions/AnalyzeTests/README.md @@ -1,12 +1,15 @@ # Analyze Tests + Analyze results of tests from the RunPipeline action ## INPUT ### ENV variables + none ### Parameters + | Name | Required | Description | Default value | | :-- | :-: | :-- | :-- | | shell | | The shell (powershell or pwsh) in which the PowerShell script in this action should run | powershell | @@ -16,12 +19,15 @@ none ## OUTPUT ### ENV variables + none ### OUTPUT variables + | Name | Description | | :-- | :-- | -| TestResultMD | MarkDown of the test result with \n instead of line breaks | +| TestResultMD | MarkDown of the test result with \\n instead of line breaks | ### SUMMARY + This function will set the test result markdown in the GITHUB_STEP_SUMMARY section diff --git a/Actions/BuildPowerPlatform/BuildPowerPlatform.ps1 b/Actions/BuildPowerPlatform/BuildPowerPlatform.ps1 index 511405849..9c999e36e 100644 --- a/Actions/BuildPowerPlatform/BuildPowerPlatform.ps1 +++ b/Actions/BuildPowerPlatform/BuildPowerPlatform.ps1 @@ -271,4 +271,4 @@ if ($environmentName -and $companyId) { } else { Write-Host "Skip Business Central connection settings update since EnvironmentName and CompanyId are not set" -} \ No newline at end of file +} diff --git a/Actions/BuildPowerPlatform/README.md b/Actions/BuildPowerPlatform/README.md index 9024460d5..ba0ca100d 100644 --- a/Actions/BuildPowerPlatform/README.md +++ b/Actions/BuildPowerPlatform/README.md @@ -1,12 +1,15 @@ # Build Power Platform + Build the Power Platform solution ## INPUT ### ENV variables + none ### Parameters + | Name | Required | Description | Default value | | :-- | :-: | :-- | :-- | | shell | | The shell (powershell or pwsh) in which the PowerShell script in this action should run | powershell | @@ -19,4 +22,5 @@ none | appRevision | | The app revision number | | ## OUTPUT + none diff --git a/Actions/BuildPowerPlatform/action.yaml b/Actions/BuildPowerPlatform/action.yaml index 463504097..3fef03051 100644 --- a/Actions/BuildPowerPlatform/action.yaml +++ b/Actions/BuildPowerPlatform/action.yaml @@ -37,12 +37,12 @@ runs: - name: Install Power Platform Tools uses: microsoft/powerplatform-actions/actions-install@v1 - - name: Update Power Platform Files + - name: Update Power Platform Files shell: ${{ inputs.shell }} env: _solutionFolder: ${{ inputs.solutionFolder }} _companyId: ${{ inputs.companyId }} - _environmentName: ${{ inputs.environmentName }} + _environmentName: ${{ inputs.environmentName }} _appBuild: ${{ inputs.appBuild }} _appRevision: ${{ inputs.appRevision }} run: | @@ -53,7 +53,7 @@ runs: catch { Write-Host "::ERROR::Unexpected error when running action. Error Message: $($_.Exception.Message.Replace("`r",'').Replace("`n",' ')), StackTrace: $($_.ScriptStackTrace.Replace("`r",'').Replace("`n",' <- '))"; exit 1 - } + } - name: Test Pack (Not real - just workaround for https://github.com/microsoft/powerplatform-vscode/issues/412) uses: microsoft/powerplatform-actions/pack-solution@v1 @@ -74,7 +74,7 @@ runs: solution-folder: ${{ inputs.solutionFolder }} solution-type: "Unmanaged" process-canvas-apps: true - + branding: icon: terminal - color: blue \ No newline at end of file + color: blue diff --git a/Actions/BuildReferenceDocumentation/BuildReferenceDocumentation.HelperFunctions.ps1 b/Actions/BuildReferenceDocumentation/BuildReferenceDocumentation.HelperFunctions.ps1 index b68c6195b..733fc5345 100644 --- a/Actions/BuildReferenceDocumentation/BuildReferenceDocumentation.HelperFunctions.ps1 +++ b/Actions/BuildReferenceDocumentation/BuildReferenceDocumentation.HelperFunctions.ps1 @@ -295,4 +295,4 @@ function CalculateProjectsAndApps { } $allApps } -} \ No newline at end of file +} diff --git a/Actions/BuildReferenceDocumentation/README.md b/Actions/BuildReferenceDocumentation/README.md index bb6fea67e..3bd908390 100644 --- a/Actions/BuildReferenceDocumentation/README.md +++ b/Actions/BuildReferenceDocumentation/README.md @@ -1,14 +1,17 @@ # BuildReferenceDocumentation + Build documentation using [ALDoc](https://go.microsoft.com/fwlink/?linkid=2247728) and [DocFx](https://dotnet.github.io/docfx) ## INPUT ### ENV variables + | Name | Description | | :-- | :-- | | Settings | env.Settings must be set by a prior call to the ReadSettings Action | ### Parameters + | Name | Required | Description | Default value | | :-- | :-: | :-- | :-- | | shell | | The shell (powershell or pwsh) in which the PowerShell script in this action should run | powershell | @@ -16,4 +19,5 @@ Build documentation using [ALDoc](https://go.microsoft.com/fwlink/?linkid=224772 | artifacts | Yes | The artifacts to build documentation for or a folder in which the artifacts have been downloaded | | ## OUTPUT + none diff --git a/Actions/CalculateArtifactNames/README.md b/Actions/CalculateArtifactNames/README.md index 807f5575b..ad611a400 100644 --- a/Actions/CalculateArtifactNames/README.md +++ b/Actions/CalculateArtifactNames/README.md @@ -1,14 +1,17 @@ # Calculate Artifact Names + Calculate Artifact Names for AL-Go workflows ## INPUT ### ENV variables + | Name | Description | | :-- | :-- | | Settings | env.Settings must be set by a prior call to the ReadSettings Action | ### Parameters + | Name | Required | Description | Default value | | :-- | :-: | :-- | :-- | | shell | | The shell (powershell or pwsh) in which the PowerShell script in this action should run | powershell | @@ -19,9 +22,11 @@ Calculate Artifact Names for AL-Go workflows ## OUTPUT ### ENV variables + none ### OUTPUT variables + | Name | Description | | :-- | :-- | | ThisBuildAppsArtifactsName | Artifact name for apps being built in the current workflow run | diff --git a/Actions/CheckForUpdates/CheckForUpdates.HelperFunctions.ps1 b/Actions/CheckForUpdates/CheckForUpdates.HelperFunctions.ps1 index 4c1956b5c..981e5aa19 100644 --- a/Actions/CheckForUpdates/CheckForUpdates.HelperFunctions.ps1 +++ b/Actions/CheckForUpdates/CheckForUpdates.HelperFunctions.ps1 @@ -426,4 +426,4 @@ function UpdateSettingsFile { } # Save the file with LF line endings and UTF8 encoding $settings | Set-JsonContentLF -path $settingsFile -} \ No newline at end of file +} diff --git a/Actions/CheckForUpdates/README.md b/Actions/CheckForUpdates/README.md index 312e86d64..554ca9db5 100644 --- a/Actions/CheckForUpdates/README.md +++ b/Actions/CheckForUpdates/README.md @@ -1,12 +1,15 @@ # Check for updates + Check for updates to AL-Go system files and perform the update if requested ## INPUT ### ENV variables + none ### Parameters + | Name | Required | Description | Default value | | :-- | :-: | :-- | :-- | | shell | | The shell (powershell or pwsh) in which the PowerShell script in this action should run | powershell | @@ -19,4 +22,5 @@ none | directCommit | | True if the action should create a direct commit against the branch or false to create a Pull Request | false | ## OUTPUT -none \ No newline at end of file + +none diff --git a/Actions/CreateApp/README.md b/Actions/CreateApp/README.md index 40dd514d5..56876142b 100644 --- a/Actions/CreateApp/README.md +++ b/Actions/CreateApp/README.md @@ -1,12 +1,15 @@ # Create a new app + Create a new app and add it to an AL-Go repository ## INPUT ### ENV variables + none ### Parameters + | Name | Required | Description | Default value | | :-- | :-: | :-- | :-- | | shell | | The shell (powershell or pwsh) in which the PowerShell script in this action should run | powershell | @@ -24,4 +27,5 @@ none | directCommit | | true if the action should create a direct commit against the branch or false to create a Pull Request | false | ## OUTPUT + none diff --git a/Actions/CreateDevelopmentEnvironment/README.md b/Actions/CreateDevelopmentEnvironment/README.md index 27e2a4175..c26ebd2db 100644 --- a/Actions/CreateDevelopmentEnvironment/README.md +++ b/Actions/CreateDevelopmentEnvironment/README.md @@ -1,12 +1,15 @@ # Create Development Environment + Create an online development environment ## INPUT ### ENV variables + none ### Parameters + | Name | Required | Description | Default value | | :-- | :-: | :-- | :-- | | shell | | The shell (powershell or pwsh) in which the PowerShell script in this action should run | powershell | @@ -21,4 +24,5 @@ none | directCommit | | true if the action should create a direct commit against the branch or false to create a Pull Request | false | ## OUTPUT -none \ No newline at end of file + +none diff --git a/Actions/CreateReleaseNotes/README.md b/Actions/CreateReleaseNotes/README.md index 72c82f3e5..7bc6f629b 100644 --- a/Actions/CreateReleaseNotes/README.md +++ b/Actions/CreateReleaseNotes/README.md @@ -1,12 +1,15 @@ # Creates release notes + Creates release notes for a release, based on a given tag and the tag from the latest release ## INPUT ### ENV variables + none ### Parameters + | Name | Required | Description | Default value | | :-- | :-: | :-- | :-- | | shell | | The shell (powershell or pwsh) in which the PowerShell script in this action should run | powershell | @@ -18,9 +21,11 @@ none ## OUTPUT ### ENV variables + none ### OUTPUT variables + | Name | Description | | :-- | :-- | | ReleaseVersion | The release version | diff --git a/Actions/Deliver/README.md b/Actions/Deliver/README.md index f6ae1efca..aa9726e38 100644 --- a/Actions/Deliver/README.md +++ b/Actions/Deliver/README.md @@ -1,15 +1,18 @@ # Deliver + Deliver App to deliveryTarget (AppSource, Storage, or...) ## INPUT ### ENV variables + | Name | Description | | :-- | :-- | | Settings | env.Settings must be set by a prior call to the ReadSettings Action | | Secrets | env.Secrets with delivery target context secrets must be read by a prior call to the ReadSecrets Action | ### Parameters + | Name | Required | Description | Default value | | :-- | :-: | :-- | :-- | | shell | | The shell (powershell or pwsh) in which the PowerShell script in this action should run | powershell | @@ -24,4 +27,5 @@ Deliver App to deliveryTarget (AppSource, Storage, or...) | goLive | | Only relevant for AppSource delivery type. Promote AppSource App to Go Live? | false | ## OUTPUT + none diff --git a/Actions/Deploy/README.md b/Actions/Deploy/README.md index 099be6404..f08c9bdbb 100644 --- a/Actions/Deploy/README.md +++ b/Actions/Deploy/README.md @@ -1,9 +1,11 @@ # Deploy + Deploy Apps to online environment ## INPUT ### ENV variables + | Name | Description | | :-- | :-- | | Settings | env.Settings must be set by a prior call to the ReadSettings Action | @@ -11,6 +13,7 @@ Deploy Apps to online environment | deviceCode | When deploying to a single environment which doesn't have an AuthContext, we will wait for the user to finalize the deviceflow with this deviceCode | ### Parameters + | Name | Required | Description | Default value | | :-- | :-: | :-- | :-- | | shell | | The shell (powershell or pwsh) in which the PowerShell script in this action should run | powershell | @@ -21,6 +24,7 @@ Deploy Apps to online environment | deploymentEnvironmentsJson | Yes | The settings for all Deployment Environments | | ## OUTPUT + | Name | Description | | :-- | :-- | | environmentUrl | The URL for the environment. This URL is presented in the Deploy Step in summary under the environment name | diff --git a/Actions/DeployPowerPlatform/README.md b/Actions/DeployPowerPlatform/README.md index 37958ae72..25ed24154 100644 --- a/Actions/DeployPowerPlatform/README.md +++ b/Actions/DeployPowerPlatform/README.md @@ -1,15 +1,18 @@ # Deploy Power Platform + Deploy the Power Platform solution from the artifacts folder ## INPUT ### ENV variables + | Name | Description | | :-- | :-- | | Settings | env.Settings must be set by a prior call to the ReadSettings Action | | Secrets | env.Secrets with delivery target context secrets must be read by a prior call to the ReadSecrets Action | ### Parameters + | Name | Required | Description | Default value | | :-- | :-: | :-- | :-- | | shell | | The shell (powershell or pwsh) in which the PowerShell script in this action should run | powershell | @@ -21,6 +24,7 @@ Deploy the Power Platform solution from the artifacts folder Either artifactsFolder or solutionFolder needs to be specified ## OUTPUT + | Name | Description | | :-- | :-- | | environmentUrl | The URL for the environment. This URL is presented in the Deploy Step in summary under the environment name | diff --git a/Actions/DeployPowerPlatform/action.yaml b/Actions/DeployPowerPlatform/action.yaml index 90a9f0126..88d0481b1 100644 --- a/Actions/DeployPowerPlatform/action.yaml +++ b/Actions/DeployPowerPlatform/action.yaml @@ -52,7 +52,7 @@ runs: uses: ./_AL-Go/Actions/ReadPowerPlatformSettings with: shell: ${{ inputs.shell }} - deploymentEnvironmentsJson: ${{ inputs.deploymentEnvironmentsJson }} + deploymentEnvironmentsJson: ${{ inputs.deploymentEnvironmentsJson }} environmentName: ${{ inputs.environmentName }} - name: Determine Power Platform solution location @@ -69,7 +69,7 @@ runs: Write-Host "::ERROR::Unexpected error when running action. Error Message: $($_.Exception.Message.Replace("`r",'').Replace("`n",' ')), StackTrace: $($_.ScriptStackTrace.Replace("`r",'').Replace("`n",' <- '))"; exit 1 } - + - name: Unpack solution artifact if: env.powerPlatformSolutionFilePath != '' uses: microsoft/powerplatform-actions/unpack-solution@v1 diff --git a/Actions/DetermineArtifactUrl/README.md b/Actions/DetermineArtifactUrl/README.md index 82edf8ec3..21f7d77c9 100644 --- a/Actions/DetermineArtifactUrl/README.md +++ b/Actions/DetermineArtifactUrl/README.md @@ -1,14 +1,17 @@ # Determine artifactUrl + Determines the artifactUrl to use for a given project ## INPUT ### ENV variables + | Name | Description | | :-- | :-- | | Settings | env.Settings must be set by a prior call to the ReadSettings Action | ### Parameters + | Name | Required | Description | Default value | | :-- | :-: | :-- | :-- | | shell | | The shell (powershell or pwsh) in which the PowerShell script in this action should run | powershell | @@ -18,6 +21,7 @@ Determines the artifactUrl to use for a given project ## OUTPUT ### ENV variables + | Name | Description | | :-- | :-- | | artifact | The ArtifactUrl to use for the build | diff --git a/Actions/DetermineDeliveryTargets/README.md b/Actions/DetermineDeliveryTargets/README.md index 4ce95f0d6..138aea6f4 100644 --- a/Actions/DetermineDeliveryTargets/README.md +++ b/Actions/DetermineDeliveryTargets/README.md @@ -1,15 +1,18 @@ # Determine Delivery Targets + Determines the delivery targets to use for the build ## INPUT ### ENV variables + | Name | Description | | :-- | :-- | | Settings | env.Settings must be set by a prior call to the ReadSettings Action | | Secrets | env.Secrets with delivery target context secrets must be read by a prior call to the ReadSecrets Action (if checkContextSecrets is set to Y) | ### Parameters + | Name | Required | Description | Default value | | :-- | :-: | :-- | :-- | | shell | | The shell (powershell or pwsh) in which the PowerShell script in this action should run | powershell | @@ -17,6 +20,7 @@ Determines the delivery targets to use for the build | checkContextSecrets | | Determines whether to check that delivery targets have a corresponding context secret defined | true | ## OUTPUT + | Name | Description | | :-- | :-- | | deliveryTargets | Compressed JSON array containing all delivery targets to use for the build | diff --git a/Actions/DetermineDeploymentEnvironments/README.md b/Actions/DetermineDeploymentEnvironments/README.md index 717a6def4..2a34e96c9 100644 --- a/Actions/DetermineDeploymentEnvironments/README.md +++ b/Actions/DetermineDeploymentEnvironments/README.md @@ -1,22 +1,26 @@ # Determine Deployment Environments + Determines the environments to be used for a build or a publish ## INPUT ### ENV variables + | Name | Description | | :-- | :-- | | Settings | env.Settings must be set by a prior call to the ReadSettings Action | | GITHUB_TOKEN | GITHUB_TOKEN must be set as an environment variable when calling this action | ### Parameters + | Name | Required | Description | Default value | | :-- | :-: | :-- | :-- | | shell | | The shell (powershell or pwsh) in which the PowerShell script in this action should run | powershell | -| getEnvironments | Yes | Specifies the pattern of the environments you want to retrieve (* for all) | | +| getEnvironments | Yes | Specifies the pattern of the environments you want to retrieve (\* for all) | | | type | Yes | Type of deployment to get environments for (CD, Publish or All) | | ## OUTPUT + | EnvironmentsMatrixJson | The Environment matrix to use for the Deploy step in compressed JSON format | | DeploymentEnvironmentsJson | Deployment Environments with settings in compressed JSON format | | EnvironmentCount | Number of Deployment Environments | diff --git a/Actions/DetermineProjectsToBuild/README.md b/Actions/DetermineProjectsToBuild/README.md index b24526642..8304dc16d 100644 --- a/Actions/DetermineProjectsToBuild/README.md +++ b/Actions/DetermineProjectsToBuild/README.md @@ -1,4 +1,5 @@ # Determine projects to build + Scans for AL-Go projects and determines which one to build The action also computes build dimensions, based on the projects and the build modes for each of them @@ -6,9 +7,11 @@ The action also computes build dimensions, based on the projects and the build m ## INPUT ### ENV variables + none ### Parameters + | Name | Required | Description | Default value | | :-- | :-: | :-- | :-- | | shell | | The shell (powershell or pwsh) in which the PowerShell script in this action should run | powershell | @@ -18,9 +21,11 @@ none ## OUTPUT ### ENV variables + none ### OUTPUT variables + | Name | Description | | :-- | :-- | | ProjectsJson | An array of AL-Go projects in compressed JSON format | diff --git a/Actions/DownloadProjectDependencies/README.md b/Actions/DownloadProjectDependencies/README.md index 24774fb61..4d4b3bbdd 100644 --- a/Actions/DownloadProjectDependencies/README.md +++ b/Actions/DownloadProjectDependencies/README.md @@ -1,4 +1,5 @@ # Download project dependencies + Downloads artifacts from AL-Go projects, that are dependencies of a given AL-Go project The action constructs arrays of paths to .app files, that are dependencies of the apps in an AL-Go project @@ -6,12 +7,14 @@ The action constructs arrays of paths to .app files, that are dependencies of th ## INPUT ### ENV variables + | Name | Description | | :-- | :-- | | Settings | env.Settings must be set by a prior call to the ReadSettings Action | | Secrets | env.Secrets must be read by a prior call to the ReadSecrets Action with appDependencyProbingPathsSecrets in getSecrets | ### Parameters + | Name | Required | Description | Default value | | :-- | :-: | :-- | :-- | | shell | | The shell (powershell or pwsh) in which the PowerShell script in this action should run | powershell | @@ -23,6 +26,7 @@ The action constructs arrays of paths to .app files, that are dependencies of th ## OUTPUT ### ENV variables + | Name | Description | | :-- | :-- | | appFolders | A JSON-formatted array of appFolders | @@ -30,6 +34,7 @@ The action constructs arrays of paths to .app files, that are dependencies of th | bcptTestFolders | A JSON-formatted array of bcptTestFolders | ### OUTPUT variables + | Name | Description | | :-- | :-- | | DownloadedApps | A JSON-formatted list of paths to .app files, that dependencies of the apps | diff --git a/Actions/DumpWorkflowInfo/README.md b/Actions/DumpWorkflowInfo/README.md index 83a023e30..275eefc91 100644 --- a/Actions/DumpWorkflowInfo/README.md +++ b/Actions/DumpWorkflowInfo/README.md @@ -1,15 +1,19 @@ # Dump Workflow Info + Dump workflow info ## INPUT ### ENV variables + none ### Parameters + | Name | Required | Description | Default value | | :-- | :-: | :-- | :-- | | shell | | The shell (powershell or pwsh) in which the PowerShell script in this action should run | powershell | ## OUTPUT + none diff --git a/Actions/GetArtifactsForDeployment/README.md b/Actions/GetArtifactsForDeployment/README.md index 34eb67502..40d153eee 100644 --- a/Actions/GetArtifactsForDeployment/README.md +++ b/Actions/GetArtifactsForDeployment/README.md @@ -1,12 +1,15 @@ # Get artifacts for deployment + Download artifacts for deployment ## INPUT ### ENV variables + none ### Parameters + | Name | Required | Description | Default value | | :-- | :-: | :-- | :-- | | shell | | The shell (powershell or pwsh) in which the PowerShell script in this action should run | powershell | @@ -15,10 +18,13 @@ none | artifactsFolder | Yes | Folder in which the artifacts will be downloaded | | ## OUTPUT + none ### ENV variables + none ### OUTPUT variables + none diff --git a/Actions/IncrementVersionNumber/IncrementVersionNumber.psm1 b/Actions/IncrementVersionNumber/IncrementVersionNumber.psm1 index 40179d269..02f0b15c2 100644 --- a/Actions/IncrementVersionNumber/IncrementVersionNumber.psm1 +++ b/Actions/IncrementVersionNumber/IncrementVersionNumber.psm1 @@ -258,4 +258,4 @@ function Set-PowerPlatformSolutionVersion { } } -Export-ModuleMember -Function Set-VersionInSettingsFile, Set-VersionInAppManifests, Set-DependenciesVersionInAppManifests, Set-PowerPlatformSolutionVersion \ No newline at end of file +Export-ModuleMember -Function Set-VersionInSettingsFile, Set-VersionInAppManifests, Set-DependenciesVersionInAppManifests, Set-PowerPlatformSolutionVersion diff --git a/Actions/IncrementVersionNumber/README.md b/Actions/IncrementVersionNumber/README.md index cdfcaaf76..c5145fd3e 100644 --- a/Actions/IncrementVersionNumber/README.md +++ b/Actions/IncrementVersionNumber/README.md @@ -1,24 +1,28 @@ # Increment version number + Increment version number in AL-Go repository ## INPUT ### ENV variables + | Name | Description | | :-- | :-- | | Settings | env.Settings must be set by a prior call to the ReadSettings Action | ### Parameters + | Name | Required | Description | Default value | | :-- | :-: | :-- | :-- | | shell | | The shell (powershell or pwsh) in which the PowerShell script in this action should run | powershell | | actor | | The GitHub actor running the action | github.actor | | token | | The GitHub token running the action | github.token | | parentTelemetryScopeJson | | Specifies the parent telemetry scope for the telemetry signal | {} | -| projects | | List of project names if the repository is setup for multiple projects (* for all projects) | * | +| projects | | List of project names if the repository is setup for multiple projects (\* for all projects) | * | | versionNumber | Yes | The version to update to. Use Major.Minor for absolute change, use +1 to bump to the next major version, use +0.1 to bump to the next minor version | | | updateBranch | | Which branch should the app be added to | github.ref_name | | directCommit | | true if the action should create a direct commit against the branch or false to create a Pull Request | false | ## OUTPUT + none diff --git a/Actions/Packages.json b/Actions/Packages.json index d2a594537..62f06803c 100644 --- a/Actions/Packages.json +++ b/Actions/Packages.json @@ -1,3 +1,3 @@ { "sign": "0.9.1-beta.24123.2" -} \ No newline at end of file +} diff --git a/Actions/PipelineCleanup/README.md b/Actions/PipelineCleanup/README.md index cc43a112d..3aebd268f 100644 --- a/Actions/PipelineCleanup/README.md +++ b/Actions/PipelineCleanup/README.md @@ -1,12 +1,15 @@ # Pipeline Cleanup + Perform cleanup after running pipeline in AL-Go repository ## INPUT ### ENV variables + none ### Parameters + | Name | Required | Description | Default value | | :-- | :-: | :-- | :-- | | shell | | The shell (powershell or pwsh) in which the PowerShell script in this action should run | powershell | @@ -14,4 +17,5 @@ none | project | | Project name if the repository is setup for multiple projects | . | ## OUTPUT + none diff --git a/Actions/PullPowerPlatformChanges/README.md b/Actions/PullPowerPlatformChanges/README.md index 5bfa3a178..4230494a4 100644 --- a/Actions/PullPowerPlatformChanges/README.md +++ b/Actions/PullPowerPlatformChanges/README.md @@ -1,15 +1,18 @@ # Pull Power Platform Changes + Pull the Power Platform solution from the specified Power Platform environment ## INPUT ### ENV variables + | Name | Description | | :-- | :-- | | Settings | env.Settings must be set by a prior call to the ReadSettings Action | | Secrets | env.Secrets with delivery target context secrets must be read by a prior call to the ReadSecrets Action | ### Parameters + | Name | Required | Description | Default value | | :-- | :-: | :-- | :-- | | shell | | The shell (powershell or pwsh) in which the PowerShell script in this action should run | powershell | @@ -21,10 +24,10 @@ Pull the Power Platform solution from the specified Power Platform environment | updateBranch | | The branch to update | github.ref_name | | directCommit | | true if the action should create a direct commit against the branch or false to create a Pull Request | false | - Either artifactsFolder or solutionFolder needs to be specified ## OUTPUT + | Name | Description | | :-- | :-- | | environmentUrl | The URL for the environment. This URL is presented in the Deploy Step in summary under the environment name | diff --git a/Actions/PullPowerPlatformChanges/action.yaml b/Actions/PullPowerPlatformChanges/action.yaml index 38f06002d..5d928e109 100644 --- a/Actions/PullPowerPlatformChanges/action.yaml +++ b/Actions/PullPowerPlatformChanges/action.yaml @@ -64,7 +64,7 @@ runs: uses: ./_AL-Go/Actions/ReadPowerPlatformSettings with: shell: ${{ inputs.shell }} - deploymentEnvironmentsJson: ${{ inputs.deploymentEnvironmentsJson }} + deploymentEnvironmentsJson: ${{ inputs.deploymentEnvironmentsJson }} environmentName: ${{ inputs.environmentName }} - name: Set up new branch for changes diff --git a/Actions/PullRequestStatusCheck/PullRequestStatusCheck.ps1 b/Actions/PullRequestStatusCheck/PullRequestStatusCheck.ps1 index bd0cf737f..0ddeadab4 100644 --- a/Actions/PullRequestStatusCheck/PullRequestStatusCheck.ps1 +++ b/Actions/PullRequestStatusCheck/PullRequestStatusCheck.ps1 @@ -17,4 +17,4 @@ } PullRequestStatusCheck -Repository $env:GITHUB_REPOSITORY -RunId $env:GITHUB_RUN_ID -Write-Host "PR Build succeeded" \ No newline at end of file +Write-Host "PR Build succeeded" diff --git a/Actions/PullRequestStatusCheck/README.md b/Actions/PullRequestStatusCheck/README.md index 11fede4de..cb761b2cb 100644 --- a/Actions/PullRequestStatusCheck/README.md +++ b/Actions/PullRequestStatusCheck/README.md @@ -1,17 +1,21 @@ # Pull Request Status Check + Check the status of a pull request build and fail the build if any jobs have failed. ## INPUT ### ENV variables + | Name | Description | | :-- | :-- | | GITHUB_TOKEN | GITHUB_TOKEN must be set as an environment variable when calling this action | ### Parameters + | Name | Required | Description | Default value | | :-- | :-: | :-- | :-- | | shell | | The shell (powershell or pwsh) in which the PowerShell script in this action should run | powershell | ## OUTPUT -none \ No newline at end of file + +none diff --git a/Actions/README.md b/Actions/README.md index c2d11a494..22c434b08 100644 --- a/Actions/README.md +++ b/Actions/README.md @@ -1,9 +1,11 @@ # AL-Go Actions + This repository contains a set of GitHub actions used by the AL-Go for GitHub templates. Please go to https://aka.ms/AL-Go to learn more. ## Actions + | Name | Description | | :-- | :-- | | [Add existing app](AddExistingApp) | Add an existing app to an AL-Go for GitHub repository | diff --git a/Actions/ReadPowerPlatformSettings/README.md b/Actions/ReadPowerPlatformSettings/README.md index 199bb0da1..c5f7324be 100644 --- a/Actions/ReadPowerPlatformSettings/README.md +++ b/Actions/ReadPowerPlatformSettings/README.md @@ -1,15 +1,18 @@ # Read Power Platform Settings + Read settings for Power Platform deployment from settings and secrets ## INPUT ### ENV variables + | Name | Description | | :-- | :-- | | Settings | env.Settings must be set by a prior call to the ReadSettings Action | | Secrets | env.Secrets with delivery target context secrets must be read by a prior call to the ReadSecrets Action | ### Parameters + | Name | Required | Description | Default value | | :-- | :-: | :-- | :-- | | shell | | The shell (powershell or pwsh) in which the PowerShell script in this action should run | powershell | @@ -19,9 +22,11 @@ Read settings for Power Platform deployment from settings and secrets ## OUTPUT ### ENV variables + none ### OUTPUT variables + | Name | Description | | :-- | :-- | | ppEnvironmentUrl | Power Platform Environment URL | diff --git a/Actions/ReadPowerPlatformSettings/ReadPowerPlatformSettings.ps1 b/Actions/ReadPowerPlatformSettings/ReadPowerPlatformSettings.ps1 index 8df001acd..dccab375e 100644 --- a/Actions/ReadPowerPlatformSettings/ReadPowerPlatformSettings.ps1 +++ b/Actions/ReadPowerPlatformSettings/ReadPowerPlatformSettings.ps1 @@ -58,4 +58,4 @@ foreach($secretName in "$($envName)-AuthContext","$($envName)_AuthContext","Auth # Verify the authentication context has been set if ($null -eq $authContext) { throw "Unable to find authentication context for GitHub environment $envName in secrets" -} \ No newline at end of file +} diff --git a/Actions/ReadSecrets/README.md b/Actions/ReadSecrets/README.md index d67b2c9c0..f2aff30f0 100644 --- a/Actions/ReadSecrets/README.md +++ b/Actions/ReadSecrets/README.md @@ -1,18 +1,21 @@ # Read secrets + Read secrets from GitHub secrets or Azure Keyvault for AL-Go workflows The secrets read and added to the output are the secrets specified in the getSecrets parameter Additionally, the secrets specified by the authToken secret in AppDependencyProbingPaths are read if appDependencyProbingPathsSecrets is specified in getSecrets All secrets included in the Secrets output are Base64 encoded to avoid issues with national characters -Secrets, which name is preceded by an asterisk (*) are encrypted and Base64 encoded +Secrets, which name is preceded by an asterisk (\*) are encrypted and Base64 encoded ## INPUT ### ENV variables + | Name | Description | | :-- | :-- | | Settings | env.Settings must be set by a prior call to the ReadSettings Action | ### Parameters + | Name | Required | Description | Default value | | :-- | :-: | :-- | :-- | | shell | | The shell (powershell or pwsh) in which the PowerShell script in this action should run | powershell | @@ -23,11 +26,12 @@ Secrets, which name is preceded by an asterisk (*) are encrypted and Base64 enco ## OUTPUT ### ENV variables + none ### OUTPUT variables + | Name | Description | | :-- | :-- | -| Secrets | A compressed json construct with all requested secrets base64 encoded. Secrets preceded by an asterisk (*) are encrypted before base64 encoding. The secret value + the base64 value of the secret value are masked in the log | +| Secrets | A compressed json construct with all requested secrets base64 encoded. Secrets preceded by an asterisk (\*) are encrypted before base64 encoding. The secret value + the base64 value of the secret value are masked in the log | | TokenForPush | The token to use when workflows are pushing changes (either directly, or via pull requests). This is either the GITHUB_TOKEN or the GhTokenWorkflow secret (based on the env variable useGhTokenWorkflowForPush) | - diff --git a/Actions/ReadSettings/README.md b/Actions/ReadSettings/README.md index 5f76261b7..d947db09f 100644 --- a/Actions/ReadSettings/README.md +++ b/Actions/ReadSettings/README.md @@ -1,12 +1,15 @@ # Read settings + Read settings for AL-Go workflows ## INPUT ### ENV variables + none ### Parameters + | Name | Required | Description | Default value | | :-- | :-: | :-- | :-- | | shell | | The shell (powershell or pwsh) in which the PowerShell script in this action should run | powershell | @@ -16,14 +19,16 @@ none ## OUTPUT ### ENV variables + | Name | Description | | :-- | :-- | | Settings | A compressed JSON structure with ALL AL-Go settings, independent of the get parameter. If project was not specified, this will only include repository settings. | -> [!NOTE] +> \[!NOTE\] > This method creates individual environment variables for every setting specified in the get parameter. ### OUTPUT variables + | Name | Description | | :-- | :-- | | GitHubRunnerJson | GitHubRunner in compressed Json format | diff --git a/Actions/RunPipeline/README.md b/Actions/RunPipeline/README.md index bd1955ee2..6eec53766 100644 --- a/Actions/RunPipeline/README.md +++ b/Actions/RunPipeline/README.md @@ -1,15 +1,18 @@ # Run pipeline + Run pipeline in AL-Go repository ## INPUT ### ENV variables + | Name | Description | | :-- | :-- | | Settings | env.Settings must be set by a prior call to the ReadSettings Action | | Secrets | env.Secrets with licenseFileUrl, codeSignCertificateUrl, codeSignCertificatePassword, keyVaultCertificateUrl, keyVaultCertificatePassword, keyVaultClientId, gitHubPackagesContext, applicationInsightsConnectionString must be read by a prior call to the ReadSecets Action | ### Parameters + | Name | Required | Description | Default value | | :-- | :-: | :-- | :-- | | shell | | The shell (powershell or pwsh) in which the PowerShell script in this action should run | powershell | @@ -18,15 +21,17 @@ Run pipeline in AL-Go repository | artifact | | ArtifactUrl to use for the build | settings.artifact | | project | | Project name if the repository is setup for multiple projects | . | | buildMode | | Specifies a mode to use for the build steps | Default | -| installAppsJson | | A JSON-formatted list of apps to install | [] | -| installTestAppsJson | | A JSON-formatted list of test apps to install | [] | +| installAppsJson | | A JSON-formatted list of apps to install | \[\] | +| installTestAppsJson | | A JSON-formatted list of test apps to install | \[\] | ## OUTPUT ## ENV variables + | Name | Description | | :-- | :-- | | containerName | Container name of a container used during build | ## OUTPUT variables + none diff --git a/Actions/SECURITY.md b/Actions/SECURITY.md index a050f362c..9657262ba 100644 --- a/Actions/SECURITY.md +++ b/Actions/SECURITY.md @@ -4,7 +4,7 @@ Microsoft takes the security of our software products and services seriously, which includes all source code repositories managed through our GitHub organizations, which include [Microsoft](https://github.com/Microsoft), [Azure](https://github.com/Azure), [DotNet](https://github.com/dotnet), [AspNet](https://github.com/aspnet), [Xamarin](https://github.com/xamarin), and [our GitHub organizations](https://opensource.microsoft.com/). -If you believe you have found a security vulnerability in any Microsoft-owned repository that meets [Microsoft's definition of a security vulnerability](https://docs.microsoft.com/en-us/previous-versions/tn-archive/cc751383(v=technet.10)), please report it to us as described below. +If you believe you have found a security vulnerability in any Microsoft-owned repository that meets [Microsoft's definition of a security vulnerability](), please report it to us as described below. ## Reporting Security Issues @@ -18,13 +18,13 @@ You should receive a response within 24 hours. If for some reason you do not, pl Please include the requested information listed below (as much as you can provide) to help us better understand the nature and scope of the possible issue: - * Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.) - * Full paths of source file(s) related to the manifestation of the issue - * The location of the affected source code (tag/branch/commit or direct URL) - * Any special configuration required to reproduce the issue - * Step-by-step instructions to reproduce the issue - * Proof-of-concept or exploit code (if possible) - * Impact of the issue, including how an attacker might exploit the issue +- Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.) +- Full paths of source file(s) related to the manifestation of the issue +- The location of the affected source code (tag/branch/commit or direct URL) +- Any special configuration required to reproduce the issue +- Step-by-step instructions to reproduce the issue +- Proof-of-concept or exploit code (if possible) +- Impact of the issue, including how an attacker might exploit the issue This information will help us triage your report more quickly. diff --git a/Actions/Sign/README.md b/Actions/Sign/README.md index 2554b789f..930b280d7 100644 --- a/Actions/Sign/README.md +++ b/Actions/Sign/README.md @@ -1,14 +1,17 @@ # Sign + Sign apps with a certificate stored in Azure Key Vault ## INPUT ### ENV variables + | Name | Description | | :-- | :-- | | Settings | env.Settings must be set by a prior call to the ReadSettings Action | ### Parameters + | Name | Required | Description | Default value | | :-- | :-: | :-- | :-- | | shell | | The shell (powershell or pwsh) in which the PowerShell script in this action should run | powershell | @@ -19,4 +22,5 @@ Sign apps with a certificate stored in Azure Key Vault | pathToFiles | Yes | The path to the files to be signed | ## OUTPUT + none diff --git a/Actions/Sign/Sign.psm1 b/Actions/Sign/Sign.psm1 index 0f65de4b3..7cf93a226 100644 --- a/Actions/Sign/Sign.psm1 +++ b/Actions/Sign/Sign.psm1 @@ -98,4 +98,4 @@ function Invoke-SigningTool() { $FilesToSign } -Export-ModuleMember -Function Invoke-SigningTool \ No newline at end of file +Export-ModuleMember -Function Invoke-SigningTool diff --git a/Actions/Troubleshooting/README.md b/Actions/Troubleshooting/README.md index 1702b2d6a..3a048a436 100644 --- a/Actions/Troubleshooting/README.md +++ b/Actions/Troubleshooting/README.md @@ -1,12 +1,15 @@ # Troubleshooting + Run troubleshooting on repository ## INPUT ### ENV variables + none ### Parameters + | Name | Required | Description | Default value | | :-- | :-: | :-- | :-- | | shell | | The shell (powershell or pwsh) in which the PowerShell script in this action should run | powershell | @@ -14,4 +17,5 @@ none | displayNameOfSecrets | Yes | Display the names (not the values) of secrets available to the repository | | ## OUTPUT -none \ No newline at end of file + +none diff --git a/Actions/VerifyPRChanges/README.md b/Actions/VerifyPRChanges/README.md index e01438ce7..e71bf42e8 100644 --- a/Actions/VerifyPRChanges/README.md +++ b/Actions/VerifyPRChanges/README.md @@ -1,12 +1,15 @@ # Verify Pull Request changes + Verify Pull Request Changes for AL-Go workflows ## INPUT ### ENV variables + none ### Parameters + | Name | Required | Description | Default value | | :-- | :-: | :-- | :-- | | shell | | The shell (powershell or pwsh) in which the PowerShell script in this action should run | powershell | @@ -15,4 +18,5 @@ none | pullRequestId | | The id of the pull request | github.event.pull_request.number | ## OUTPUT + none diff --git a/Actions/WorkflowInitialize/README.md b/Actions/WorkflowInitialize/README.md index 182c85c53..3c14fe539 100644 --- a/Actions/WorkflowInitialize/README.md +++ b/Actions/WorkflowInitialize/README.md @@ -1,12 +1,15 @@ # Initialize workflow + Initialize a workflow ## INPUT ### ENV variables + none ### Parameters + | Name | Required | Description | Default value | | :-- | :-: | :-- | :-- | | shell | | The shell (powershell or pwsh) in which the PowerShell script in this action should run | powershell | @@ -17,9 +20,11 @@ none ## OUTPUT ### ENV variables + none ### OUTPUT variables + | Name | Description | | :-- | :-- | | correlationId | A correlation Id for the workflow | diff --git a/Actions/WorkflowPostProcess/README.md b/Actions/WorkflowPostProcess/README.md index 598d492f7..1a150b940 100644 --- a/Actions/WorkflowPostProcess/README.md +++ b/Actions/WorkflowPostProcess/README.md @@ -1,18 +1,21 @@ # PostProcess action + Finalize a workflow ## INPUT ### ENV variables + none ### Parameters + | Name | Required | Description | Default value | | :-- | :-: | :-- | :-- | | shell | | The shell (powershell or pwsh) in which the PowerShell script in this action should run | powershell | | eventId | Yes | The event id of the initiating workflow | | | telemetryScopeJson | | Telemetry scope generated during the workflow initialization | {} | - ## OUTPUT -none \ No newline at end of file + +none diff --git a/Internal/Overrides/1st party apps/NewBcContainer.ps1 b/Internal/Overrides/1st party apps/NewBcContainer.ps1 index ef0544df4..306089b1f 100644 --- a/Internal/Overrides/1st party apps/NewBcContainer.ps1 +++ b/Internal/Overrides/1st party apps/NewBcContainer.ps1 @@ -18,4 +18,4 @@ Clean-BcContainerDatabase ` -onlySaveBaseAppData ` -keepBaseApp -Invoke-ScriptInBcContainer -containerName $parameters.ContainerName -scriptblock { $progressPreference = 'SilentlyContinue' } \ No newline at end of file +Invoke-ScriptInBcContainer -containerName $parameters.ContainerName -scriptblock { $progressPreference = 'SilentlyContinue' } diff --git a/README.md b/README.md index 4e448fb98..2ff4b733e 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,5 @@ # AL-Go for GitHub + AL-Go for GitHub is a set of GitHub templates and actions, which can be used to setup and maintain professional DevOps processes for your Business Central AL projects. The goal is that people who have created their GitHub repositories based on the AL-Go templates, can maintain these repositories and stay current just by running a workflow, which updates their repositories. This includes necessary changes to scripts and workflows to cope with new features and functions in Business Central. @@ -6,6 +7,7 @@ The goal is that people who have created their GitHub repositories based on the The roadmap for AL-Go for GitHub can be found here: [https://aka.ms/ALGoRoadmap](https://aka.ms/ALGoRoadmap) The template repositories to use as starting point are: + - [https://github.com/microsoft/AL-Go-PTE](https://github.com/microsoft/AL-Go-PTE) or [https://aka.ms/algopte](https://aka.ms/algopte) is the GitHub repository template for Per Tenant Extensions. When creating a Per Tenant Extensions, this is your starting point. - [https://github.com/microsoft/AL-Go-AppSource](https://github.com/microsoft/AL-Go-AppSource) or [https://aka.ms/algoappsource](https://aka.ms/algoappsource) is the GitHub repository template for AppSource apps. When creating an AppSource App, this is your starting point. @@ -14,35 +16,38 @@ The template repositories to use as starting point are: Try out the [AL-Go workshop](https://aka.ms/algoworkshop) for an in-depth workshop on AL-Go for GitHub functionality or examine the below usage scenarios, which explains how to get started and how to perform the most common tasks. ## Usage scenarios + 1. [Create a new per-tenant extension (like AL Go) and start developing in VS Code](Scenarios/GetStarted.md) -2. [Add a test app to an existing project](Scenarios/AddATestApp.md) -3. [Register a customer sandbox environment for Continuous Deployment using S2S](Scenarios/RegisterSandboxEnvironment.md) -4. [Create a release of your application](Scenarios/CreateRelease.md) -5. [Register a customer production environment for Manual Deployment](Scenarios/RegisterProductionEnvironment.md) -6. [Update AL-Go system files](Scenarios/UpdateAlGoSystemFiles.md) -7. [Use Azure KeyVault for secrets with AL-Go](Scenarios/UseAzureKeyVault.md) -8. [Create Online Development Environment from VS Code](Scenarios/CreateOnlineDevEnv.md) -9. [Create Online Development Environment from GitHub](Scenarios/CreateOnlineDevEnv2.md) -10. [Set up CI/CD for an existing per tenant extension (BingMaps)](Scenarios/SetupCiCdForExistingPTE.md) -11. [Set up CI/CD for an existing AppSource App](Scenarios/SetupCiCdForExistingAppSourceApp.md) -12. [Enable KeyVault access for your AppSource App during development and/or tests](Scenarios/EnableKeyVaultForAppSourceApp.md) -13. [Set up your own GitHub runner to increase build performance](Scenarios/SelfHostedGitHubRunner.md) -14. [Introducing a dependency to another GitHub repository](Scenarios/AppDependencies.md) -15. [Enabling Telemetry for AL-Go workflows and actions](Scenarios/EnablingTelemetry.md) -16. [Add a performance test app to an existing project](Scenarios/AddAPerformanceTestApp.md) -17. [Publish your app to AppSource](Scenarios/PublishToAppSource.md) -18. [Connect your GitHub repository to Power Platform](Scenarios/SetupPowerPlatform.md) -19. [How to set up Service Principal for Power Platform](Scenarios/SetupServicePrincipalForPowerPlatform.md) -20. [Try one of the Business Central and Power Platform samples](Scenarios/TryPowerPlatformSamples.md) +1. [Add a test app to an existing project](Scenarios/AddATestApp.md) +1. [Register a customer sandbox environment for Continuous Deployment using S2S](Scenarios/RegisterSandboxEnvironment.md) +1. [Create a release of your application](Scenarios/CreateRelease.md) +1. [Register a customer production environment for Manual Deployment](Scenarios/RegisterProductionEnvironment.md) +1. [Update AL-Go system files](Scenarios/UpdateAlGoSystemFiles.md) +1. [Use Azure KeyVault for secrets with AL-Go](Scenarios/UseAzureKeyVault.md) +1. [Create Online Development Environment from VS Code](Scenarios/CreateOnlineDevEnv.md) +1. [Create Online Development Environment from GitHub](Scenarios/CreateOnlineDevEnv2.md) +1. [Set up CI/CD for an existing per tenant extension (BingMaps)](Scenarios/SetupCiCdForExistingPTE.md) +1. [Set up CI/CD for an existing AppSource App](Scenarios/SetupCiCdForExistingAppSourceApp.md) +1. [Enable KeyVault access for your AppSource App during development and/or tests](Scenarios/EnableKeyVaultForAppSourceApp.md) +1. [Set up your own GitHub runner to increase build performance](Scenarios/SelfHostedGitHubRunner.md) +1. [Introducing a dependency to another GitHub repository](Scenarios/AppDependencies.md) +1. [Enabling Telemetry for AL-Go workflows and actions](Scenarios/EnablingTelemetry.md) +1. [Add a performance test app to an existing project](Scenarios/AddAPerformanceTestApp.md) +1. [Publish your app to AppSource](Scenarios/PublishToAppSource.md) +1. [Connect your GitHub repository to Power Platform](Scenarios/SetupPowerPlatform.md) +1. [How to set up Service Principal for Power Platform](Scenarios/SetupServicePrincipalForPowerPlatform.md) +1. [Try one of the Business Central and Power Platform samples](Scenarios/TryPowerPlatformSamples.md) ## Migration scenarios + A. [Migrate a repository from Azure DevOps to AL-Go for GitHub without history](Scenarios/MigrateFromAzureDevOpsWithoutHistory.md)
B. [Migrate a repository from Azure DevOps to AL-Go for GitHub with history](Scenarios/MigrateFromAzureDevOpsWithHistory.md) -> [!NOTE] +> \[!NOTE\] > Please refer to [this description](Scenarios/settings.md) to learn about the settings file and how you can modify default behaviors. # This project + This project in the main source repository for AL-Go for GitHub. This project is deployed on every release to a branch in the following repositories: - [https://github.com/microsoft/AL-Go-PTE](https://github.com/microsoft/AL-Go-PTE) is the GitHub repository template for Per Tenant Extenstions. For creating a Per Tenant Extensions, this is your starting point. diff --git a/RELEASENOTES.md b/RELEASENOTES.md index 6ff757800..5e56d77e9 100644 --- a/RELEASENOTES.md +++ b/RELEASENOTES.md @@ -1,4 +1,3 @@ - ### Business Central Performance Toolkit Test Result Viewer In the summary after a Test Run, you now also have the result of performance tests. @@ -11,12 +10,13 @@ In the summary after a Test Run, you now also have the result of performance tes - **NumberOfSqlStmtsWarning** - a warning is issued if the number of SQL statements from a bcpt test increases more than this percentage (default 5) - **NumberOfSqlStmtsError** - an error is issued if the number of SQL statements from a bcpt test increases more than this percentage (default 10) -> [!NOTE] +> \[!NOTE\] > Duration thresholds are subject to varying results depending on the performance of the agent running the tests. Number of SQL statements executed by a test is often the most reliable indicator of performance degredation. ## v5.2 ### Issues + - Issue 1084 Automatic updates for AL-Go are failing when main branch requires Pull Request ### New Settings @@ -37,7 +37,7 @@ In the summary after a Test Run, you now also have the result of performance tes - **Pull PowerPlatform Changes** for pulling changes from your PowerPlatform development environment into your AL-Go for GitHub repository - **Push PowerPlatform Changes** for pushing changes from your AL-Go for GitHub repository to your PowerPlatform development environment -> [!NOTE] +> \[!NOTE\] > PowerPlatform workflows are only available in the PTE template and will be removed if no PowerPlatformSolutionFolder is defined in settings. ### New Scenarios (Documentation) @@ -47,7 +47,7 @@ In the summary after a Test Run, you now also have the result of performance tes - [Try one of the Business Central and Power Platform samples](https://github.com/microsoft/AL-Go/blob/main/Scenarios/TryPowerPlatformSamples.md) - [Publish To AppSource](https://github.com/microsoft/AL-Go/blob/main/Scenarios/PublishToAppSource.md) -> [!NOTE] +> \[!NOTE\] > PowerPlatform functionality are only available in the PTE template. ## v5.1 @@ -72,6 +72,7 @@ In the summary after a Test Run, you now also have the result of performance tes ### Better artifact selection The artifact setting in your project settings file can now contain a `*` instead of the version number. This means that AL-Go for GitHub will determine the application dependency for your projects together with the `applicationDependency` setting and determine which Business Central version is needed for the project. + - `"artifact": "//*//latest"` will give you the latest Business Central version, higher than your application dependency and with the same major.minor as your application dependency. - `"artifact": "//*//first"` will give you the first Business Central version, higher than your application dependency and with the same major.minor as your application dependency. @@ -97,35 +98,43 @@ Adding -clean when running localdevenv or clouddevenv will create a clean develo ## v5.0 ### Issues + - Issue 940 Publish to Environment is broken when specifying projects to publish - Issue 994 CI/CD ignores Deploy to GitHub Pages in private repositories ### New Settings -- `UpdateALGoSystemFilesEnvironment`: The name of the environment that is referenced in job `UpdateALGoSystemFiles` in the _Update AL-Go System Files_ workflow. See [jobs..environment](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idenvironment) for more information. Currently, only setting the environment name is supported. + +- `UpdateALGoSystemFilesEnvironment`: The name of the environment that is referenced in job `UpdateALGoSystemFiles` in the _Update AL-Go System Files_ workflow. See [jobs.\.environment](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idenvironment) for more information. Currently, only setting the environment name is supported. ### Issues + - Support release branches that start with releases/ - Issue 870 Improve Error Handling when CLI is missing - Issue 889 CreateRelease and IncrementVersionNumber workflow did not handle wild characters in `appFolders`, `testFolders` or `bcptTestFolders` settings. - Issue 973 Prerelease is not used for deployment ### Build modes + AL-Go ships with Default, Translated and Clean mode out of the box. Now you can also define custom build modes in addition to the ones shipped with AL-Go. This allows you to define your own build modes, which can be used to build your apps in different ways. By default, a custom build mode will build the apps similarly to the Default mode but this behavior can be overridden in e.g. script overrides in your repository. ## v4.1 ### New Settings + - `templateSha`: The SHA of the version of AL-Go currently used ### New Actions + - `DumpWorkflowInfo`: Dump information about running workflow - `Troubleshooting` : Run troubleshooting for repository ### Update AL-Go System Files + Add another parameter when running Update AL-Go System Files, called downloadLatest, used to indicate whether to download latest version from template repository. Default value is true. If false, the templateSha repository setting is used to download specific AL-Go System Files when calculating new files. ### Issues + - Issue 782 Exclude '.altestrunner/' from template .gitignore - Issue 823 Dependencies from prior build jobs are not included when using useProjectDependencies - App artifacts for version 'latest' are now fetched from the latest CICD run that completed and successfully built all the projects for the corresponding branch. @@ -148,10 +157,12 @@ If false, the templateSha repository setting is used to download specific AL-Go - *Note that in header, footer, defaultIndexMD and defaultReleaseMD you can use the following placeholders: {REPOSITORY}, {VERSION}, {INDEXTEMPLATERELATIVEPATH}, {RELEASENOTES}* ### New Workflows + - **Deploy Reference Documentation** is a workflow, which you can invoke manually or on a schedule to generate and deploy reference documentation using the aldoc tool, using the ALDoc setting properties described above. - **Troubleshooting** is a workflow, which you can invoke manually to run troubleshooting on the repository and check for settings or secrets, containing illegal values. When creating issues on https://github.com/microsoft/AL-Go/issues, we might ask you to run the troubleshooter to help identify common problems. ### Support for ALDoc reference documentation tool + ALDoc reference documentation tool is now supported for generating and deploying reference documentation for your projects either continuously or manually/scheduled. ## v4.0 @@ -163,19 +174,22 @@ As of October 1st 2023, Business Central insider builds are now publicly availab AL-Go for GitHub allows you to build and test using insider builds without any explicit approval, but please note that the insider artifacts contains the insider Eula and you automatically accept this when using the builds. ### Issues + - Issue 730 Support for external rulesets. - Issue 739 Workflow specific KeyVault settings doesn't work for localDevEnv -- Using self-hosted runners while using Azure KeyVault for secrets or signing might fail with C:\Modules doesn't exist +- Using self-hosted runners while using Azure KeyVault for secrets or signing might fail with C:\\Modules doesn't exist - PullRequestHandler wasn't triggered if only .md files where changes. This lead to PRs which couldn't be merged if a PR status check was mandatory. - Artifacts names for PR Builds were using the merge branch instead of the head branch. ### New Settings + - `enableExternalRulesets`: set this setting to true if you want to allow AL-Go to automatically download external references in rulesets. - `deliverTo`: is not really new, but has new properties and wasn't documented. The complete list of properties is here (note that some properties are deliveryTarget specific): - - **Branches** = an array of branch patterns, which are allowed to deliver to this deliveryTarget. (Default [ "main" ]) - - **CreateContainerIfNotExist** = *[Only for DeliverToStorage]* Create Blob Storage Container if it doesn't already exist. (Default false) + - **Branches** = an array of branch patterns, which are allowed to deliver to this deliveryTarget. (Default \[ "main" \]) + - **CreateContainerIfNotExist** = *\[Only for DeliverToStorage\]* Create Blob Storage Container if it doesn't already exist. (Default false) ### Deployment + Environment URL is now displayed underneath the environment being deployed to in the build summary. For Custom Deployment, the script can set the GitHub Output variable `environmentUrl` in order to show a custom URL. ## v3.3 @@ -201,18 +215,20 @@ This mechanism is no longer supported and you will get an error if your reposito Earlier, you could also specify the projects you want to deploy to an environment in a setting called `_Projects` or `-Projects`. This is also no longer supported. Instead use the `DeployTo` and remove the old settings. ### New Actions + - `DetermineDeliveryTargets`: Determine which delivery targets should be used for delivering artifacts from the build job. - `DetermineDeploymentEnvironments`: Determine which deployment environments should be used for the workflow. ### New Settings + - `projectName`: project setting used as friendly name for an AL-Go project, to be used in the UI for various workflows, e.g. CICD, Pull Request Build. - `fullBuildPatterns`: used by `DetermineProjectsToBuild` action to specify changes in which files and folders would trigger a full build (building all AL-Go projects). - `excludeEnvironments`: used by `DetermineDeploymentEnvironments` action to exclude environments from the list of environments considered for deployment. - `deployTo`: is not really new, but has new properties. The complete list of properties is here: - **EnvironmentType** = specifies the type of environment. The environment type can be used to invoke a custom deployment. (Default SaaS) - **EnvironmentName** = specifies the "real" name of the environment if it differs from the GitHub environment - - **Branches** = an array of branch patterns, which are allowed to deploy to this environment. (Default [ "main" ]) - - **Projects** = In multi-project repositories, this property can be a comma separated list of project patterns to deploy to this environment. (Default *) + - **Branches** = an array of branch patterns, which are allowed to deploy to this environment. (Default \[ "main" \]) + - **Projects** = In multi-project repositories, this property can be a comma separated list of project patterns to deploy to this environment. (Default \*) - **SyncMode** = ForceSync if deployment to this environment should happen with ForceSync, else Add. If deploying to the development endpoint you can also specify Development or Clean. (Default Add) - **ContinuousDeployment** = true if this environment should be used for continuous deployment, else false. (Default: AL-Go will continuously deploy to sandbox environments or environments, which doesn't end in (PROD) or (FAT) - **runs-on** = specifies which GitHub runner to use when deploying to this environment. (Default is settings.runs-on) @@ -239,6 +255,7 @@ By specifying a custom EnvironmentType in the DeployTo structure for an environm AL-Go for GitHub now adds status checks to Pull Requests Builds. In your GitHub branch protection rules, you can set up "Pull Request Status Check" to be a required status check to ensure Pull Request Builds succeed before merging. ### Secrets in AL-Go for GitHub + In v3.2 of AL-Go for GitHub, all secrets requested by AL-Go for GitHub were available to all steps in a job one compressed JSON structure in env:Secrets. With this update, only the steps that actually requires secrets will have the secrets available. @@ -259,6 +276,7 @@ Create Online Development environment workflow didn't work if runs-on was set to Special characters are not supported in RepoName, Project names or other settings - Use UTF8 encoding to handle special characters in GITHUB_OUTPUT and GITHUB_ENV ### Issue 555 + AL-Go contains several workflows, which create a Pull Request or pushes code directly. All (except Update AL-Go System Files) earlier used the GITHUB_TOKEN to create the PR or commit. The problem using GITHUB_TOKEN is that is doesn't trigger a pull request build or a commit build. @@ -266,20 +284,23 @@ This is by design: https://docs.github.com/en/actions/using-workflows/triggering Now, you can set the checkbox called Use GhTokenWorkflow to allowing you to use the GhTokenWorkflow instead of the GITHUB_TOKEN - making sure that workflows are triggered ### New Settings + - `keyVaultCodesignCertificateName`: With this setting you can delegate the codesigning to an Azure Key Vault. This can be useful if your certificate has to be stored in a Hardware Security Module - `PullRequestTrigger`: With this setting you can set which trigger to use for Pull Request Builds. By default AL-Go will use pull_request_target. ### New Actions + - `DownloadProjectDependencies`: Downloads the dependency apps for a given project and build mode. ### Settings and Secrets in AL-Go for GitHub + In earlier versions of AL-Go for GitHub, all settings were available as individual environment variables to scripts and overrides, this is no longer the case. Settings were also available as one compressed JSON structure in env:Settings, this is still the case. Settings can no longer contain line breaks. It might have been possible to use line breaks earlier, but it would likely have unwanted consequences. Use `$settings = $ENV:Settings | ConvertFrom-Json` to get all settings in PowerShell. In earlier versions of AL-Go for GitHub, all secrets requested by AL-Go for GitHub were available as individual environment variables to scripts and overrides, this is no longer the case. -As described in bug 647, all secrets available to the workflow were also available in env:_Secrets, this is no longer the case. +As described in bug 647, all secrets available to the workflow were also available in env:\_Secrets, this is no longer the case. All requested secrets were also available (base64 encoded) as one compressed JSON structure in env:Secrets, this is still the case. Use `$secrets = $ENV:Secrets | ConvertFrom-Json` to get all requested secrets in PowerShell. You cannot get to any secrets that weren't requested by AL-Go for GitHub. @@ -293,7 +314,6 @@ Issue #453 DeliverToStorage - override fails reading secrets Issue #434 Use gh auth token to get authentication token instead of gh auth status Issue #501 The Create New App action will now use 22.0.0.0 as default application reference and include NoImplicitwith feature. - ### New behavior The following workflows: @@ -314,8 +334,8 @@ All these actions now uses the selected branch in the **Run workflow** dialog as ### New Workflows -- **_BuildALGoProject** is a reusable workflow that unites the steps for building an AL-Go projects. It has been reused in the following workflows: _CI/CD_, _Pull Request Build_, _NextMinor_, _NextMajor_ and _Current_. -The workflow appears under the _Actions_ tab in GitHub, but it is not actionable in any way. +- **\_BuildALGoProject** is a reusable workflow that unites the steps for building an AL-Go projects. It has been reused in the following workflows: _CI/CD_, _Pull Request Build_, _NextMinor_, _NextMajor_ and _Current_. + The workflow appears under the _Actions_ tab in GitHub, but it is not actionable in any way. ### New Actions @@ -329,29 +349,36 @@ Obviously, if you build and test your app for Business Central versions prior to ## v3.0 ### **NOTE:** When upgrading to this version + When upgrading to this version form earlier versions of AL-Go for GitHub, you will need to run the _Update AL-Go System Files_ workflow twice if you have the `useProjectDependencies` setting set to _true_. ### Publish to unknown environment + You can now run the **Publish To Environment** workflow without creating the environment in GitHub or settings up-front, just by specifying the name of a single environment in the Environment Name when running the workflow. Subsequently, if an AuthContext secret hasn't been created for this environment, the Device Code flow authentication will be initiated from the Publish To Environment workflow and you can publish to the new environment without ever creating a secret. Open Workflow details to get the device Code for authentication in the job summary for the initialize job. ### Create Online Dev. Environment + When running the **Create Online Dev. Environment** workflow without having the _adminCenterApiCredentials_ secret created, the workflow will intiate the deviceCode flow and allow you to authenticate to the Business Central Admin Center. Open Workflow details to get the device Code for authentication in the job summary for the initialize job. ### Issues + - Issue #391 Create release action - CreateReleaseBranch error - Issue 434 Building local DevEnv, downloading dependencies: Authentication fails when using "gh auth status" ### Changes to Pull Request Process + In v2.4 and earlier, the PullRequestHandler would trigger the CI/CD workflow to run the PR build. Now, the PullRequestHandler will perform the build and the CI/CD workflow is only run on push (or manual dispatch) and will perform a complete build. ### Build modes per project + Build modes can now be specified per project ### New Actions + - **DetermineProjectsToBuild** is used to determine which projects to build in PullRequestHandler, CI/CD, Current, NextMinor and NextMajor workflows. - **CalculateArtifactNames** is used to calculate artifact names in PullRequestHandler, CI/CD, Current, NextMinor and NextMajor workflows. - **VerifyPRChanges** is used to verify whether a PR contains changes, which are not allowed from a fork. @@ -359,6 +386,7 @@ Build modes can now be specified per project ## v2.4 ### Issues + - Issue #171 create a workspace file when creating a project - Issue #356 Publish to AppSource fails in multi project repo - Issue #358 Publish To Environment Action stopped working in v2.3 @@ -368,9 +396,11 @@ Build modes can now be specified per project - Issue #376 CICD jobs that are triggered by the pull request trigger run directly to an error if title contains quotes ### Release Branches + **NOTE:** Release Branches are now only named after major.minor if the patch value is 0 in the release tag (which must be semver compatible) This version contains a number of bug fixes to release branches, to ensure that the recommended branching strategy is fully supported. Bugs fixed includes: + - Release branches was named after the full tag (1.0.0), even though subsequent hotfixes released from this branch would be 1.0.x - Release branches named 1.0 wasn't picked up as a release branch - Release notes contained the wrong changelog @@ -383,9 +413,11 @@ Recommended branching strategy: ![Branching Strategy](https://raw.githubusercontent.com/microsoft/AL-Go/main/Scenarios/images/branchingstrategy.png) ### New Settings + New Project setting: EnableTaskScheduler in container executing tests and when setting up local development environment ### Support for GitHub variables: ALGoOrgSettings and ALGoRepoSettings + Recently, GitHub added support for variables, which you can define on your organization or your repository. AL-Go now supports that you can define a GitHub variable called ALGoOrgSettings, which will work for all repositories (with access to the variable) Org Settings will be applied before Repo settings and local repository settings files will override values in the org settings @@ -394,11 +426,13 @@ Example for usage could be setup of branching strategies, versioning or an appDe appDependencyProbingPaths from settings variables are merged together with appDependencyProbingPaths defined in repositories ### Refactoring and tests + ReadSettings has been refactored to allow organization wide settings to be added as well. CI Tests have been added to cover ReadSettings. ## v2.3 ### Issues + - Issue #312 Branching enhancements - Issue #229 Create Release action tags wrong commit - Issue #283 Create Release workflow uses deprecated actions @@ -408,45 +442,56 @@ ReadSettings has been refactored to allow organization wide settings to be added - Issue #345 LocalDevEnv.ps1 can't Dowload the file license file ### New Settings + New Project setting: AssignPremiumPlan on user in container executing tests and when setting up local development environment New Repo setting: unusedALGoSystemFiles is an array of AL-Go System Files, which won't be updated during Update AL-Go System Files. They will instead be removed. Use with care, as this can break the AL-Go for GitHub functionality and potentially leave your repo no longer functional. ### Build modes support + AL-Go projects can now be built in different modes, by specifying the _buildModes_ setting in AL-Go-Settings.json. Read more about build modes in the [Basic Repository settings](https://github.com/microsoft/AL-Go/blob/main/Scenarios/settings.md#basic-repository-settings). ### LocalDevEnv / CloudDevEnv + With the support for PowerShell 7 in BcContainerHelper, the scripts LocalDevEnv and CloudDevEnv (placed in the .AL-Go folder) for creating development environments have been modified to run inside VS Code instead of spawning a new powershell 5.1 session. ### Continuous Delivery -Continuous Delivery can now run from other branches than main. By specifying a property called branches, containing an array of branches in the deliveryContext json construct, the artifacts generated from this branch are also delivered. The branch specification can include wildcards (like release/*). Default is main, i.e. no changes to functionality. + +Continuous Delivery can now run from other branches than main. By specifying a property called branches, containing an array of branches in the deliveryContext json construct, the artifacts generated from this branch are also delivered. The branch specification can include wildcards (like release/\*). Default is main, i.e. no changes to functionality. ### Continuous Deployment -Continuous Deployment can now run from other branches than main. By creating a repo setting (.github/AL-Go-Settings.json) called **`-Branches`**, which is an array of branches, which will deploy the generated artifacts to this environment. The branch specification can include wildcards (like release/*), although this probably won't be used a lot in continuous deployment. Default is main, i.e. no changes to functionality. + +Continuous Deployment can now run from other branches than main. By creating a repo setting (.github/AL-Go-Settings.json) called **`-Branches`**, which is an array of branches, which will deploy the generated artifacts to this environment. The branch specification can include wildcards (like release/\*), although this probably won't be used a lot in continuous deployment. Default is main, i.e. no changes to functionality. ### Create Release + When locating artifacts for the various projects, the SHA used to build the artifact is used for the release tag If all projects are not available with the same SHA, this error is thrown: **The build selected for release doesn't contain all projects. Please rebuild all projects by manually running the CI/CD workflow and recreate the release.** There is no longer a hard dependency on the main branch name from Create Release. ### AL-Go Tests + Some unit tests have been added and AL-Go unit tests can now be run directly from VS Code. Another set of end to end tests have also been added and in the documentation on contributing to AL-Go, you can see how to run these in a local fork or from VS Code. ### LF, UTF8 and JSON + GitHub natively uses LF as line seperator in source files. In earlier versions of AL-Go for GitHub, many scripts and actions would use CRLF and convert back and forth. Some files were written with UTF8 BOM (Byte Order Mark), other files without and JSON formatting was done using PowerShell 5.1 (which is different from PowerShell 7). In the latest version, we always use LF as line seperator, UTF8 without BOM and JSON files are written using PowerShell 7. If you have self-hosted runners, you need to ensure that PS7 is installed to make this work. ### Experimental Support + Setting the repo setting "shell" to "pwsh", followed by running Update AL-Go System Files, will cause all PowerShell code to be run using PowerShell 7 instead of PowerShell 5. This functionality is experimental. Please report any issues at https://github.com/microsoft/AL-Go/issues Setting the repo setting "runs-on" to "Ubuntu-Latest", followed by running Update AL-Go System Files, will cause all non-build jobs to run using Linux. This functionality is experimental. Please report any issues at https://github.com/microsoft/AL-Go/issues ## v2.2 ### Enhancements + - Container Event log is added as a build artifact if builds or tests are failing ### Issues + - Issue #280 Overflow error when test result summary was too big - Issue #282, 292 AL-Go for GitHub causes GitHub to issue warnings - Issue #273 Potential security issue in Pull Request Handler in Open Source repositories @@ -456,25 +501,30 @@ Setting the repo setting "runs-on" to "Ubuntu-Latest", followed by running Updat - Issue #287 AL-Go pipeline fails in ReadSettings step ### Changes + - VersioningStrategy 1 is no longer supported. GITHUB_ID has changed behavior (Issue #277) ## v2.1 ### Issues + - Issue #233 AL-Go for GitHub causes GitHub to issue warnings - Issue #244 Give error if AZURE_CREDENTIALS contains line breaks ### Changes + - New workflow: PullRequestHandler to handle all Pull Requests and pass control safely to CI/CD - Changes to yaml files, PowerShell scripts and codeowners files are not permitted from fork Pull Requests - Test Results summary (and failed tests) are now displayed directly in the CI/CD workflow and in the Pull Request Check ### Continuous Delivery + - Proof Of Concept Delivery to GitHub Packages and Nuget ## v2.0 ### Issues + - Issue #143 Commit Message for **Increment Version Number** workflow - Issue #160 Create local DevEnv aith appDependencyProbingPaths - Issue #156 Versioningstrategy 2 doesn't use 24h format @@ -488,15 +538,18 @@ Setting the repo setting "runs-on" to "Ubuntu-Latest", followed by running Updat - Special characters wasn't supported in parameters to GitHub actions (Create New App etc.) ### Continuous Delivery + - Added new GitHub Action "Deliver" to deliver build output to Storage or AppSource - Refactor CI/CD and Release workflows to use new deliver action -- Custom delivery supported by creating scripts with the naming convention DeliverTo*.ps1 in the .github folder +- Custom delivery supported by creating scripts with the naming convention DeliverTo\*.ps1 in the .github folder ### AppSource Apps + - New workflow: Publish to AppSource - Continuous Delivery to AppSource validation supported ### Settings + - New Repo setting: CICDPushBranches can be specified as an array of branches, which triggers a CI/CD workflow on commit. Default is main', release/\*, feature/\* - New Repo setting: CICDPullRequestBranches can be specified as an array of branches, which triggers a CI/CD workflow on pull request. Default is main - New Repo setting: CICDSchedule can specify a CRONTab on when you want to run CI/CD on a schedule. Note that this will disable Push and Pull Request triggers unless specified specifically using CICDPushBranches or CICDPullRequestBranches @@ -507,16 +560,19 @@ Setting the repo setting "runs-on" to "Ubuntu-Latest", followed by running Updat - New project Setting: AppSourceMainAppFolder. If you have multiple appFolders, this is the folder name of the main app to submit to AppSource. ### All workflows -- Support 2 folder levels projects (apps\w1, apps\dk etc.) + +- Support 2 folder levels projects (apps\\w1, apps\\dk etc.) - Better error messages for if an error occurs within an action - Special characters are now supported in secrets - Initial support for agents running inside containers on a host - Optimized workflows to have fewer jobs ### Update AL-Go System Files Workflow + - workflow now displays the currently used template URL when selecting the Run Workflow action ### CI/CD workflow + - Better detection of changed projects - appDependencyProbingPaths did not support multiple projects in the same repository for latestBuild dependencies - appDependencyProbingPaths with release=latestBuild only considered the last 30 artifacts @@ -525,45 +581,56 @@ Setting the repo setting "runs-on" to "Ubuntu-Latest", followed by running Updat - Continue on error with Deploy and Deliver ### CI/CD and Publish To New Environment + - Base functionality for selecting a specific GitHub runner for an environment - Include dependencies artifacts when deploying (if generateDependencyArtifacts is true) ### localDevEnv.ps1 and cloudDevEnv.ps1 + - Display clear error message if something goes wrong ## v1.5 ### Issues + - Issue #100 - Add more resilience to localDevEnv.ps1 and cloudDevEnv.ps1 - Issue #131 - Special characters are not allowed in secrets ### All workflows + - During initialize, all AL-Go settings files are now checked for validity and reported correctly - During initialize, the version number of AL-Go for GitHub is printed in large letters (incl. preview or dev.) ### New workflow: Create new Performance Test App + - Create BCPT Test app and add to bcptTestFolders to run bcpt Tests in workflows (set doNotRunBcptTests in workflow settings for workflows where you do NOT want this) ### Update AL-Go System Files Workflow + - Include release notes of new version in the description of the PR (and in the workflow output) ### CI/CD workflow + - Apps are not signed when the workflow is running as a Pull Request validation - if a secret called applicationInsightsConnectionString exists, then the value of that will be used as ApplicationInsightsConnectionString for the app ### Increment Version Number Workflow + - Bugfix: increment all apps using f.ex. +0.1 would fail. ### Environments -- Add suport for EnvironmentName redirection by adding an Environment Secret under the environment or a repo secret called \_EnvironmentName with the actual environment name. + +- Add suport for EnvironmentName redirection by adding an Environment Secret under the environment or a repo secret called \\_EnvironmentName with the actual environment name. - No default environment name on Publish To Environment -- For multi-project repositories, you can specify an environment secret called Projects or a repo setting called \_Projects, containing the projects you want to deploy to this environment. +- For multi-project repositories, you can specify an environment secret called Projects or a repo setting called \\_Projects, containing the projects you want to deploy to this environment. ### Settings + - New setting: **runs-on** to allow modifying runs-on for all jobs (requires Update AL-Go System files after changing the setting) - New setting: **DoNotSignApps** - setting this to true causes signing of the app to be skipped - New setting: **DoNotPublishApps** - setting this to true causes the workflow to skip publishing, upgrading and testing the app to improve performance. - New setting: **ConditionalSettings** to allow to use different settings for specific branches. Example: + ``` "ConditionalSettings": [ { @@ -577,6 +644,7 @@ Setting the repo setting "runs-on" to "Ubuntu-Latest", followed by running Updat } ] ``` + - Default **BcContainerHelperVersion** is now based on AL-Go version. Preview AL-Go selects preview bcContainerHelper, normal selects latest. - New Setting: **bcptTestFolders** contains folders with BCPT tests, which will run in all build workflows - New Setting: set **doNotRunBcptTest** to true (in workflow specific settings file?) to avoid running BCPT tests @@ -585,54 +653,64 @@ Setting the repo setting "runs-on" to "Ubuntu-Latest", followed by running Updat ## v1.4 ### All workflows + - Add requested permissions to avoid dependency on user/org defaults being too permissive ### Update AL-Go System Files Workflow + - Default host to https://github.com/ (you can enter **myaccount/AL-Go-PTE@main** to change template) -- Support for "just" changing branch (ex. **\@Preview**) to shift to the preview version +- Support for "just" changing branch (ex. **@Preview**) to shift to the preview version ### CI/CD Workflow + - Support for feature branches (naming **feature/\***) - CI/CD workflow will run, but not generate artifacts nor deploy to QA ### Create Release Workflow + - Support for release branches - Force Semver format on release tags - Add support for creating release branches on release (naming release/\*) - Add support for incrementing main branch after release ### Increment version number workflow + - Add support for incremental (and absolute) version number change ### Environments + - Support environmentName redirection in CI/CD and Publish To Environments workflows - If the name in Environments or environments settings doesn't match the actual environment name, -- You can add a secret called EnvironmentName under the environment (or \_ENVIRONMENTNAME globally) - +- You can add a secret called EnvironmentName under the environment (or \\_ENVIRONMENTNAME globally) ## v1.3 ### Issues -- Issue #90 - Environments did not work. Secrets for environments specified in settings can now be **\_AUTHCONTEXT** + +- Issue #90 - Environments did not work. Secrets for environments specified in settings can now be **\\_AUTHCONTEXT** ### CI/CD Workflow + - Give warning instead of error If no artifacts are found in **appDependencyProbingPaths** ## v1.2 ### Issues + - Issue #90 - Environments did not work. Environments (even if only defined in the settings file) did not work for private repositories if you didn't have a premium subscription. ### Local scripts -- **LocalDevEnv.ps1** and ***CloudDevEnv.ps1** will now spawn a new PowerShell window as admin instead of running inside VS Code. Normally people doesn't run VS Code as administrator, and they shouldn't have to. Furthermore, I have seen a some people having problems when running these scripts inside VS Code. +- **LocalDevEnv.ps1** and \***CloudDevEnv.ps1** will now spawn a new PowerShell window as admin instead of running inside VS Code. Normally people doesn't run VS Code as administrator, and they shouldn't have to. Furthermore, I have seen a some people having problems when running these scripts inside VS Code. ## v1.1 ### Settings + - New Repo Setting: **GenerateDependencyArtifact** (default **false**). When true, CI/CD pipeline generates an artifact with the external dependencies used for building the apps in this repo. - New Repo Setting: **UpdateDependencies** (default **false**). When true, the default artifact for building the apps in this repo is not the latest available artifacts for this country, but instead the first compatible version (after calculating application dependencies). It is recommended to run Test Current, Test NextMinor and Test NextMajor in order to test your app against current and future builds. ### CI/CD Workflow + - New Artifact: BuildOutput.txt. All compiler warnings and errors are emitted to this file to make it easier to investigate compiler errors and build a better UI for build errors and test results going forward. - TestResults artifact name to include repo version number and workflow name (for Current, NextMinor and NextMajor) - Default dependency version in appDependencyProbingPaths setting used is now latest Release instead of LatestBuild diff --git a/SECURITY.md b/SECURITY.md index 1f9d3d442..9657262ba 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -4,7 +4,7 @@ Microsoft takes the security of our software products and services seriously, which includes all source code repositories managed through our GitHub organizations, which include [Microsoft](https://github.com/Microsoft), [Azure](https://github.com/Azure), [DotNet](https://github.com/dotnet), [AspNet](https://github.com/aspnet), [Xamarin](https://github.com/xamarin), and [our GitHub organizations](https://opensource.microsoft.com/). -If you believe you have found a security vulnerability in any Microsoft-owned repository that meets [Microsoft's definition of a security vulnerability](https://docs.microsoft.com/en-us/previous-versions/tn-archive/cc751383(v=technet.10)), please report it to us as described below. +If you believe you have found a security vulnerability in any Microsoft-owned repository that meets [Microsoft's definition of a security vulnerability](), please report it to us as described below. ## Reporting Security Issues @@ -18,13 +18,13 @@ You should receive a response within 24 hours. If for some reason you do not, pl Please include the requested information listed below (as much as you can provide) to help us better understand the nature and scope of the possible issue: - * Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.) - * Full paths of source file(s) related to the manifestation of the issue - * The location of the affected source code (tag/branch/commit or direct URL) - * Any special configuration required to reproduce the issue - * Step-by-step instructions to reproduce the issue - * Proof-of-concept or exploit code (if possible) - * Impact of the issue, including how an attacker might exploit the issue +- Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.) +- Full paths of source file(s) related to the manifestation of the issue +- The location of the affected source code (tag/branch/commit or direct URL) +- Any special configuration required to reproduce the issue +- Step-by-step instructions to reproduce the issue +- Proof-of-concept or exploit code (if possible) +- Impact of the issue, including how an attacker might exploit the issue This information will help us triage your report more quickly. @@ -38,4 +38,4 @@ We prefer all communications to be in English. Microsoft follows the principle of [Coordinated Vulnerability Disclosure](https://www.microsoft.com/en-us/msrc/cvd). - \ No newline at end of file + diff --git a/Scenarios/AddAPerformanceTestApp.md b/Scenarios/AddAPerformanceTestApp.md index 8c27fc9a7..ce2d883ab 100644 --- a/Scenarios/AddAPerformanceTestApp.md +++ b/Scenarios/AddAPerformanceTestApp.md @@ -1,4 +1,5 @@ # #16 Add a performance test app to an existing project + *Prerequisites: A completed [scenario 1](GetStarted.md)* 1. On **github.com**, open **Actions** on your solution, select **Create a new performance test app** and then choose **Run workflow**. Enter values for **name**, **publisher**, and **ID range** and choose **Run workflow** @@ -9,33 +10,33 @@ ![Annotation](https://github.com/microsoft/AL-Go/assets/10775043/d346f0fc-5db4-4ff1-9c76-e93cb03ae504) -2. When the workflow is done, navigate to **Pull Requests**, **inspect the PR** and **Merge the pull request** +1. When the workflow is done, navigate to **Pull Requests**, **inspect the PR** and **Merge the pull request** ![Pull Request](https://github.com/microsoft/AL-Go/assets/10775043/d2831620-3bc9-4808-aa7a-997944aaaa33) -3. Under **Actions**, you will see that a Merge pull request **CI/CD workflow** has been kicked off +1. Under **Actions**, you will see that a Merge pull request **CI/CD workflow** has been kicked off ![Workflows](https://github.com/microsoft/AL-Go/assets/10775043/37f6c5b9-aaac-4cdc-b1d0-ef661cd2bfbe) -4. If you wait for the workflow to complete, you will see that it completes and one of the build artifacts are the **BCPT Test Results** +1. If you wait for the workflow to complete, you will see that it completes and one of the build artifacts are the **BCPT Test Results** ![BCPT Test Results](https://github.com/microsoft/AL-Go/assets/10775043/cb206f91-3b83-4000-987c-39faa9765695) -5. Opening the **BCPT Test Results** and inspecting the results looks like this +1. Opening the **BCPT Test Results** and inspecting the results looks like this ![BCPT Test Results.json](https://github.com/microsoft/AL-Go/assets/10775043/27acb70c-1ead-4832-b22a-b022c578250d) -6. Scrolling down further reveals the Performance Test Results in a table, which also indicates that if we want to set a baseline for comparing future BCPT Test Results, we need to add a `bcptBaseLine.json` file in the project folder. +1. Scrolling down further reveals the Performance Test Results in a table, which also indicates that if we want to set a baseline for comparing future BCPT Test Results, we need to add a `bcptBaseLine.json` file in the project folder. ![BCPT Test Results viewer](https://github.com/microsoft/AL-Go/assets/10775043/4b263e9e-7ec9-4101-92a7-046e7807e797) -7. After uploading a `bcptBaseLine.json`, to the project root (which is the repo root in single project repositories), another CI/CD workflow will be kicked off, which now compares the results with the baseline: +1. After uploading a `bcptBaseLine.json`, to the project root (which is the repo root in single project repositories), another CI/CD workflow will be kicked off, which now compares the results with the baseline: ![With BaseLine](https://github.com/microsoft/AL-Go/assets/10775043/c00840d5-4c67-4a72-a4d9-cdebe62e54c0) Where negative numbers in the diff fields indicates faster execution or lower number of SQL statements than the baseline. -> [!NOTE] +> \[!NOTE\] > > You can specify thresholds for performance testing in project settings (see [https://aka.ms/algosettings#bcptThresholds](https://aka.ms/algosettings#bcptThresholds)) or in a file called `bcptThresholds.json`, which should be located next to the `bcptBaseLine.json` file. @@ -52,5 +53,6 @@ ![Warnings and Error](https://github.com/microsoft/AL-Go/assets/10775043/be85d4c1-c710-410d-aba3-b55de8750396) ---- +______________________________________________________________________ + [back](../README.md) diff --git a/Scenarios/AddATestApp.md b/Scenarios/AddATestApp.md index 2ac9d6626..4b9422eaf 100644 --- a/Scenarios/AddATestApp.md +++ b/Scenarios/AddATestApp.md @@ -1,22 +1,24 @@ # #2 Add a test app to an existing project + *Prerequisites: A completed [scenario 1](GetStarted.md)* 1. On **github.com**, open **Actions** on your solution, select **Create a new test app** and then choose **Run workflow**. Enter values for **name**, **publisher**, and **ID range** and choose **Run workflow** -![Run Workflow](https://github.com/microsoft/AL-Go/assets/10775043/96485817-a631-4626-92b4-89e6432f5622) + ![Run Workflow](https://github.com/microsoft/AL-Go/assets/10775043/96485817-a631-4626-92b4-89e6432f5622) 1. When the workflow is done, navigate to **Pull Requests**, **inspect the PR** and **Merge the pull request** -![Pull Request](https://github.com/microsoft/AL-Go/assets/10775043/9fef16a8-ed34-43ee-8678-5ea7d3f1d221) + ![Pull Request](https://github.com/microsoft/AL-Go/assets/10775043/9fef16a8-ed34-43ee-8678-5ea7d3f1d221) 1. Under **Actions**, you will see that a Merge pull request CI workflow has been kicked off -![Workflows](https://github.com/microsoft/AL-Go/assets/10775043/033ca252-ca26-457e-81a5-6f9edbda7a96) + ![Workflows](https://github.com/microsoft/AL-Go/assets/10775043/033ca252-ca26-457e-81a5-6f9edbda7a96) 1. If you wait for the workflow to complete, you will see that it fails. -![Fail](https://github.com/microsoft/AL-Go/assets/10775043/d009f93b-0346-4273-b180-34ecf83ab76f) + ![Fail](https://github.com/microsoft/AL-Go/assets/10775043/d009f93b-0346-4273-b180-34ecf83ab76f) 1. Inspecting the build, you can see the details of the error. -![Test failure](https://github.com/microsoft/AL-Go/assets/10775043/9120bf17-c3d4-414e-ae39-c876653b5567) + ![Test failure](https://github.com/microsoft/AL-Go/assets/10775043/9120bf17-c3d4-414e-ae39-c876653b5567) 1. To fix this, open VS Code, pull changes from the server using the sync button, open the **HelloWorld.Test.al** file and fix the test message. -![Bug fix](https://github.com/microsoft/AL-Go/assets/10775043/49d0f417-b9b3-4a30-8a48-e296cfe03b70) + ![Bug fix](https://github.com/microsoft/AL-Go/assets/10775043/49d0f417-b9b3-4a30-8a48-e296cfe03b70) 1. Stage, Commit, and Push the change. On github.com, under **Actions** you will see that your check-in caused another CI workflow to be kicked off. -![CI Workflow](https://github.com/microsoft/AL-Go/assets/10775043/c7527963-d728-413b-82bc-c9185674026f) + ![CI Workflow](https://github.com/microsoft/AL-Go/assets/10775043/c7527963-d728-413b-82bc-c9185674026f) 1. This time it should be passing and if you investigate the CI/CD workflow, you will see that the deploy step has been skipped as no environment existed. -![Success](https://github.com/microsoft/AL-Go/assets/10775043/4977dd06-36f3-45e1-a91b-991047f1604c) + ![Success](https://github.com/microsoft/AL-Go/assets/10775043/4977dd06-36f3-45e1-a91b-991047f1604c) + +______________________________________________________________________ ---- [back](../README.md) diff --git a/Scenarios/AddPowerPlatformProject.md b/Scenarios/AddPowerPlatformProject.md index f2b6d0c17..79915eb07 100644 --- a/Scenarios/AddPowerPlatformProject.md +++ b/Scenarios/AddPowerPlatformProject.md @@ -7,29 +7,32 @@ - A GitHub Account > **NOTE:** AL-Go App source does not currently support Power Platform solutions. + ## Steps 1. Create a new repository based on the AL-Go-PTE template from [microsoft/AL-Go-PTE](https://github.com/microsoft/AL-Go-PTE) - ![Screen shot from GitHub showing how ot create a new repository based on the AL-Go-PTE template](https://github.com/microsoft/AL-Go/assets/10775043/09c4998b-7c1b-4b3e-ad0d-412a377fff0d) + ![Screen shot from GitHub showing how ot create a new repository based on the AL-Go-PTE template](https://github.com/microsoft/AL-Go/assets/10775043/09c4998b-7c1b-4b3e-ad0d-412a377fff0d) -1. Once the repository is set up, configure your Business Central and Power Platform authentication and deployment settings (See [Power Platform Repository setup](./SetupPowerPlatform.md) for detailed steps). +1. Once the repository is set up, configure your Business Central and Power Platform authentication and deployment settings (See [Power Platform Repository setup](./SetupPowerPlatform.md) for detailed steps). 1. If you already have a solution ready in your Power App repository, use the new "Pull Power Platform changes" action to have your solution and artifacts pulled into your repository. - ![Screen shot from GitHub showing how to pull Power Platform changes](https://github.com/microsoft/AL-Go/assets/10775043/2d0a9321-8446-401d-8644-39c4dad62b53) + ![Screen shot from GitHub showing how to pull Power Platform changes](https://github.com/microsoft/AL-Go/assets/10775043/2d0a9321-8446-401d-8644-39c4dad62b53) 1. If you do not already have a solution ready in your Power App repository, follow these steps: - - Go to [make.powerapps.com](https://make.powerapps.com) - - Create a new solution - - Start building your Power Platform artifacts - - Run the pull action when you are ready to pull the artifacts into your repository + - Go to [make.powerapps.com](https://make.powerapps.com) + - Create a new solution + - Start building your Power Platform artifacts + - Run the pull action when you are ready to pull the artifacts into your repository 1. Use the **Pull Power Platform Changes** action to get the latest changes from your Power Platform development environment and either check-in directly or create a PR to review them beforehand. - > **NOTE:** Changes need to be published in Power Platform before they are included in the Pull action. A lot of the Power App source files contain state information and are safe to overwrite in case of conflicts. The connection files and the YAML files under Srs are the ones it makes sense to review. + > **NOTE:** Changes need to be published in Power Platform before they are included in the Pull action. A lot of the Power App source files contain state information and are safe to overwrite in case of conflicts. The connection files and the YAML files under Srs are the ones it makes sense to review. + 1. After your changes are checked into a branch in the repository, you can use the **Push Power Platform changes** to deploy them to an environment. Or use the **CI/CD** flow or **Publish to Environment** action to deploy both the AL and Power Platform solutions. ---- -[back](../README.md) \ No newline at end of file +______________________________________________________________________ + +[back](../README.md) diff --git a/Scenarios/AppDependencies.md b/Scenarios/AppDependencies.md index 118b20283..8d630433b 100644 --- a/Scenarios/AppDependencies.md +++ b/Scenarios/AppDependencies.md @@ -26,5 +26,6 @@ The `appDependencyProbingPaths` key in the settings expects a json array with th **projects** specifies the project in a multi project repository. “\*” means all projects. ---- +______________________________________________________________________ + [back](../README.md) diff --git a/Scenarios/Codesigning.md b/Scenarios/Codesigning.md index 6eb8f3d5c..a240f2e16 100644 --- a/Scenarios/Codesigning.md +++ b/Scenarios/Codesigning.md @@ -1,26 +1,30 @@ # Code signing in AL-Go -On June 1st 2023 the industry standards for storing code signing certificates changed. Certificate Authorities now require code signing certificates to be stored on Hardware Security Modules (HSM) or Hardware Tokens that are certified with FIPS 140-2 Level 2 or equivalent. Code signing certificates issued after this date are therefore only issued via physical USB tokens, into on-premises HSM services, or cloud HSM services such as Azure Key Vault. In AL-Go we have decided to opt for using Azure Key Vaults to store code signing certificates and .NET Sign to sign files. -This guide will take you through how to set up your AL-Go project with an Azure Key Vault and how to use a certificate in the Key Vault to perform code signing. Before you get started, please make sure you've set up your AL-Go project with an Azure Key Vault by following [Scenario 7: Use Azure KeyVault for secrets with AL-Go](./UseAzureKeyVault.md). +On June 1st 2023 the industry standards for storing code signing certificates changed. Certificate Authorities now require code signing certificates to be stored on Hardware Security Modules (HSM) or Hardware Tokens that are certified with FIPS 140-2 Level 2 or equivalent. Code signing certificates issued after this date are therefore only issued via physical USB tokens, into on-premises HSM services, or cloud HSM services such as Azure Key Vault. In AL-Go we have decided to opt for using Azure Key Vaults to store code signing certificates and .NET Sign to sign files. -> [!NOTE] +This guide will take you through how to set up your AL-Go project with an Azure Key Vault and how to use a certificate in the Key Vault to perform code signing. Before you get started, please make sure you've set up your AL-Go project with an Azure Key Vault by following [Scenario 7: Use Azure KeyVault for secrets with AL-Go](./UseAzureKeyVault.md). + +> \[!NOTE\] > If your code signing certificate was issued after June 1st 2023 you will most likely need to create a Premium SKU Key Vault. You can [learn more about the differences between Standard and Premium SKU here](https://azure.microsoft.com/en-us/pricing/details/key-vault/) ## Setting up your Azure Key Vault for code signing -1. Import your certificate into the Key Vault. + +1. Import your certificate into the Key Vault. How you do this might depend on which Certificate Authority you are getting your certificate from. DigiCert and GlobalSign have integrations with Azure Key Vault. You can follow [this guide](https://learn.microsoft.com/en-us/azure/key-vault/certificates/how-to-integrate-certificate-authority) on how to set up that integration if you are using one of those CAs. Once you have set up the integration, you can request a certificate from within your Azure Key Vault. If you are using another CA you can try following this guide to [Generate a CSR and Install a Certificate in Microsoft Azure Key Vault](https://www.ssl.com/how-to/generate-csr-install-certificate-microsoft-azure-key-vault/). If neither of those options work for you, please engage with your CA to get the certificate into the Key Vault. 2. Configure an Azure Key Vault access policy for the service principal that will be used for signing. At minimum, the account needs the following permissions: -* Cryptographic Operations: Sign -* Certificate Management Operations: Get -![Key Vault Access Policies](https://github.com/microsoft/AL-Go/assets/117829001/c93375e0-ce5b-4aa0-a6b9-a845a87fddef) +- Cryptographic Operations: Sign +- Certificate Management Operations: Get + ![Key Vault Access Policies](https://github.com/microsoft/AL-Go/assets/117829001/c93375e0-ce5b-4aa0-a6b9-a845a87fddef) ## Setting up AL-Go for Code Signing + Once you have an Azure Key Vault with your certificate in it and a Service Principal with access to the Key Vault you are ready to set up AL-Go for code signing. 1. Update your AL-Go settings with + ```json "keyVaultCodesignCertificateName": "" ``` diff --git a/Scenarios/Contribute.md b/Scenarios/Contribute.md index 82f633a5c..cd385fa8b 100644 --- a/Scenarios/Contribute.md +++ b/Scenarios/Contribute.md @@ -3,23 +3,24 @@ This section describes how to contribute to AL-Go. How to set up your own environment (your own set of actions and your own templates) You can do this in two ways: + - Use a fork of AL-Go for GitHub in your own **personal GitHub account** in development mode - Use 3 public repositories in your own **personal GitHub account** (AL-Go-PTE, AL-Go-AppSource and AL-Go-Actions, much like in production) ## Use a fork of AL-Go for GitHub in "development mode" 1. Fork the [https://github.com/microsoft/AL-Go](https://github.com/microsoft/AL-Go) repository to your **personal GitHub account**. -2. You can optionally also create a branch in the AL-Go fork for the feature you are working on. +1. You can optionally also create a branch in the AL-Go fork for the feature you are working on. **https://github.com//AL-Go@** can now be used as a template in your AL-Go project when running _Update AL-Go System Files_ to use the actions/workflows from this fork. ## Use 3 public repositories in "production mode" 1. Fork the [https://github.com/microsoft/AL-Go](https://github.com/microsoft/AL-Go) repository to your **personal GitHub account**. -2. Navigate to [https://github.com/settings/tokens/new](https://github.com/settings/tokens/new) and create a new personal access token with **Full control of private repositories** and **workflow** permissions. -3. In your personal fork of AL-Go, create a New Repository Secret called **OrgPAT** with your personal access token as content. See **https://github.com/yourGitHubUserName/AL-Go/settings/secrets/actions**. -4. In your personal fork of AL-Go, navigate to **Actions**, select the **Deploy** workflow and choose **Run Workflow**. -5. Using the default settings press **Run workflow**. Select the AL-Go branch to run from and the branch to deploy to. +1. Navigate to [https://github.com/settings/tokens/new](https://github.com/settings/tokens/new) and create a new personal access token with **Full control of private repositories** and **workflow** permissions. +1. In your personal fork of AL-Go, create a New Repository Secret called **OrgPAT** with your personal access token as content. See **https://github.com/yourGitHubUserName/AL-Go/settings/secrets/actions**. +1. In your personal fork of AL-Go, navigate to **Actions**, select the **Deploy** workflow and choose **Run Workflow**. +1. Using the default settings press **Run workflow**. Select the AL-Go branch to run from and the branch to deploy to. Now you should have 3 new public repositories: @@ -27,7 +28,7 @@ Now you should have 3 new public repositories: - [https://github.com/yourGitHubUserName/AL-Go-AppSource](https://github.com/yourGitHubUserName/AL-Go-AppSource) - [https://github.com/yourGitHubUserName/AL-Go-PTE](https://github.com/yourGitHubUserName/AL-Go-PTE) -> [!NOTE] +> \[!NOTE\] > Deploying to a branch called **preview** will only update the two template repositories (and use your AL-Go project with the current SHA as actions repository). You can optionally also create a branch in the AL-Go fork for the feature you are working on and then select that branch when running Deploy (both as **Use workflow from** and as **Branch to deploy to**). @@ -36,14 +37,21 @@ You can optionally also create a branch in the AL-Go fork for the feature you ar Please ensure that all unit tests run and create a Pull Request against [https://github.com/microsoft/AL-Go](https://github.com/microsoft/AL-Go). You are very welcome to run the end to end tests as well, but we will also run the end to end tests as part of the code review process. -> [!NOTE] +> \[!NOTE\] > You can also deploy to a different branch in the 3 public repositories by specifying a branch name under **Branch to deploy** to when running the **Deploy** workflow. The branch you specify in **Use workflow from** indicates which branch in **your personal fork of the AL-Go repository** you publish to the 3 repositories. +## Pre-Commit + +In the AL-Go repository we use a number of precommit hooks to help us identify issues in the code. We run the precommit hooks locally but also as a PR check. In order to ensure this check passes please install pre-commit in your local AL-Go repository. Pre-Commit can be installed by following the instructions on https://pre-commit.com/#quick-start. Once the precommint hooks are installed you can run `pre-commit run --all-files` to verify your changes. + ## Unit tests + The Tests folder, in the AL-Go repository, contains a number of unit-tests. Open Tests/runtests.ps1 in VS Code and select Run. Unit tests are quick and will run on every PR and every Push. We will be adding a lot of unit tests going forward. ## End to End tests + In the e2eTests folder, in the AL-Go repository, there are 3 types of end to end tests. + - Test-AL-Go.ps1 contains an end-2-end test scenario and is in E2E.yaml run for all combinations of Public/Private, Windows/Linux, Single/Multiproject and PTE/AppSource. - Test-AL-Go-Upgrade.ps1 contains an end-2-end upgrade scenario and is run for all prior releases of AL-Go for GitHub to test that you can successfully upgrade that version to the latestand run CI/CD successfully. - The scenarios folder contains a set of AL-Go scenarios, which tests specific functionality end to end. Every folder under e2eTests/scenarios, which contains a runtests.ps1 will be run as a scenario test, like: @@ -54,6 +62,7 @@ In the e2eTests folder, in the AL-Go repository, there are 3 types of end to end - SpecialCharacters - testing that various settings (+ publisher name and app name) can contain special national characters In your personal fork, you can now run the end to end tests, if the following pre-requisites are available: + - You need the following secrets: - E2EPAT needs to be a Personal Access Token with these permissions: _admin:org, delete:packages, delete_repo, repo, workflow, write:packages_ - AdminCenterApiCredentials needs to be the adminCenterApiCredentials as described [here](CreateOnlineDevEnv2.md). @@ -75,5 +84,6 @@ You can also run the end to end tests directly from VS Code, by providing the fo |$global:pteTemplate| String | URL for your PTE template (like `freddyk/AL-Go-PTE@main` or `freddydk/AL-Go@main\|Templates/Per Tenant Extension` for using your AL-Go fork directly) | |$global:appSourceTemplate| String | URL for your PTE template (like `freddyk/AL-Go-AppSource@main` or `freddydk/AL-Go@main\|Templates/AppSource App` for using your AL-Go fork directly) | ---- +______________________________________________________________________ + [back](../README.md) diff --git a/Scenarios/CreateOnlineDevEnv.md b/Scenarios/CreateOnlineDevEnv.md index b9c94a56f..7bd74b5ea 100644 --- a/Scenarios/CreateOnlineDevEnv.md +++ b/Scenarios/CreateOnlineDevEnv.md @@ -1,19 +1,21 @@ # #8 Create Online Development Environment from VS Code + *Prerequisites: A completed [scenario 7](UseAzureKeyVault.md)* 1. Open your **App1** project in VS Code, open the **cloudDevEnv.ps1** in your **.AL-Go** folder and run the script. -![Cloud DevEnv](https://github.com/microsoft/AL-Go/assets/10775043/adfafea6-4136-4120-95e7-45e7313cc67d) + ![Cloud DevEnv](https://github.com/microsoft/AL-Go/assets/10775043/adfafea6-4136-4120-95e7-45e7313cc67d) 1. The script will ask for an **environment name** if it isn’t specified and it will ask whether you want to reuse or **recreate** the environment if it already exists. After this the script will need access to the **admin center API** and will initiate a **device code login** for this purpose. -![Cloud DevEnv](https://github.com/microsoft/AL-Go/assets/10775043/ce042a0a-0a91-481f-8752-4fa40ec78424) + ![Cloud DevEnv](https://github.com/microsoft/AL-Go/assets/10775043/ce042a0a-0a91-481f-8752-4fa40ec78424) 1. Open [https://aka.ms/devicelogin](https://aka.ms/devicelogin) and paste in the **code provided**, sign in and accept that you are trying to sign in with PowerShell. -![Cloud DevEnv](https://github.com/microsoft/AL-Go/assets/10775043/751bb507-1a5e-436f-8a2a-1acdd53c33ab) + ![Cloud DevEnv](https://github.com/microsoft/AL-Go/assets/10775043/751bb507-1a5e-436f-8a2a-1acdd53c33ab) 1. Wait for the script to finish. All apps are compiled and published to the online environment using the development scope and **VS Code is ready for RAD development** -![Cloud DevEnv](https://github.com/microsoft/AL-Go/assets/10775043/20c5848a-3238-4fed-a1f2-36dd027884cd) + ![Cloud DevEnv](https://github.com/microsoft/AL-Go/assets/10775043/20c5848a-3238-4fed-a1f2-36dd027884cd) 1. Modify your app, press **F5** and select the **Cloud Sandbox** with your new name. -![Cloud DevEnv](https://github.com/microsoft/AL-Go/assets/10775043/7cebf477-28ff-4746-9004-c5075015b7c8) + ![Cloud DevEnv](https://github.com/microsoft/AL-Go/assets/10775043/7cebf477-28ff-4746-9004-c5075015b7c8) 1. Your online environment will have your app changes. -![Cloud DevEnv](https://github.com/microsoft/AL-Go/assets/10775043/6c5b5ebd-c46e-41e6-bc5e-e25344ecb3ae) + ![Cloud DevEnv](https://github.com/microsoft/AL-Go/assets/10775043/6c5b5ebd-c46e-41e6-bc5e-e25344ecb3ae) 1. The `launch.json` file will be updated with your new environment in VS Code. You can decide whether you want to check-in the changes to the repo or only use this locally. ---- +______________________________________________________________________ + [back](../README.md) diff --git a/Scenarios/CreateOnlineDevEnv2.md b/Scenarios/CreateOnlineDevEnv2.md index 71be60f40..cd530c7c2 100644 --- a/Scenarios/CreateOnlineDevEnv2.md +++ b/Scenarios/CreateOnlineDevEnv2.md @@ -1,4 +1,5 @@ # #9 Create Online Development Environment from GitHub + *Prerequisites: A completed [scenario 7](UseAzureKeyVault.md).* *To create an online development environment, we need to authenticate to our Business Central Admin API using OAuth. The Create Online Dev. Environment workflow works unattended if you provide a secret called **AdminCenterApiCredentials** (either as a GitHub Secret or in a keyvault). @@ -17,10 +18,11 @@ At the time when writing this, the Admin Center API does not yet support S2S, me ![Devicecode](https://github.com/microsoft/AL-Go/assets/10775043/5c898ee3-3ad9-4a0b-8ed5-5cdbbc0c802c) 1. On github.com, under **Actions** select the **Create Online Dev. Environment** workflow, choose **Run workflow** and specify the requested **environment name** and whether you want to **reuse the environment** if it already exists and choose **Run workflow**. -![Run Workflow](https://github.com/microsoft/AL-Go/assets/10775043/34386824-c4ca-4dab-8a81-6fa8868e2dfc) + ![Run Workflow](https://github.com/microsoft/AL-Go/assets/10775043/34386824-c4ca-4dab-8a81-6fa8868e2dfc) 1. When the workflow is complete, inspect the pull request to see the changes in **launch.json**. This environment can now be used from a developer but **note** that two developers cannot share one online environment. -![launch.json](https://github.com/microsoft/AL-Go/assets/10775043/797260fc-9a4b-4980-a5f1-2af3ba177c50) + ![launch.json](https://github.com/microsoft/AL-Go/assets/10775043/797260fc-9a4b-4980-a5f1-2af3ba177c50) 1. Merge the pull request and you are ready to do rapid application development (RAD). ---- +______________________________________________________________________ + [back](../README.md) diff --git a/Scenarios/CreateRelease.md b/Scenarios/CreateRelease.md index 5bec50df6..ee15c6076 100644 --- a/Scenarios/CreateRelease.md +++ b/Scenarios/CreateRelease.md @@ -1,14 +1,16 @@ # #4 Create a release of your application + *Prerequisites: A completed [scenario 3](RegisterSandboxEnvironment.md)* 1. On github.com, open **Actions** in your project and select **Create Release**. Choose **Run workflow**. Enter 1.0 as **name** and **tag** of the release, and then choose **Run workflow**. -![Run workflow](https://github.com/microsoft/AL-Go/assets/10775043/3c559c16-6066-491a-b205-be4f34c9c9a0) + ![Run workflow](https://github.com/microsoft/AL-Go/assets/10775043/3c559c16-6066-491a-b205-be4f34c9c9a0) 1. When the **create release** workflow completes, choose the **Code** section to see the releases. -![Run workflow](https://github.com/microsoft/AL-Go/assets/10775043/72a2c3f5-c0f0-43b9-bac7-29b8a4f40755) + ![Run workflow](https://github.com/microsoft/AL-Go/assets/10775043/72a2c3f5-c0f0-43b9-bac7-29b8a4f40755) 1. Choose the release (1.0) and you will see the release. The release notes are pulled from all pull-requests checked in since the last release. The auto-generated release note also contains a list of the new contributers and a link to the full changelog. Choose the **Edit** button (the pencil) to modify the release notes. At the bottom, you can see the artifacts published, both the apps and the source code. A tag is created in the repository for the release number to always keep this. -![Run workflow](https://github.com/microsoft/AL-Go/assets/10775043/79b94990-afc3-4217-ace9-3d5e19d6c5b6) + ![Run workflow](https://github.com/microsoft/AL-Go/assets/10775043/79b94990-afc3-4217-ace9-3d5e19d6c5b6) 1. Under **Actions**, select the **CI/CD** workflow and choose **Run workflow** to kick off a new CI/CD workflow. After the CI/CD workflow finishes, you can inspect the workflow output to see that the latest release was used as a baseline for the upgrade tests in the pipeline. You will also see that the new build, just created was deployed to the QA environment automatically. -![Run workflow](https://github.com/microsoft/AL-Go/assets/10775043/7c684aba-a680-449c-96bf-e9600342bcd1) + ![Run workflow](https://github.com/microsoft/AL-Go/assets/10775043/7c684aba-a680-449c-96bf-e9600342bcd1) + +______________________________________________________________________ ---- [back](../README.md) diff --git a/Scenarios/EnableKeyVaultForAppSourceApp.md b/Scenarios/EnableKeyVaultForAppSourceApp.md index 7097df911..40bb6bdd8 100644 --- a/Scenarios/EnableKeyVaultForAppSourceApp.md +++ b/Scenarios/EnableKeyVaultForAppSourceApp.md @@ -1,10 +1,12 @@ # #12 Enable KeyVault access for your AppSource App during development and/or tests + For AppSource apps, if you want to enable KeyVault access for your app (as described [here](https://go.microsoft.com/fwlink/?linkid=2217058&clcid=0x409) you can add the access to this keyvault in your local development environment or your pipelines (for running tests) by adding 3 secrets to either the GitHub repo or your KeyVault. Based on [this walkthrough](https://go.microsoft.com/fwlink/?linkid=2216856&clcid=0x409) you will need to create 3 secrets: + - A **KeyVaultClientId**, which is the Client ID for the Microsoft Entra application registration with access to the KeyVault. - A **KeyVaultCertificateUrl**, pointing to a certificate which gives you access to the Microsoft Entra application registration. - A **KeyVaultCertificatePassword**, which is the password for this certificate. -In the case of KeyVault access for apps, it is not enough to just add the secrets, you will also have to add information in the **.AL-Go\settings.json** that this app uses this KeyVault. Add these three settings +In the case of KeyVault access for apps, it is not enough to just add the secrets, you will also have to add information in the **.AL-Go\\settings.json** that this app uses this KeyVault. Add these three settings ```json "KeyVaultCertificateUrlSecretName": "KeyVaultCertificateUrl", @@ -14,5 +16,6 @@ In the case of KeyVault access for apps, it is not enough to just add the secret With this, containers set up for build pipelines or development environments will have access to this keyvault. ---- +______________________________________________________________________ + [back](../README.md) diff --git a/Scenarios/EnablingTelemetry.md b/Scenarios/EnablingTelemetry.md index 6c3dde225..3d0f0c9e7 100644 --- a/Scenarios/EnablingTelemetry.md +++ b/Scenarios/EnablingTelemetry.md @@ -54,5 +54,6 @@ Here is a list of the telemetry signals for different workflows: | DO0103 | AL-Go workflow ran: PublishToAppSource | | DO0104 | AL-Go workflow ran: PullRequestHandler | ---- +______________________________________________________________________ + [back](../README.md) diff --git a/Scenarios/GetStarted.md b/Scenarios/GetStarted.md index 0af83047e..a9bb25527 100644 --- a/Scenarios/GetStarted.md +++ b/Scenarios/GetStarted.md @@ -1,37 +1,39 @@ # #1 Create a new per-tenant extension (like AL:Go in VS Code) and start developing in VS Code + *Prerequisites: A GitHub account, VS-Code (with AL and PowerShell extensions installed), and Docker installed locally* 1. Navigate to [https://github.com/microsoft/AL-Go-PTE](https://github.com/microsoft/AL-Go-PTE) and choose **Use this template** -![Use this template](https://github.com/microsoft/AL-Go/assets/10775043/b808352c-c293-4ed3-b460-40e7b0ec36e9) + ![Use this template](https://github.com/microsoft/AL-Go/assets/10775043/b808352c-c293-4ed3-b460-40e7b0ec36e9) 1. Enter **app1** as repository name, select Public or Private and select **Create Repository from template** 1. Select **Actions** -> **Create a new app** -> **Run workflow** -![Run workflow](https://github.com/microsoft/AL-Go/assets/10775043/6c1ac9c3-14c2-4917-a31a-d94e5bb7bd66) + ![Run workflow](https://github.com/microsoft/AL-Go/assets/10775043/6c1ac9c3-14c2-4917-a31a-d94e5bb7bd66) 1. Enter **Name**, **Publisher**, **ID range** and specify **Y** in **Direct Commit** and choose **Run workflow**. -1. When the workflow is complete, select **< > Code** in the top bar +1. When the workflow is complete, select **\< > Code** in the top bar 1. Choose the **Code** button and copy the **https Clone Url** (in this picture: *https://github.com/freddydk/App1.git*) -![Clone](https://github.com/microsoft/AL-Go/assets/10775043/84b92edb-72b8-4444-908c-0c6f6bc2b7f7) + ![Clone](https://github.com/microsoft/AL-Go/assets/10775043/84b92edb-72b8-4444-908c-0c6f6bc2b7f7) 1. Start **VS Code**, press **Ctrl+Shift+P** and select **Git Clone**, paste the clone URL and select a folder in which you want to clone the directory. 1. **Open the cloned repository** and **open the workspace** when VS Code asks you (or do it manually) -> [!NOTE] +> \[!NOTE\] > You can rename the `al.code-workspace` file to `.code-workspace` to be able to better distinguish the workspaces. 1. In the **.AL-Go** folder, choose the **localDevEnv.ps1** script and Run the PowerShell script. -![LocalDevEnv](https://github.com/microsoft/AL-Go/assets/10775043/fded935a-b529-4ade-8daa-bbe7e37726b8) + ![LocalDevEnv](https://github.com/microsoft/AL-Go/assets/10775043/fded935a-b529-4ade-8daa-bbe7e37726b8) 1. Answer the questions asked about container name, authentication mechanism, credentials and select none for license file. The script might show a dialog asking for permissions to run docker commands, select **Yes** in this dialog. Wait for completion of the script. -![LocalDevEnv Done](https://github.com/microsoft/AL-Go/assets/10775043/6d88b2b8-3198-4c4e-8f4e-292178fa2e9f) + ![LocalDevEnv Done](https://github.com/microsoft/AL-Go/assets/10775043/6d88b2b8-3198-4c4e-8f4e-292178fa2e9f) 1. In VS Code, press **Ctrl+Shift+P** and **clear the credentials cache**. 1. Open the **HelloWorld.al** file, modify the string and press **F5**. Depending on authentication selected VS Code might ask for the credentials you provided earlier. 1. Login to **Business Central** and your **very own world** opens up! -![Very own world](https://github.com/microsoft/AL-Go/assets/10775043/02037442-b604-4ea7-9ec4-256a5fafad4a) + ![Very own world](https://github.com/microsoft/AL-Go/assets/10775043/02037442-b604-4ea7-9ec4-256a5fafad4a) 1. Back in **VS Code**, you will see that in addition to your changes in HelloWorld.al, the launch.json was also modified with the information about the local environment. **Stage your changes**, **commit** and **push** -![Launch.json](https://github.com/microsoft/AL-Go/assets/10775043/b71daf76-3166-4d33-8724-160ac3f60e31) + ![Launch.json](https://github.com/microsoft/AL-Go/assets/10775043/b71daf76-3166-4d33-8724-160ac3f60e31) 1. Back on github.com, investigate your **Workflows**. -![Workflows](https://github.com/microsoft/AL-Go/assets/10775043/aaef1edb-9e42-4de4-bec2-e21b2da1ae61) + ![Workflows](https://github.com/microsoft/AL-Go/assets/10775043/aaef1edb-9e42-4de4-bec2-e21b2da1ae61) 1. When the build is done, inspect the **Build summary** (no test app) -![Build Summary](https://github.com/microsoft/AL-Go/assets/10775043/f6a25fff-eef0-433c-84b0-e12b0b62008a) + ![Build Summary](https://github.com/microsoft/AL-Go/assets/10775043/f6a25fff-eef0-433c-84b0-e12b0b62008a) 1. Inspect the workflow run by choosing the **build job**, expanding the **Run Pipeline** section and the **Compiling apps** subsection -![Inspect](https://github.com/microsoft/AL-Go/assets/10775043/20a6da2b-33fe-4ebc-ad05-786e7700eeb6) + ![Inspect](https://github.com/microsoft/AL-Go/assets/10775043/20a6da2b-33fe-4ebc-ad05-786e7700eeb6) + +______________________________________________________________________ ---- [back](../README.md) diff --git a/Scenarios/MigrateFromAzureDevOpsWithHistory.md b/Scenarios/MigrateFromAzureDevOpsWithHistory.md index 25b80b702..c4e327d3f 100644 --- a/Scenarios/MigrateFromAzureDevOpsWithHistory.md +++ b/Scenarios/MigrateFromAzureDevOpsWithHistory.md @@ -1,61 +1,79 @@ # #B Migrate a repository from Azure DevOps to AL-Go for GitHub with history + *This walkthrough explains how to migrate a repository from Azure DevOps to AL-Go for GitHub **while preserving the full commit history**. As a sample, I will use a repository, which was setup using the CI/CD Hands On Lab, including scripts and pipelines from this.* *If you do not want to preserve the full commit history, you should use [Scenario A](MigrateFromAzureDevOpsWithoutHistory.md) or [Scenario 11](SetupCiCdForExistingAppSourceApp.md)* -> [!NOTE] +> \[!NOTE\] > This walkthrough will leave your existing Azure DevOps repository untouched and you can decide to keep working in that if you like. 1. Start out by navigating to your **Azure DevOps** repository. Click the **Clone** button and click **Generate Git Credentials**. -![Azure DevOps](https://github.com/microsoft/AL-Go/assets/10775043/59b623eb-56da-4821-8869-b27a34954597) + ![Azure DevOps](https://github.com/microsoft/AL-Go/assets/10775043/59b623eb-56da-4821-8869-b27a34954597) + 1. Copy the **Password** to the clipboard, navigate to **GitHub**, login and click the small **+** menu in the top right corner and select **Import repository**. -![files](https://github.com/microsoft/AL-Go/assets/10775043/9b8eb461-e03a-4c77-b0d2-be5bbb2ea25b) + ![files](https://github.com/microsoft/AL-Go/assets/10775043/9b8eb461-e03a-4c77-b0d2-be5bbb2ea25b) + 1. Enter the **GIT URL** to the Azure DevOps repository, choose the owner+name of the new GitHub repository and specify privacy level. Click **Begin Import**. -![createrepo](https://github.com/microsoft/AL-Go/assets/10775043/2f94e677-f713-4771-953a-16d7f1a8a0aa) + ![createrepo](https://github.com/microsoft/AL-Go/assets/10775043/2f94e677-f713-4771-953a-16d7f1a8a0aa) + 1. If your GIT repository requires **authentication**, you will be asked to provide this (the password you copied to the clipboard). -![auth](https://github.com/microsoft/AL-Go/assets/10775043/a3c16e8d-0ae4-43c0-99d1-4df57acf8551) + ![auth](https://github.com/microsoft/AL-Go/assets/10775043/a3c16e8d-0ae4-43c0-99d1-4df57acf8551) + 1. After GitHub is done importing your repo, you can **navigate to the repo**. -![importdone](https://github.com/microsoft/AL-Go/assets/10775043/7f7a6d5a-4d3b-4e47-8ac2-426dfd1a3c39) -1. In the new GitHub repository, you might see different messages about branches and PRs. This is because GitHub has imported everything. Ignore this for now. Click the **<> Code** button and copy the git address to the clipboard. -![newrepo](https://github.com/microsoft/AL-Go/assets/10775043/2089bcc3-8aa3-4582-be9d-3ce77364198a) + ![importdone](https://github.com/microsoft/AL-Go/assets/10775043/7f7a6d5a-4d3b-4e47-8ac2-426dfd1a3c39) + +1. In the new GitHub repository, you might see different messages about branches and PRs. This is because GitHub has imported everything. Ignore this for now. Click the **\<> Code** button and copy the git address to the clipboard. + ![newrepo](https://github.com/microsoft/AL-Go/assets/10775043/2089bcc3-8aa3-4582-be9d-3ce77364198a) + 1. Open **VS Code**, press **Ctrl+Shift+P**, select **Git Clone** and paste your git URL into the address bar. Select a location, clone and open the repo and open the Repo in VS Code. -![clone](https://github.com/microsoft/AL-Go/assets/10775043/4d91c31d-1aee-4fad-990e-73a075e69026) + ![clone](https://github.com/microsoft/AL-Go/assets/10775043/4d91c31d-1aee-4fad-990e-73a075e69026) + 1. Delete the files and folders that are not needed in AL-Go for GitHub (including **.github**, **.azureDevOps**, **.pipelines** and **scripts** folders), leaving only your **apps**, your **test apps** and other files you want to preserve. -![delete](https://github.com/microsoft/AL-Go/assets/10775043/e8d21772-30dc-448a-8892-92a66c7c36e6) + ![delete](https://github.com/microsoft/AL-Go/assets/10775043/e8d21772-30dc-448a-8892-92a66c7c36e6) + 1. Now, download the AL-Go template needed, either the [PTE template](https://github.com/microsoft/AL-Go-PTE/archive/refs/heads/main.zip) or the [AppSource Template](https://github.com/microsoft/AL-Go-AppSource/archive/refs/heads/main.zip). Unpack the .zip file and open the unpacked template files. -![templatefiles](https://github.com/microsoft/AL-Go/assets/10775043/7539c845-b696-4347-8b2f-d51d6be2ebfa) + ![templatefiles](https://github.com/microsoft/AL-Go/assets/10775043/7539c845-b696-4347-8b2f-d51d6be2ebfa) + 1. Drag the needed files and folders from the unpacked files file into VS Code (at a minimum the .AL-Go folder and the .github folder) and select to **Copy the folders**. -![newfiles](https://github.com/microsoft/AL-Go/assets/10775043/edd24801-73cd-4ad4-9fc6-5d2cd80ac6c8) + ![newfiles](https://github.com/microsoft/AL-Go/assets/10775043/edd24801-73cd-4ad4-9fc6-5d2cd80ac6c8) + 1. Modify any settings necessary for the app. Typical settings you might need to modify are: - - appFolders, see https://aka.ms/algosettings#appfolders - - testFolders, see https://aka.ms/algosettings#testfolders - - appSourceMandatoryAffixes, see https://aka.ms/algosettings#appSourceMandatoryAffixes - - enableAppSourceCop, see https://aka.ms/algosettings#enableAppSourceCop - - enablePerTenantExtensionCop, see https://aka.ms/algosettings#enablePerTenantExtensionCop - - enableCodeCop, see https://aka.ms/algosettings#enableCodeCop - - enableUICop, see https://aka.ms/algosettings#enableUICop - - rulesetFile, see https://aka.ms/algosettings#rulesetFile - - enableExternalRulesets, see https://aka.ms/algosettings#enableExternalRulesets - - runNumberOffset, see https://aka.ms/algosettings#runNumberOffset - Also, if you are migrating an AppSource App, you will need to create a secret called LicenseFileUrl, which should contain a secure direct download URL to your license file, as mentioned [here](SetupCiCdForExistingAppSourceApp.md). + - appFolders, see https://aka.ms/algosettings#appfolders + - testFolders, see https://aka.ms/algosettings#testfolders + - appSourceMandatoryAffixes, see https://aka.ms/algosettings#appSourceMandatoryAffixes + - enableAppSourceCop, see https://aka.ms/algosettings#enableAppSourceCop + - enablePerTenantExtensionCop, see https://aka.ms/algosettings#enablePerTenantExtensionCop + - enableCodeCop, see https://aka.ms/algosettings#enableCodeCop + - enableUICop, see https://aka.ms/algosettings#enableUICop + - rulesetFile, see https://aka.ms/algosettings#rulesetFile + - enableExternalRulesets, see https://aka.ms/algosettings#enableExternalRulesets + - runNumberOffset, see https://aka.ms/algosettings#runNumberOffset + + Also, if you are migrating an AppSource App, you will need to create a secret called LicenseFileUrl, which should contain a secure direct download URL to your license file, as mentioned [here](SetupCiCdForExistingAppSourceApp.md). - Finally, if you want AL-Go for GitHub to digitally sign your file, you need to create two secrets in the repository (or in the organization) called **CodeSignCertificateUrl** and **CodeSignCertificatePassword**, being a secure direct download URL to your PFX certificate and the PFX password for the certificate. + Finally, if you want AL-Go for GitHub to digitally sign your file, you need to create two secrets in the repository (or in the organization) called **CodeSignCertificateUrl** and **CodeSignCertificatePassword**, being a secure direct download URL to your PFX certificate and the PFX password for the certificate. - See a list of all settings [here](settings.md). + See a list of all settings [here](settings.md). 1. In VS Code, in the Source Control area, **Add** all changed files, **Commit** the changes and press **Sync Changes** to push to GitHub. -![commit](https://github.com/microsoft/AL-Go/assets/10775043/55afdd6f-e401-4542-9029-652f5ce7a3e9) + ![commit](https://github.com/microsoft/AL-Go/assets/10775043/55afdd6f-e401-4542-9029-652f5ce7a3e9) + 1. Navigate back to your repository on GitHub. See that your files have been uploaded. Click **Settings** -> **Actions** -> **General**, select **Allow all actions and reusable workflows** and click **Save**. -![upload](https://github.com/microsoft/AL-Go/assets/10775043/4f717190-5e5f-45e9-a187-186ac45be590) + ![upload](https://github.com/microsoft/AL-Go/assets/10775043/4f717190-5e5f-45e9-a187-186ac45be590) + 1. Click **Actions**, select the **CI/CD** workflow and click **Run workflow** to manually run the CI/CD workflow. -![cicd](https://github.com/microsoft/AL-Go/assets/10775043/ec7f76b1-2eb9-42fe-91a3-c0170c796d3c) + ![cicd](https://github.com/microsoft/AL-Go/assets/10775043/ec7f76b1-2eb9-42fe-91a3-c0170c796d3c) + 1. Open the running workflow to see **status and summary** and **wait for the build to complete**. -![success](https://github.com/microsoft/AL-Go/assets/10775043/8a1fcd6d-0a8d-4bbc-bb97-51a4c48e537a) + ![success](https://github.com/microsoft/AL-Go/assets/10775043/8a1fcd6d-0a8d-4bbc-bb97-51a4c48e537a) + 1. Scroll down to see the artifacts and the **test results** -![testresults](https://github.com/microsoft/AL-Go/assets/10775043/7267a1a7-7afe-495f-8100-474fb8db9499) + ![testresults](https://github.com/microsoft/AL-Go/assets/10775043/7267a1a7-7afe-495f-8100-474fb8db9499) + 1. Navigate to **Code** and click **Commits** to see the history and all your commits. -![history](https://github.com/microsoft/AL-Go/assets/10775043/c10ea3b3-2b1b-486d-9727-6b91b7bc3834) + ![history](https://github.com/microsoft/AL-Go/assets/10775043/c10ea3b3-2b1b-486d-9727-6b91b7bc3834) + +______________________________________________________________________ ---- [back](../README.md) diff --git a/Scenarios/MigrateFromAzureDevOpsWithoutHistory.md b/Scenarios/MigrateFromAzureDevOpsWithoutHistory.md index a7586ff38..35c263e5e 100644 --- a/Scenarios/MigrateFromAzureDevOpsWithoutHistory.md +++ b/Scenarios/MigrateFromAzureDevOpsWithoutHistory.md @@ -1,51 +1,64 @@ # #A Migrate a repository from Azure DevOps to AL-Go for GitHub without history + *This walkthrough explains how to migrate a repository from Azure DevOps to AL-Go for GitHub **without including the commit history**. As a sample, I will use a repository, which was setup using the CI/CD Hands On Lab, including scripts and pipelines from this.* *This walkthrough is similar to [scenario 11](SetupCiCdForExistingAppSourceApp.md), but uses VS Code and File Explorer to move the files instead of uploading a .zip file.* -> [!NOTE] +> \[!NOTE\] > This walkthrough will leave your existing Azure DevOps repository untouched and you can decide to keep working in that if you like. 1. Start out by navigating to your **Azure DevOps** repository. Click the **Clone** button. -![Azure DevOps](https://github.com/microsoft/AL-Go/assets/10775043/3e61f1c1-6e29-477e-a5da-92bf3228005a) + ![Azure DevOps](https://github.com/microsoft/AL-Go/assets/10775043/3e61f1c1-6e29-477e-a5da-92bf3228005a) + 1. Clone the repository to your PC by selecting Clone in **VS Code** (or your favorite way of cloning). And open the files in the **file explorer**. -![files](https://github.com/microsoft/AL-Go/assets/10775043/f9925c6a-215b-4475-a062-9aeb20a2f1ee) + ![files](https://github.com/microsoft/AL-Go/assets/10775043/f9925c6a-215b-4475-a062-9aeb20a2f1ee) + 1. Navigate to [https://aka.ms/algopte](https://aka.ms/algopte) or [https://aka.ms/algoappsource](https://aka.ms/algoappsource), click **Use this template**. Select **Create a new repository** and choose the owner + name of the repository and select public or private. Click **Create repository from template** and open the repository. -![createrepo](https://github.com/microsoft/AL-Go/assets/10775043/8b253c09-36aa-4334-94d1-9541f328ff06) -1. In the new repository, click the **<> Code** button and copy the git address to the clipboard. Open VS Code, press Ctrl+Shift+P, select **Git Clone** and paste your git URL into the address bar. Select a location, clone and open the repo and navigate to the File Explorer with the **Azure DevOps cloned files**. -![clone](https://github.com/microsoft/AL-Go/assets/10775043/94d1b0cd-96b4-48cb-bc10-0433d0e13e6c) + ![createrepo](https://github.com/microsoft/AL-Go/assets/10775043/8b253c09-36aa-4334-94d1-9541f328ff06) + +1. In the new repository, click the **\<> Code** button and copy the git address to the clipboard. Open VS Code, press Ctrl+Shift+P, select **Git Clone** and paste your git URL into the address bar. Select a location, clone and open the repo and navigate to the File Explorer with the **Azure DevOps cloned files**. + ![clone](https://github.com/microsoft/AL-Go/assets/10775043/94d1b0cd-96b4-48cb-bc10-0433d0e13e6c) + 1. In the file Explorer containing the cloned files from the Azure DevOps repo, select all the folders containing apps, test apps or other files you need to migrate over. Do not include the **.git**, **.github**, **.azureDevOps**, **.pipelines** and **scripts** folders - we won't be using them. Drag the files to VS Code and select **Copy Folders** -![copy](https://github.com/microsoft/AL-Go/assets/10775043/485d8117-f81e-4f18-8630-391d466ee5b6) + ![copy](https://github.com/microsoft/AL-Go/assets/10775043/485d8117-f81e-4f18-8630-391d466ee5b6) + 1. Modify any settings necessary for the app. Typical settings you might need to modify are: - - appFolders, see https://aka.ms/algosettings#appfolders - - testFolders, see https://aka.ms/algosettings#testfolders - - appSourceMandatoryAffixes, see https://aka.ms/algosettings#appSourceMandatoryAffixes - - enableAppSourceCop, see https://aka.ms/algosettings#enableAppSourceCop - - enablePerTenantExtensionCop, see https://aka.ms/algosettings#enablePerTenantExtensionCop - - enableCodeCop, see https://aka.ms/algosettings#enableCodeCop - - enableUICop, see https://aka.ms/algosettings#enableUICop - - rulesetFile, see https://aka.ms/algosettings#rulesetFile - - enableExternalRulesets, see https://aka.ms/algosettings#enableExternalRulesets - - runNumberOffset, see https://aka.ms/algosettings#runNumberOffset - Also, if you are migrating an AppSource App, you will need to create a secret called LicenseFileUrl, which should contain a secure direct download URL to your license file, as mentioned [here](SetupCiCdForExistingAppSourceApp.md). + - appFolders, see https://aka.ms/algosettings#appfolders + - testFolders, see https://aka.ms/algosettings#testfolders + - appSourceMandatoryAffixes, see https://aka.ms/algosettings#appSourceMandatoryAffixes + - enableAppSourceCop, see https://aka.ms/algosettings#enableAppSourceCop + - enablePerTenantExtensionCop, see https://aka.ms/algosettings#enablePerTenantExtensionCop + - enableCodeCop, see https://aka.ms/algosettings#enableCodeCop + - enableUICop, see https://aka.ms/algosettings#enableUICop + - rulesetFile, see https://aka.ms/algosettings#rulesetFile + - enableExternalRulesets, see https://aka.ms/algosettings#enableExternalRulesets + - runNumberOffset, see https://aka.ms/algosettings#runNumberOffset + + Also, if you are migrating an AppSource App, you will need to create a secret called LicenseFileUrl, which should contain a secure direct download URL to your license file, as mentioned [here](SetupCiCdForExistingAppSourceApp.md). - Finally, if you want AL-Go for GitHub to digitally sign your file, you need to create two secrets in the repository (or in the organization) called **CodeSignCertificateUrl** and **CodeSignCertificatePassword**, being a secure direct download URL to your PFX certificate and the PFX password for the certificate. + Finally, if you want AL-Go for GitHub to digitally sign your file, you need to create two secrets in the repository (or in the organization) called **CodeSignCertificateUrl** and **CodeSignCertificatePassword**, being a secure direct download URL to your PFX certificate and the PFX password for the certificate. - See a list of all settings [here](settings.md). + See a list of all settings [here](settings.md). 1. In VS Code, in the Source Control area, **Add** all changed files, **Commit** the changes and press **Sync Changes** to push to GitHub. -![commit](https://github.com/microsoft/AL-Go/assets/10775043/b5e0a078-581b-4a1b-bcbf-6b1e0f684255) + ![commit](https://github.com/microsoft/AL-Go/assets/10775043/b5e0a078-581b-4a1b-bcbf-6b1e0f684255) + 1. Navigate back to your repository on GitHub. See that your files have been uploaded. -![upload](https://github.com/microsoft/AL-Go/assets/10775043/a0e37ff1-6b9a-4a09-973e-79e3b2d06ad0) + ![upload](https://github.com/microsoft/AL-Go/assets/10775043/a0e37ff1-6b9a-4a09-973e-79e3b2d06ad0) + 1. Click **Actions** to see that the **CI/CD** workflow was kicked off with your migration files. -![cicd](https://github.com/microsoft/AL-Go/assets/10775043/2768cc67-dff4-47d6-906f-8c2eb3761e35) + ![cicd](https://github.com/microsoft/AL-Go/assets/10775043/2768cc67-dff4-47d6-906f-8c2eb3761e35) + 1. Open the running workflow to see **status and summary** and wait for the build to complete. -![success](https://github.com/microsoft/AL-Go/assets/10775043/1f1a7e3e-f8f4-4b5f-805d-c5357439c527) + ![success](https://github.com/microsoft/AL-Go/assets/10775043/1f1a7e3e-f8f4-4b5f-805d-c5357439c527) + 1. Scroll down to see the **artifacts** and the **test results**. -![testresults](https://github.com/microsoft/AL-Go/assets/10775043/130aef13-dbf1-4a4b-987c-74df6f915790) + ![testresults](https://github.com/microsoft/AL-Go/assets/10775043/130aef13-dbf1-4a4b-987c-74df6f915790) + 1. Navigate to **Code** and click **Commits** to see the history. -![history](https://github.com/microsoft/AL-Go/assets/10775043/7458a5cf-356d-41f1-8e48-5805dec584d6) + ![history](https://github.com/microsoft/AL-Go/assets/10775043/7458a5cf-356d-41f1-8e48-5805dec584d6) + +______________________________________________________________________ ---- [back](../README.md) diff --git a/Scenarios/PublishToAppSource.md b/Scenarios/PublishToAppSource.md index 434b70d6a..79c565bfa 100644 --- a/Scenarios/PublishToAppSource.md +++ b/Scenarios/PublishToAppSource.md @@ -1,7 +1,8 @@ # #17 Publish To AppSource + *Prerequisites: An app in AppSource and a GitHub Repository based on the [AL-Go-AppSource](https://aka.ms/AL-Go-AppSource) template with the source code for that app.* -> [!NOTE] +> \[!NOTE\] > The initial creation and upload of the your app on AppSource cannot be automated in AL-Go for GitHub. You have to do the first upload of marketing material manually and also the first upload of your app. After this, AL-Go for GitHub can be setup to publish updates to your app either continuously or manually by running a Workflow. As a sample app, I will use my AppSource app called [BingMaps.AppSource](https://appsource.microsoft.com/da-dk/product/dynamics-365-business-central/PUBID.microsoftdynsmb%7CAID.bingmapsintegration%7CPAPPID.4270bff7-c860-434f-b09a-0f3e37d243fd?tab=Overview), located on [microsoft/bcsamples-bingmaps.appsource](https://github.com/microsoft/bcsamples-bingmaps.appsource). @@ -34,6 +35,7 @@ $authcontext = New-BcAuthContext ` -tenantID "" New-ALGoAppSourceContext -authContext $authContext | Set-Clipboard ``` + This will invoke the device flow and display a code, which you need to use when authenticating to https://aka.ms/devicelogin ## Add AppSourceContext secret to AL-Go for GitHub @@ -68,10 +70,10 @@ The **productId GUID is mandatory** and must be specified in `deliverToAppSource The other properties in the deliverToAppSource structure are **optional** and determines whether or not Continuous Delivery (CD) is enabled during CI/CD, what appFolder contains the main app and which dependencies to include dependencies from other projects/repositories. -> [!NOTE] +> \[!NOTE\] > The includeDependencies requires you to also set `generateDependencyArtifact` to `true` (like shown above). GenerateDependencyArtifact will create a build and a release artifact with the dependent apps used for building the app. includeDependencies will include a number of these apps as library apps when submitting. -> [!NOTE] +> \[!NOTE\] > When having multiple projects in an AL-Go for GitHub repository, you should set `UseProjectDependencies` to `true` in the **repository settings file** *(.github/AL-Go-Settings.json)* and run Update AL-Go System Files to only build the library apps once and reuse them in the depending projects. The BingMaps.AppSource repository has 2 projects: **Main App** and **Library Apps**. The Main App projects contains three apps: **BingMaps-AppSource**, **BingMaps-AppSource.Test**, **BingMaps.Common**. The Library Apps contains only one app: **FreddyDK.Licensing**. The Main AppFolder is BingMaps-AppSource and all dependencies with Freddy Kristiansen as the publisher from other projects will be included as library apps. The BingMaps.Common app is always included (if referenced by the main app). Navigate to [microsoft/bcsamples-bingmaps.appsource](https://github.com/microsoft/bcsamples-bingmaps.appsource) and investigate. @@ -86,6 +88,6 @@ If you navigate to the BingMaps.AppSource repository, you should be able to see If you have set ContinuousDelivery to true, every app will be delivered to AppSource and taken through validation and made available in AppSource as preview. You then need to press **Go Live** in partner center or run the Publish To AppSource workflow in AL-Go for GitHub in order to publish the app to production. +______________________________________________________________________ ---- [back](../README.md) diff --git a/Scenarios/RegisterProductionEnvironment.md b/Scenarios/RegisterProductionEnvironment.md index bd7986b22..16ff07135 100644 --- a/Scenarios/RegisterProductionEnvironment.md +++ b/Scenarios/RegisterProductionEnvironment.md @@ -1,15 +1,16 @@ # #5 Register a customer production environment for Manual Deployment + *Prerequisites: A completed [scenario 4](CreateRelease.md), an online production environment setup for S2S as specified in task 2 here [Using Service to Service Authentication - Business Central | Microsoft Docs](https://go.microsoft.com/fwlink/?linkid=2217415&clcid=0x409), using the same Microsoft Entra application registration as scenario 3* -> [!NOTE] +> \[!NOTE\] > For access to environments, environment secrets, and deployment branches in private or internal repositories, you must use GitHub Pro, GitHub Team, or GitHub Enterprise. (see [this](https://go.microsoft.com/fwlink/?linkid=2216857&clcid=0x409)). We are considering adding a secondary option for listing environments. 1. Following the process in step 3, you can add an environment to the GitHub repository under settings called **MYPROD (Production)**, which maps to a production environment called **MYPROD**. Remember the **AUTHCONTEXT** Secret. Apps will NOT be deployed to production environments from the CI/CD pipeline, by adding the **(Production)** tag, the environment will be filtered out already during the **Analyze** phase. You need to run the **Publish To Environment** workflow to publish the apps. Leave the App version as **current**, which means that the **latest released bits** are published to **MYPROD**. -![Run workflow](https://github.com/microsoft/AL-Go/assets/10775043/43961e6f-c1ee-4640-9a9c-bbc70dec7fa7) + ![Run workflow](https://github.com/microsoft/AL-Go/assets/10775043/43961e6f-c1ee-4640-9a9c-bbc70dec7fa7) 1. After running the **Publish to Environment** workflow, you should see that the app was deployed to the **MYPROD** environment only. -![Run workflow](https://github.com/microsoft/AL-Go/assets/10775043/34ec03d5-a736-4b44-9229-34de32029ea3) + ![Run workflow](https://github.com/microsoft/AL-Go/assets/10775043/34ec03d5-a736-4b44-9229-34de32029ea3) -> [!NOTE] +> \[!NOTE\] > If your Business Central environment name contains spaces or special characters, you might need to map your GitHub environment name to your Business Central environment name using the DeployTo setting with an EnvironmentName setting called DeployTo. ```json @@ -18,5 +19,6 @@ } ``` ---- +______________________________________________________________________ + [back](../README.md) diff --git a/Scenarios/RegisterSandboxEnvironment.md b/Scenarios/RegisterSandboxEnvironment.md index 0069bf453..841105a77 100644 --- a/Scenarios/RegisterSandboxEnvironment.md +++ b/Scenarios/RegisterSandboxEnvironment.md @@ -1,20 +1,22 @@ # #3 Register a customer sandbox environment for Continuous Deployment using S2S -*Prerequisites: A completed [scenario 2](AddATestApp.md), an Microsoft Entra application registration, and an online sandbox environment called QA with the setup for S2S as specified in task 1 and 2 [here](https://go.microsoft.com/fwlink/?linkid=2217415&clcid=0x409) completed. -> [!NOTE] +\*Prerequisites: A completed [scenario 2](AddATestApp.md), an Microsoft Entra application registration, and an online sandbox environment called QA with the setup for S2S as specified in task 1 and 2 [here](https://go.microsoft.com/fwlink/?linkid=2217415&clcid=0x409) completed. + +> \[!NOTE\] > For access to environments, environment secrets, and deployment branches in private or internal repositories, you must use GitHub Pro, GitHub Team, or GitHub Enterprise. (see [this](https://go.microsoft.com/fwlink/?linkid=2216857&clcid=0x409)). We are considering adding a secondary option for listing environments. 1. On github.com, open **Settings** and **Environments** in your project. Click **New Environment** and specify the **name of the environment** you have created in your tenant. -![Add Environment](https://github.com/microsoft/AL-Go/assets/10775043/ec3d7bf3-84dd-4ca4-8c6c-b79d796afadf) + ![Add Environment](https://github.com/microsoft/AL-Go/assets/10775043/ec3d7bf3-84dd-4ca4-8c6c-b79d796afadf) 1. Under **Environment secrets**, choose the **Add Secret** action. Create a secret called **AUTHCONTEXT**, and enter a **COMPRESSED JSON** construct with 3 values: TenantID (where the environment lives), ClientID, and ClientSecret (from the pre-requisites), like: -`{"TenantID":"","ClientID":"","ClientSecret":""}`. -![Add Environment](https://github.com/microsoft/AL-Go/assets/10775043/79d41d03-7b94-4876-a44b-a4276473147a) + `{"TenantID":"","ClientID":"","ClientSecret":""}`. + ![Add Environment](https://github.com/microsoft/AL-Go/assets/10775043/79d41d03-7b94-4876-a44b-a4276473147a) 1. Navigate to **Actions**, select the **Publish To Environment** workflow and choose **Run workflow**. Enter **latest** in the **App version** field and the **name of your environment** or keep the * in the **environment to receive the new version** field. Click **Run workflow**. -![Add Environment](https://github.com/microsoft/AL-Go/assets/10775043/f207e06b-451d-4e31-8938-2c72f14c2527) + ![Add Environment](https://github.com/microsoft/AL-Go/assets/10775043/f207e06b-451d-4e31-8938-2c72f14c2527) 1. When the workflow completes, you can inspect the output of the workflow. -![Add Environment](https://github.com/microsoft/AL-Go/assets/10775043/fb6e4b5d-ce7b-4e9b-8f2d-ae07b554083f) + ![Add Environment](https://github.com/microsoft/AL-Go/assets/10775043/fb6e4b5d-ce7b-4e9b-8f2d-ae07b554083f) 1. And/or you can open the QA environment, navigate to Customers and see that your very own Hello World message appears. -![Add Environment](https://github.com/microsoft/AL-Go/assets/10775043/eed622b5-4299-4474-8a73-8eb9ce1b288c) + ![Add Environment](https://github.com/microsoft/AL-Go/assets/10775043/eed622b5-4299-4474-8a73-8eb9ce1b288c) + +______________________________________________________________________ ---- [back](../README.md) diff --git a/Scenarios/SelfHostedGitHubRunner.md b/Scenarios/SelfHostedGitHubRunner.md index 84fb85e4e..766d0fef6 100644 --- a/Scenarios/SelfHostedGitHubRunner.md +++ b/Scenarios/SelfHostedGitHubRunner.md @@ -1,26 +1,29 @@ # #13 Set up your own GitHub runner to increase build performance + *Prerequisites: An AL-Go repository setup using one of the scenarios* When running the CI/CD workflow, the build job is by far the most time-consuming job. By adding your own GitHub Runner, which can cache the generic image, the build image and also the artifacts, the time for running the build job can become much faster. GitHub runners can be registered for an organization (accessible for all repositories in the organization) or for a single repository. -1. Navigate to [https://github.com/organizations/{organization}/settings/actions/runners/new](https://github.com/organizations/{organization}/settings/actions/runners/new) to create a self-hosted runner for your organization. Use [https://github.com/{organization}/{repository}/settings/actions/runners](https://github.com/{organization}/{repository}/settings/actions/runners) to create a self-hosted runner for a single repository. -![Organization new runner](https://github.com/microsoft/AL-Go/assets/10775043/f09af5ee-73b5-40e3-bad1-98f0c7b0ddaa) +1. Navigate to [https://github.com/organizations/{organization}/settings/actions/runners/new](https://github.com/organizations/%7Borganization%7D/settings/actions/runners/new) to create a self-hosted runner for your organization. Use [https://github.com/{organization}/{repository}/settings/actions/runners](https://github.com/%7Borganization%7D/%7Brepository%7D/settings/actions/runners) to create a self-hosted runner for a single repository. + ![Organization new runner](https://github.com/microsoft/AL-Go/assets/10775043/f09af5ee-73b5-40e3-bad1-98f0c7b0ddaa) 1. Now, you can either [Use the Azure VM Template to create your self-hosted runner](#use-the-azure-vm-template-to-create-your-self-hosted-runner) or you can [Create your self-hosted runner manually](#create-your-self-hosted-runner-manually) ## Use the Azure VM Template to create your self-hosted runner + 1. To create an Azure VM hosting x self-hosted runners, open a new tab and navigate to [https://aka.ms/getbuildagent](https://aka.ms/getbuildagent). 1. Enter the **Resource Group name**, **Region**, **VM Name**, **Admin Password** of your choice. 1. Enter the **number of agents** you want to create on the VM. 1. Grab the **token**, the **organization Url**, and the **Agent Url** from the Create Self-Hosted runner page, and specify **self-hosted** in labels. -![getbuildagent](https://github.com/microsoft/AL-Go/assets/10775043/959e9872-1b54-46ee-b202-ca80724334f0) + ![getbuildagent](https://github.com/microsoft/AL-Go/assets/10775043/959e9872-1b54-46ee-b202-ca80724334f0) 1. Select **Review and Create** and then review the deployment and choose **Create**. 1. Wait for the Azure VM creation to finalize, navigate back to see that the Runners have been registered and are ready to use. -![Runners](https://github.com/microsoft/AL-Go/assets/10775043/ba90e239-a8ee-4297-8bed-a30e3fc3db8a) + ![Runners](https://github.com/microsoft/AL-Go/assets/10775043/ba90e239-a8ee-4297-8bed-a30e3fc3db8a) 1. Go to [Allow your repository access to your runners](#allow-your-repository-access-to-your-runners) to continue the configuration. ## Create your self-hosted runner manually + 1. To create a self-hosted runner manually, choose Windows under Runner Image and x64 in architecture and follow the description on how to create a self-hosted runner manually 1. Make sure that the following software is installed on the computer (the suggestion in parentheses explains the mechanism used in https://aka.ms/getbuildagent) - Docker (getbuildagent use [this script](https://github.com/microsoft/nav-arm-templates/blob/master/InstallOrUpdateDockerEngine.ps1) to install or update Docker Engine on the Azure VM) @@ -34,36 +37,39 @@ GitHub runners can be registered for an organization (accessible for all reposit - Microsoft .NET SDK (getbuildagent use `choco install dotnet-sdk -y`) - nuget.org added as dotnet nuget source (getbuildagent use `dotnet nuget add source https://api.nuget.org/v3/index.json --name nuget.org`) -> [!NOTE] +> \[!NOTE\] > If the Deploy Reference Documentation job results in an error like [this](https://github.com/actions/upload-pages-artifact/issues/95), then you need to check your GIT installation as described in the issue. ## Allow your repository access to your runners + 1. On the list of Runners on GitHub, choose the runner group **Default** and allow public repositories if your repository is public. -![public](https://github.com/microsoft/AL-Go/assets/10775043/9bdd01ab-ac67-44bf-bfd1-af5c5ec91364) + ![public](https://github.com/microsoft/AL-Go/assets/10775043/9bdd01ab-ac67-44bf-bfd1-af5c5ec91364) 1. Now navigate to your repo settings file (.github/AL-Go-Settings.json) and set **gitHubRunner** to **self-hosted**. - Note that you can use other tags than **self-hosted** to identify special runners for GitHub jobs, or you can set gitHubRunner to "self-hosted, Windows" to ensure that a Windows version is selected if you have self-hosted linux runners as well. 1. Save and inspect your workflows performance increase on the second run. 1. Inspect that one of the runners pick up the workflow. -![Active](https://github.com/microsoft/AL-Go/assets/10775043/dfcd369c-ad54-427e-92d4-153afda30b53) + ![Active](https://github.com/microsoft/AL-Go/assets/10775043/dfcd369c-ad54-427e-92d4-153afda30b53) 1. Clicking the runner reveals that the job it is running. -![Job](https://github.com/microsoft/AL-Go/assets/10775043/0ae30c22-9352-4864-a80e-81ed4ecd93e1) + ![Job](https://github.com/microsoft/AL-Go/assets/10775043/0ae30c22-9352-4864-a80e-81ed4ecd93e1) ## GitHubRunner vs. runs-on + You might have noticed that there are two settings in the repository settings file controlling which runners are selected, [GitHubRunner](https://aka.ms/algosettings#githubrunner) and [Runs-On](https://aka.ms/algosettings#runs-on). `"runs-on"` is used for all jobs that don’t build/test your app, such as jobs that don’t require a lot of machine power or a docker container. AL-Go for GitHub supports using ubuntu-latest for runs-on, which is faster and cheaper than windows-latest (which is the default). Many jobs run in parallel using these runners, and we do not recommend using self-hosted runners for this type of job. -`"githubRunner"` is used for build/test jobs, which require more memory and a container. +`"githubRunner"` is used for build/test jobs, which require more memory and a container. ## Additional info on build performance 1. Running 6 CI/CD workflows simultanously, causes 1 workflow to wait as I only had 5 runners. -![Wait](https://github.com/microsoft/AL-Go/assets/10775043/c18e4c23-4337-4747-ba67-177940175414) + ![Wait](https://github.com/microsoft/AL-Go/assets/10775043/c18e4c23-4337-4747-ba67-177940175414) 1. Connecting to the runner VM and looking at utilization indicates that the VM is pretty busy and probably over-allocated when starting 5+ builds at the same time. Every build was ~50% slower than when running only 1 build. -![CPU](https://github.com/microsoft/AL-Go/assets/10775043/24fc97c0-2a70-4c24-a4e7-0193bf9df4a7) + ![CPU](https://github.com/microsoft/AL-Go/assets/10775043/24fc97c0-2a70-4c24-a4e7-0193bf9df4a7) 1. Decreasing the number of runners to 4 causes the build performance to be similar to when running just 1 build. 1. Turning off real-time protection on the self-hosted runner makes builds go ~25% faster. -![Better utilization](https://github.com/microsoft/AL-Go/assets/10775043/41307197-1fa7-4586-a212-43ca73d8fd9f) + ![Better utilization](https://github.com/microsoft/AL-Go/assets/10775043/41307197-1fa7-4586-a212-43ca73d8fd9f) + +______________________________________________________________________ ---- [back](../README.md) diff --git a/Scenarios/SetupCiCdForExistingAppSourceApp.md b/Scenarios/SetupCiCdForExistingAppSourceApp.md index b857fa1fb..a9317260d 100644 --- a/Scenarios/SetupCiCdForExistingAppSourceApp.md +++ b/Scenarios/SetupCiCdForExistingAppSourceApp.md @@ -1,27 +1,33 @@ # #11 Set up CI/CD for an existing AppSource App + *Prerequisites: A GitHub account and experience from the other scenarios* + 1. Navigate to [https://github.com/microsoft/AL-Go-AppSource](https://github.com/microsoft/AL-Go-AppSource) and choose **Use this template**. -![Use this template](https://github.com/microsoft/AL-Go/assets/10775043/b884e577-1f72-4ad6-9cac-8ab41f364c1b) + ![Use this template](https://github.com/microsoft/AL-Go/assets/10775043/b884e577-1f72-4ad6-9cac-8ab41f364c1b) 1. Enter **app3** as repository name and select **Create Repository from template**. 1. My current AppSource App is using **Azure DevOps**, I download the **entire source** as a **.zip** file and place it on **Dropbox** or **Azure Blob storage** and create a **secure download Url** to the .zip file. -![Create Zip Url](https://github.com/microsoft/AL-Go/assets/10775043/fa287e2e-d2e9-4e62-a5e8-641a8e2d4ab3) + ![Create Zip Url](https://github.com/microsoft/AL-Go/assets/10775043/fa287e2e-d2e9-4e62-a5e8-641a8e2d4ab3) 1. Back on github.com, under **Actions**, select the **Add existing app or test app** workflow and choose **Run workflow**. Paste in the **Secure Download URL** and choose **Run Workflow**. When the workflow finishes, complete the pull request created. -1. A CI workflow is kicked off by the pull request, this will fail with this error: *For AppSource Apps with AppSourceCop enabled, you need to specify AppSourceCopMandatoryAffixes in .AL-Go\settings.json.* +1. A CI workflow is kicked off by the pull request, this will fail with this error: *For AppSource Apps with AppSourceCop enabled, you need to specify AppSourceCopMandatoryAffixes in .AL-Go\\settings.json.* 1. Note that if you are building your AppSource app for Business Central versions prior to 22, you also need to create a secret called LicenseFileUrl, with permissions to your objects. for version 22 and later, the CRONUS license has sufficient rights to be used as a DevOps license. -1. I will use my **KeyVault from [Scenario 7](UseAzureKeyVault.md)**, by adding a secret called **AZURE_CREDENTIALS** to my GitHub repo. And then add or modify the following 3 properties in the **.AL-Go\settings.json** file: +1. I will use my **KeyVault from [Scenario 7](UseAzureKeyVault.md)**, by adding a secret called **AZURE_CREDENTIALS** to my GitHub repo. And then add or modify the following 3 properties in the **.AL-Go\\settings.json** file: + ```json "LicenseFileUrlSecretName": "LicenseFile", "AppSourceCopMandatoryAffixes": [ "BingMaps" ], ``` -1. Meaning that the **AppSourceCopMandatoryAffixes** is set to check that I use **BingMaps** as an affix for my objects. The second setting **is only needed** if my secret is called something else than expected. AL-Go is by default looking for a secret called **LicenseFileUrl**, but you might have multiple repositories sharing the same KeyVault but needing different secrets. In this case you create a setting called **"\SecretName"**, specifying the actual secret name in the KeyVault. This mechanism is used for all secrets. In my **BuildVariables KeyVault**, the **LicenseFileUrl** secret is called **LicenseFile**. After these changes, my CI pipeline completes: -![Pipeline](https://github.com/microsoft/AL-Go/assets/10775043/679c0627-4e94-4e60-9248-c22ae8c77c1e) + +1. Meaning that the **AppSourceCopMandatoryAffixes** is set to check that I use **BingMaps** as an affix for my objects. The second setting **is only needed** if my secret is called something else than expected. AL-Go is by default looking for a secret called **LicenseFileUrl**, but you might have multiple repositories sharing the same KeyVault but needing different secrets. In this case you create a setting called **"\SecretName"**, specifying the actual secret name in the KeyVault. This mechanism is used for all secrets. In my **BuildVariables KeyVault**, the **LicenseFileUrl** secret is called **LicenseFile**. After these changes, my CI pipeline completes: + ![Pipeline](https://github.com/microsoft/AL-Go/assets/10775043/679c0627-4e94-4e60-9248-c22ae8c77c1e) 1. AppSource apps need to be code-signed. To achieve this, you must create two secrets in the GitHub repo or in your KeyVault. **CodeSignCertificateUrl** should be a secure download URL to your `.pfx` file and **CodeSignCertificatePassword** should be the password for this .pfx file. Adding these secrets will cause the **CI** workflow and the **Create Release** workflow to sign the .app files. In the pipeline, you will see a new step. -![Signing App](https://github.com/microsoft/AL-Go/assets/10775043/7e494df6-a7fb-42aa-9dc8-26c728e15270) -If your secrets are called something else than **CodesignCertificateUrl** and **CodesignCertificatePassword**, you can add an indirection to the **.AL-Go\settings.json** file: + ![Signing App](https://github.com/microsoft/AL-Go/assets/10775043/7e494df6-a7fb-42aa-9dc8-26c728e15270) + If your secrets are called something else than **CodesignCertificateUrl** and **CodesignCertificatePassword**, you can add an indirection to the **.AL-Go\\settings.json** file: + ```json "CodeSignCertificateUrlSecretName": "myCodeSignCertUrl", "CodeSignCertificatePasswordSecretName": "myCodeSignCertPassword", ``` ---- +______________________________________________________________________ + [back](../README.md) diff --git a/Scenarios/SetupCiCdForExistingPTE.md b/Scenarios/SetupCiCdForExistingPTE.md index faafe07d7..7727c694c 100644 --- a/Scenarios/SetupCiCdForExistingPTE.md +++ b/Scenarios/SetupCiCdForExistingPTE.md @@ -1,19 +1,21 @@ # #10 Set up CI/CD for an existing per-tenant extension (BingMaps) -*Prerequisites: A GitHub account. + +\*Prerequisites: A GitHub account. We will use the BingMaps sample app, which can be found on GitHub in the [Business Central BingMaps.PTE repo](https://github.com/microsoft/bcsamples-bingmaps.pte). Copy the URL to the Apps artifact of the latest release to the clipboard (currently [https://github.com/microsoft/bcsamples-bingmaps.pte/releases/download/24.0.0/bcsamples-bingmaps.pte-main-Apps-24.0.169.0.zip](https://github.com/microsoft/bcsamples-bingmaps.pte/releases/download/24.0.0/bcsamples-bingmaps.pte-main-Apps-24.0.169.0.zip) – you can also download the .zip file and see the content of it. 1. Navigate to [https://github.com/microsoft/AL-Go-PTE](https://github.com/microsoft/AL-Go-PTE) and then choose **Use this template**. -![Use this template](https://github.com/microsoft/AL-Go/assets/10775043/b4e32467-723d-434e-8c0a-45c6254699b4) + ![Use this template](https://github.com/microsoft/AL-Go/assets/10775043/b4e32467-723d-434e-8c0a-45c6254699b4) 1. Enter **app2** as repository name and select **Create Repository from template**. 1. Under **Actions** select the **Add existing app or test app** workflow and choose **Run workflow**. 1. In the **Direct Download URL** field, paste in the direct download URL of the BingMaps sample from above. 1. When the workflow is complete, inspect the **Pull request**. -![Pull Request](https://github.com/microsoft/AL-Go/assets/10775043/a02cdef9-b3f7-486a-be32-a19a3f56525d) + ![Pull Request](https://github.com/microsoft/AL-Go/assets/10775043/a02cdef9-b3f7-486a-be32-a19a3f56525d) 1. Merge the pull request. The **CI/CD** workflow will kick off. -![CI/CD](https://github.com/microsoft/AL-Go/assets/10775043/58ab0a72-4b81-4a52-814f-a0984d7154de) + ![CI/CD](https://github.com/microsoft/AL-Go/assets/10775043/58ab0a72-4b81-4a52-814f-a0984d7154de) 1. After the workflow completes, you can investigate the output and see that everything works. -![Success](https://github.com/microsoft/AL-Go/assets/10775043/d7806af4-822d-43ea-8103-dd7c69e8fd64) + ![Success](https://github.com/microsoft/AL-Go/assets/10775043/d7806af4-822d-43ea-8103-dd7c69e8fd64) 1. Use [scenario 3](RegisterSandboxEnvironment.md), [scenario 4](CreateRelease.md), and [scenario 5](RegisterProductionEnvironment.md) to set up customer environments, publish and test the app. ---- +______________________________________________________________________ + [back](../README.md) diff --git a/Scenarios/SetupPowerPlatform.md b/Scenarios/SetupPowerPlatform.md index 401b66e22..073e1dc27 100644 --- a/Scenarios/SetupPowerPlatform.md +++ b/Scenarios/SetupPowerPlatform.md @@ -3,15 +3,16 @@ There are 2 steps to connect your GitHub repository to your Power Platform tenant and environments: 1. Setup the authentication context -2. Setup the AL-Go Repository settings (.github/AL-Go-Settings.json) +1. Setup the AL-Go Repository settings (.github/AL-Go-Settings.json) ## Authentication Context + The authentication context is a JSON object that you save in your GitHub secrets with the following naming convention: `_AUTHCONTEXT` The authentication context specifies how the GitHub Environment you have created authenticates against your Power Platform and Business Central environments. You can use UserName/Password to create the authentication context or create a service principal account and use a client secret to connect (see a [Setting up service principal](./SetupServicePrincipalForPowerPlatform.md) for detailed steps). > **NOTE:** Username/password authentication is only supported for tenants that do NOT have 2-factor authentication enabled. -The recommended way to get the auth context is to use the BCContainerHelper to generate the JSON - open a PowerShell window and run the following commands: +> The recommended way to get the auth context is to use the BCContainerHelper to generate the JSON - open a PowerShell window and run the following commands: ### Getting service principal authentication context @@ -59,5 +60,6 @@ The settings are located at: `.github/AL-Go-Settings.json` > **NOTE:** GitHubEnvironmentName is the name of the environment you are creating in GitHub to represent the Business Central and Power Platform environments you are deploying to. The GitHub environment must have a corresponding authentication context. ---- +______________________________________________________________________ + [back](../README.md) diff --git a/Scenarios/SetupServicePrincipalForPowerPlatform.md b/Scenarios/SetupServicePrincipalForPowerPlatform.md index d8f5f3d52..57a122969 100644 --- a/Scenarios/SetupServicePrincipalForPowerPlatform.md +++ b/Scenarios/SetupServicePrincipalForPowerPlatform.md @@ -8,14 +8,13 @@ Setting up a service principal can be done in 2 steps: setting up the principal You can do this step using the Azure portal or PowerShell. For more information, see one the following articles: - - [Create an Azure AD application and service principal \(using Azure portal\)](https://learn.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal) + - [Create an Azure AD application and service principal (using Azure portal)](https://learn.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal) - [Create service principal and client secret using PowerShell](https://learn.microsoft.com/en-us/power-platform/alm/devops-build-tools#create-service-principal-and-client-secret-using-powershell)
2. In Power Platform, add the service principal as an app user on the environment. - Using Power Platform admin center, add the service principal as an application user of the environment and assign it either the **System admin** or **Super** role. **System admin** is recommended. + Using Power Platform admin center, add the service principal as an application user of the environment and assign it either the **System admin** or **Super** role. **System admin** is recommended. For more information, see [Manage app users in Power Platform](https://learn.microsoft.com/en-us/power-platform/admin/manage-application-users). - \ No newline at end of file diff --git a/Scenarios/TryPowerPlatformSamples.md b/Scenarios/TryPowerPlatformSamples.md index 2382ae4cb..215170b06 100644 --- a/Scenarios/TryPowerPlatformSamples.md +++ b/Scenarios/TryPowerPlatformSamples.md @@ -3,46 +3,49 @@ The easiest way to get started with Business Central and Power Apps is to find one of our sample apps: - [Take Order](https://github.com/microsoft/bcsamples-takeorder) -- [Warehouse helper](https://github.com/microsoft/bcsamples-warehousehelper) +- [Warehouse helper](https://github.com/microsoft/bcsamples-warehousehelper) > **NOTE:** Other samples might be available here: [https://github.com/topics/bcsamples](https://github.com/topics/bcsamples). -From the sample app repositories, you have two options: +> From the sample app repositories, you have two options: -- [Manual installation](#manual-installation) +- [Manual installation](#manual-installation) - [Fork the repository](#fork-the-repository) - ## Manual Installation + If you just want to try the apps and not the ALM functionality, follow these steps: 1. In the App repository, find the latest release and download the Power platform solution and the Business Central extension zip files. *Note:* You need to unzip the files to access the actual extension and solution file. -![Screen shot from showing where the release artifacts are located](https://github.com/microsoft/AL-Go/assets/10775043/1c8bea93-5ec3-410b-b1b8-a94e7c5e533e) + ![Screen shot from showing where the release artifacts are located](https://github.com/microsoft/AL-Go/assets/10775043/1c8bea93-5ec3-410b-b1b8-a94e7c5e533e) + +1. Upload the Business Central extension to your Business Central environment. -2. Upload the Business Central extension to your Business Central environment. +1. (Optional) Open the sample page to generate demo data. -3. (Optional) Open the sample page to generate demo data. +1. Import the Power Platform solution to your Power Platform environment. You will be asked to add a Business Central connection if your environment does not have one. Follow the steps in the wizard to add it. -4. Import the Power Platform solution to your Power Platform environment. You will be asked to add a Business Central connection if your environment does not have one. Follow the steps in the wizard to add it. - > **Note:** You might receive a warning about the imported flow. This is expected and will be addressed in a subsequent step. -5. Update the flow so it is pointing to your Business Central environment and company. Clear the current values and use the dropdown to select your settings. -![Screen shot from Power Automate showing where to update the Business Central connection reference](https://github.com/microsoft/AL-Go/assets/10775043/025787fa-38eb-4290-ad6a-4c607d2fa2d1) + > **Note:** You might receive a warning about the imported flow. This is expected and will be addressed in a subsequent step. -6. Update the Power App data sources to point to your Business Central environment. When you hover over the data source, the connection information is displayed under the 'Dataset name'. +1. Update the flow so it is pointing to your Business Central environment and company. Clear the current values and use the dropdown to select your settings. + ![Screen shot from Power Automate showing where to update the Business Central connection reference](https://github.com/microsoft/AL-Go/assets/10775043/025787fa-38eb-4290-ad6a-4c607d2fa2d1) - Delete the existing connections. Then, add new ones that point to your environment and company. You can do this by using the '+ Add data' button. - ![Screen shot from Power Apps showing where to update the Business Central connection reference](https://github.com/microsoft/AL-Go/assets/10775043/3b9d1ed6-4257-4234-8f0f-8b87df398b4f) +1. Update the Power App data sources to point to your Business Central environment. When you hover over the data source, the connection information is displayed under the 'Dataset name'. - > **Note:** After the data sources have been updated and you verified that the app is working, use the 'Publish' action in the upper right corner to make the changes available when running the app outside the editor. -If you experience any issues while setting up the app, please log them in the 'Issues' tab of the sample repository - [Take order issues](https://github.com/microsoft/bcsamples-takeorder/issues), [Warehouse Helper issues](https://github.com/microsoft/bcsamples-warehousehelper/issues) - or post the issue in the [Business Central partner community](https://www.yammer.com/dynamicsnavdev/#/threads/inGroup?type=in_group&feedId=64329121792) for assistance. + Delete the existing connections. Then, add new ones that point to your environment and company. You can do this by using the '+ Add data' button. + ![Screen shot from Power Apps showing where to update the Business Central connection reference](https://github.com/microsoft/AL-Go/assets/10775043/3b9d1ed6-4257-4234-8f0f-8b87df398b4f) + + > **Note:** After the data sources have been updated and you verified that the app is working, use the 'Publish' action in the upper right corner to make the changes available when running the app outside the editor. + > If you experience any issues while setting up the app, please log them in the 'Issues' tab of the sample repository - [Take order issues](https://github.com/microsoft/bcsamples-takeorder/issues), [Warehouse Helper issues](https://github.com/microsoft/bcsamples-warehousehelper/issues) - or post the issue in the [Business Central partner community](https://www.yammer.com/dynamicsnavdev/#/threads/inGroup?type=in_group&feedId=64329121792) for assistance. ## Fork the Repository This gives you access to all the source code for the Power Platform solution and AL extension and the ALM infrastructure. Follow the steps in the [Power Platform repository setup guide](./SetupPowerPlatform.md) to get started. Once set up, you can easily publish the latest changes to your environment. > **NOTE:** The first time you import the solution into your environment, you need to set up the Business Central connection reference authentication. See an example in the screen shot below -![Screen shot from Power Apps showing how to set up a the Business Central connection reference](https://github.com/microsoft/AL-Go/assets/10775043/dd90b6ae-f54f-4851-8073-c32d7fa54c7a) +> ![Screen shot from Power Apps showing how to set up a the Business Central connection reference](https://github.com/microsoft/AL-Go/assets/10775043/dd90b6ae-f54f-4851-8073-c32d7fa54c7a) Choose the method that suits you best and get started with exploring the capabilities of Business Central and Power Platform! ---- +______________________________________________________________________ + [back](../README.md) diff --git a/Scenarios/UpdateAlGoSystemFiles.md b/Scenarios/UpdateAlGoSystemFiles.md index f46c1eca3..23a3ac5b7 100644 --- a/Scenarios/UpdateAlGoSystemFiles.md +++ b/Scenarios/UpdateAlGoSystemFiles.md @@ -1,45 +1,47 @@ # #6 Update AL-Go system files + *Prerequisites: A completed [scenario 5](RegisterProductionEnvironment.md)* 1. Every time a CI/CD pipeline runs, it checks whether there are updates to AL-Go system files. AL-Go System files are scripts in the **.AL-Go folder** and workflows in the **.github folder**. Looking into the details of the Check for updates to Al-Go system files, usually looks like this ![CI/CD](https://github.com/microsoft/AL-Go/assets/10775043/8322a06e-a270-4b6d-8d92-ccc547ca4555) -2. In VS Code, try to modify the **LocalDevEnv.ps1** file, **stage** the change, **commit** and **push**. +1. In VS Code, try to modify the **LocalDevEnv.ps1** file, **stage** the change, **commit** and **push**. ![localdevenv](https://github.com/microsoft/AL-Go/assets/10775043/9eb67bc0-5460-44c5-8ede-fc8f6545a821) -3. Now there is a difference. AL-Go doesn’t support that anybody changes the AL-Go system files and will warn about these changes. The CI/CD pipeline, which kicked off when pushing the change, tells me about this. +1. Now there is a difference. AL-Go doesn’t support that anybody changes the AL-Go system files and will warn about these changes. The CI/CD pipeline, which kicked off when pushing the change, tells me about this. ![summary](https://github.com/microsoft/AL-Go/assets/10775043/8b87cf1e-5f39-487d-9b39-4ebf9a39706a) -4. To update the AL-Go system files using the Update AL-Go System Files workflow, you need to provide a secret called GHTOKENWORKFLOW containing a Personal Access Token with permissions to modify workflows. Personal access tokens are either fine-grained personal access tokens or classic personal access tokens. AL-Go for GitHub works with both if you have enabled these tokens in organization settings: +1. To update the AL-Go system files using the Update AL-Go System Files workflow, you need to provide a secret called GHTOKENWORKFLOW containing a Personal Access Token with permissions to modify workflows. Personal access tokens are either fine-grained personal access tokens or classic personal access tokens. AL-Go for GitHub works with both if you have enabled these tokens in organization settings: ![orgimage](https://github.com/microsoft/AL-Go/assets/10775043/f3a26b6c-ddf6-4ab6-9e7e-2a4ac04a0828) -5. To create a **classic** personal access token, navigate to [New personal access token](https://github.com/settings/tokens/new) in a browser. Name it, set the expiration date and check the **workflow option** in the list of **scopes**. The classic tokens have access to all repositories, which you as a user have access to. +1. To create a **classic** personal access token, navigate to [New personal access token](https://github.com/settings/tokens/new) in a browser. Name it, set the expiration date and check the **workflow option** in the list of **scopes**. The classic tokens have access to all repositories, which you as a user have access to. ![newPAT](https://github.com/microsoft/AL-Go/assets/10775043/1ab9978a-37e8-423a-8f8e-5c0203f7ae00) -6. To create a **fine-grained** personal access token, navigate to [New fine-grained personal access token](https://github.com/settings/personal-access-tokens/new) in a browser. Name it, set the expiration date and specify which repositories to include. You need to and assign **Read and Write** permissions to **Contents**, **Pull Requests** and **Workflows**. You also need to assign **Read-only** permissions to **Actions**. +1. To create a **fine-grained** personal access token, navigate to [New fine-grained personal access token](https://github.com/settings/personal-access-tokens/new) in a browser. Name it, set the expiration date and specify which repositories to include. You need to and assign **Read and Write** permissions to **Contents**, **Pull Requests** and **Workflows**. You also need to assign **Read-only** permissions to **Actions**. ![newFineGrained](https://github.com/microsoft/AL-Go/assets/10775043/c4618a82-3f56-4423-9ab5-15b53b4b2e95) -7. Generate the token and **copy it to the clipboard**. You won’t be able to see the token again. +1. Generate the token and **copy it to the clipboard**. You won’t be able to see the token again. -8. On github.com, open **Settings** in your project and select **Secrets**. Choose the New repository secret button and create a secret called GHTOKENWORKFLOW and paste the personal access token in the value field and choose **Add secret**. +1. On github.com, open **Settings** in your project and select **Secrets**. Choose the New repository secret button and create a secret called GHTOKENWORKFLOW and paste the personal access token in the value field and choose **Add secret**. ![PAT](https://github.com/microsoft/AL-Go/assets/10775043/7dcccca3-ec43-47ba-bffb-795332c890ad) -9. On github.com, under **Actions** in your project, select the **Update AL-Go system files** workflow and choose **Run workflow**. Leave the **Template Repository URL** blank and choose **Run workflow**. +1. On github.com, under **Actions** in your project, select the **Update AL-Go system files** workflow and choose **Run workflow**. Leave the **Template Repository URL** blank and choose **Run workflow**. ![update](https://github.com/microsoft/AL-Go/assets/10775043/221e6aa1-27a8-47ea-b011-88bb6b7005b9) -10. Inspect the pull request and see that it indeed reverts your change to the `LocalDevEnv.ps1` file. +1. Inspect the pull request and see that it indeed reverts your change to the `LocalDevEnv.ps1` file. + +![update](https://github.com/microsoft/AL-Go/assets/10775043/c5811750-eeb2-4ce5-a8a6-9d7db620c81e) - ![update](https://github.com/microsoft/AL-Go/assets/10775043/c5811750-eeb2-4ce5-a8a6-9d7db620c81e) +11. By default, this workflow will apply any updates to the **workflow files (in .github\\workflows)** or **system scripts (in .AL-Go)** from the template repository used to spin up the repository. If you want to change branch or template Url, you can specify the `templateUrl@branch` when you run the workflow. -11. By default, this workflow will apply any updates to the **workflow files (in .github\workflows)** or **system scripts (in .AL-Go)** from the template repository used to spin up the repository. If you want to change branch or template Url, you can specify the `templateUrl@branch` when you run the workflow. +______________________________________________________________________ ---- [back](../README.md) diff --git a/Scenarios/UseAzureKeyVault.md b/Scenarios/UseAzureKeyVault.md index 14d0746db..f7746f4bf 100644 --- a/Scenarios/UseAzureKeyVault.md +++ b/Scenarios/UseAzureKeyVault.md @@ -1,4 +1,5 @@ # #7 Use Azure KeyVault for secrets with AL-Go + *Prerequisites: A completed [scenario 6](UpdateAlGoSystemFiles.md), an Azure KeyVault and you will need to follow the guidelines on how to connect to an Azure KeyVault as specified [here](https://learn.microsoft.com/azure/developer/github/connect-from-azure?tabs=azure-portal%2Cwindows#use-the-azure-login-action-with-a-service-principal-secret). Add your KeyVault name to the the JSON construct from this walkthrough (using **“keyVaultName” : “{your keyvault name}”**) and add this JSON construct as a repository secret called AZURE_CREDENTIALS. You can also specify the KeyVault name in the AL-Go settings file if you do not wait to mess with the JSON construct.* *If you need to use Hardware Security Modules, you'll need to use a Premium SKU key vault. For more information on this, see [learn.microsoft.com](https://learn.microsoft.com/en-us/azure/key-vault/keys/about-keys)* @@ -7,8 +8,9 @@ 1. Add the **authContext** secret (see scenario 3) and the **ghTokenWorkflow** secret (see scenario 6) as secrets in your KeyVault. Remove the secrets from repository secrets and environment secrets. 1. Run the CI/CD pipeline to see that the deployment still works, reading the **authContext** secret from the KeyVault. -![runpipeline](https://github.com/microsoft/AL-Go/assets/10775043/0dd31eb9-e135-46e3-a526-d47873f08b63) + ![runpipeline](https://github.com/microsoft/AL-Go/assets/10775043/0dd31eb9-e135-46e3-a526-d47873f08b63) 1. Redo scenario 6 to see that Update AL-Go System files still works. ---- +______________________________________________________________________ + [back](../README.md) diff --git a/Scenarios/settings.md b/Scenarios/settings.md index 0b670806f..536875e9c 100644 --- a/Scenarios/settings.md +++ b/Scenarios/settings.md @@ -1,4 +1,5 @@ # Settings + The behavior of AL-Go for GitHub is very much controlled by settings. ## Where are the settings located @@ -7,43 +8,45 @@ Settings can be defined in GitHub variables or in various settings file. An AL-G When running a workflow or a local script, the settings are applied by reading settings from GitHub variables and one or more settings files. Last applied settings file wins. The following lists the order of locations to search for settings: -1. `ALGoOrgSettings` is a **GitHub variable**, which can be defined on an **organizational level** and will apply to **all AL-Go repositories** in this organization. +1. `ALGoOrgSettings` is a **GitHub variable**, which can be defined on an **organizational level** and will apply to **all AL-Go repositories** in this organization. -1. `.github/AL-Go-settings.json` is the **repository settings file**. This settings file contains settings that are relevant for all projects in the repository. **Special note:** The repository settings file can also contains `BcContainerHelper` settings, which will be applied when loading `BcContainerHelper` in a workflow - the GitHub variables are not considered for BcContainerHelper settings. (see expert section). +1. `.github/AL-Go-settings.json` is the **repository settings file**. This settings file contains settings that are relevant for all projects in the repository. **Special note:** The repository settings file can also contains `BcContainerHelper` settings, which will be applied when loading `BcContainerHelper` in a workflow - the GitHub variables are not considered for BcContainerHelper settings. (see expert section). -1. `ALGoRepoSettings` is a **GitHub variable**, which can be defined on an **repository level** and can contain settings that are relevant for **all projects** in the repository. +1. `ALGoRepoSettings` is a **GitHub variable**, which can be defined on an **repository level** and can contain settings that are relevant for **all projects** in the repository. -1. `.AL-Go/settings.json` is the **project settings file**. If the repository is a single project, the .AL-Go folder is in the root folder of the repository. If the repository contains multiple projects, there will be a .AL-Go folder in each project folder (like `project/.AL-Go/settings.json`) +1. `.AL-Go/settings.json` is the **project settings file**. If the repository is a single project, the .AL-Go folder is in the root folder of the repository. If the repository contains multiple projects, there will be a .AL-Go folder in each project folder (like `project/.AL-Go/settings.json`) -1. `.github/.settings.json` is the **workflow-specific settings file** for **all projects**. This option is used for the Current, NextMinor and NextMajor workflows to determine artifacts and build numbers when running these workflows. +1. `.github/.settings.json` is the **workflow-specific settings file** for **all projects**. This option is used for the Current, NextMinor and NextMajor workflows to determine artifacts and build numbers when running these workflows. -1. `.AL-Go/.settings.json` is the **workflow-specific settings file** for a **specific project**. +1. `.AL-Go/.settings.json` is the **workflow-specific settings file** for a **specific project**. -1. `.AL-Go/.settings.json` is the **user-specific settings file**. This option is rarely used, but if you have special settings, which should only be used for one specific user (potentially in the local scripts), these settings can be added to a settings file with the name of the user followed by `.settings.json`. +1. `.AL-Go/.settings.json` is the **user-specific settings file**. This option is rarely used, but if you have special settings, which should only be used for one specific user (potentially in the local scripts), these settings can be added to a settings file with the name of the user followed by `.settings.json`. ## Basic Project settings | Name | Description | Default value | | :-- | :-- | :-- | | country | Specifies which country this app is built against. | us | -| repoVersion | RepoVersion is the project version number. The Repo Version number consists of \.\ only and is used for naming build artifacts in the CI/CD workflow. Build artifacts are named **\-Apps-\.\.\** and can contain multiple apps. The Repo Version number is used as major.minor for individual apps if versioningStrategy is +16. | 1.0 | +| repoVersion | RepoVersion is the project version number. The Repo Version number consists of \.\ only and is used for naming build artifacts in the CI/CD workflow. Build artifacts are named **\-Apps-\.\.\** and can contain multiple apps. The Repo Version number is used as major.minor for individual apps if versioningStrategy is +16. | 1.0 | | projectName | Friendly name for an AL-Go project to be used in the UI for various workflows (CICD, Pull Request Build, etc.). If not set, the name for the project will be the relative path from the root of the repository. | '' | -| appFolders | appFolders should be an array of folders (relative to project root), which contains apps for this project. Apps in these folders are sorted based on dependencies and built and published in that order.
If appFolders are not specified, AL-Go for GitHub will try to locate appFolders in the root of the project. | [ ] | -| testFolders | testFolders should be an array of folders (relative to project root), which contains test apps for this project. Apps in these folders are sorted based on dependencies and built, published and tests are run in that order.
If testFolders are not specified, AL-Go for GitHub will try to locate testFolders in the root of the project. | [ ] | -| bcptTestFolders | bcptTestFolders should be an array of folders (relative to project root), which contains performance test apps for this project. Apps in these folders are sorted based on dependencies and built, published and bcpt tests are run in that order.
If bcptTestFolders are not specified, AL-Go for GitHub will try to locate bcptTestFolders in the root of the project. | [ ] | -| appDependencyProbingPaths | Array of dependency specifications, from which apps will be downloaded when the CI/CD workflow is starting. Every dependency specification consists of the following properties:
**repo** = repository
**version** = version (default latest)
**release_status** = latestBuild/release/prerelease/draft (default release)
**projects** = projects (default * = all)
**branch** = branch (default main)
**AuthTokenSecret** = Name of secret containing auth token (default none)
| [ ] | -| cleanModePreprocessorSymbols | List of clean tags to be used in _Clean_ build mode | [ ] | +| appFolders | appFolders should be an array of folders (relative to project root), which contains apps for this project. Apps in these folders are sorted based on dependencies and built and published in that order.
If appFolders are not specified, AL-Go for GitHub will try to locate appFolders in the root of the project. | \[ \] | +| testFolders | testFolders should be an array of folders (relative to project root), which contains test apps for this project. Apps in these folders are sorted based on dependencies and built, published and tests are run in that order.
If testFolders are not specified, AL-Go for GitHub will try to locate testFolders in the root of the project. | \[ \] | +| bcptTestFolders | bcptTestFolders should be an array of folders (relative to project root), which contains performance test apps for this project. Apps in these folders are sorted based on dependencies and built, published and bcpt tests are run in that order.
If bcptTestFolders are not specified, AL-Go for GitHub will try to locate bcptTestFolders in the root of the project. | \[ \] | +| appDependencyProbingPaths | Array of dependency specifications, from which apps will be downloaded when the CI/CD workflow is starting. Every dependency specification consists of the following properties:
**repo** = repository
**version** = version (default latest)
**release_status** = latestBuild/release/prerelease/draft (default release)
**projects** = projects (default * = all)
**branch** = branch (default main)
**AuthTokenSecret** = Name of secret containing auth token (default none)
| \[ \] | +| cleanModePreprocessorSymbols | List of clean tags to be used in _Clean_ build mode | \[ \] | | bcptThresholds | Structure with properties for the thresholds when running performance tests using the Business Central Performance Toolkit.
**DurationWarning** = a warning is shown if the duration of a bcpt test degrades more than this percentage (default 10)
**DurationError** - an error is shown if the duration of a bcpt test degrades more than this percentage (default 25)
**NumberOfSqlStmtsWarning** - a warning is shown if the number of SQL statements from a bcpt test increases more than this percentage (default 5)
**NumberOfSqlStmtsError** - an error is shown if the number of SQL statements from a bcpt test increases more than this percentage (default 10)
*Note that errors and warnings on the build in GitHub are only issued when a threshold is exceeded on the codeunit level, when an individual operation threshold is exceeded, it is only shown in the test results viewer.* | ## AppSource specific basic project settings + | Name | Description | Default value | | :-- | :-- | :-- | -| appSourceCopMandatoryAffixes | This setting is only used if the type is AppSource App. The value is an array of affixes, which is used for running AppSource Cop. | [ ] | +| appSourceCopMandatoryAffixes | This setting is only used if the type is AppSource App. The value is an array of affixes, which is used for running AppSource Cop. | \[ \] | | deliverToAppSource | Structure with properties for AppSource delivery from AL-Go for GitHub. The structure can contain the following properties:
**productId** must be the product Id from partner Center.
**mainAppFolder** specifies the appFolder of the main app if you have multiple apps in the same project.
**continuousDelivery** can be set to true to enable continuous delivery of every successful build to AppSource Validation. Note that the app will only be in preview in AppSource and you will need to manually press GO LIVE in order for the app to be promoted to production.
**includeDependencies** can be set to an array of file names (incl. wildcards) which are the names of the dependencies to include in the AppSource submission. You need to set `generateDependencyArtifact` in the [project settings file](#where-are-the-settings-located) to true in order to include dependencies.
**Note:** You will need to define an AppSourceContext secret in order to publish to AppSource. | | | obsoleteTagMinAllowedMajorMinor | This setting will enable AppSource cop rule AS0105, which causes objects that are pending obsoletion with an obsolete tag version lower than the minimum set in this property are not allowed. | | ## Basic Repository settings -The repository settings are only read from the repository settings file (.github\AL-Go-Settings.json) + +The repository settings are only read from the repository settings file (.github\\AL-Go-Settings.json) | Name | Description | | :-- | :-- | @@ -61,13 +64,13 @@ The repository settings are only read from the repository settings file (.github | shell | Specifies which shell will be used as the default in all jobs. **powershell** is the default, which results in using _PowerShell 5.1_ (unless you selected _ubuntu-latest_, then **pwsh** is used, which results in using _PowerShell 7_) | | githubRunner | Specifies which github runner will be used for the build/test jobs in workflows including a build job. This is the most time consuming task. By default this job uses the _Windows-latest_ github runner (unless overridden by the runs-on setting). This settings takes precedence over runs-on so that you can use different runners for the build job and the housekeeping jobs. See **runs-on** setting. | | githubRunnerShell | Specifies which shell is used for build jobs in workflows including a build job. The default is to use the same as defined in **shell**. If the shell setting isn't defined, **powershell** is the default, which results in using _PowerShell 5.1_. Use **pwsh** for _PowerShell 7_. | -| environments | Array of logical environment names. You can specify environments in GitHub environments or in the repo settings file. If you specify environments in the settings file, you can create your AUTHCONTEXT secret using **<environmentname>_AUTHCONTEXT**. You can specify additional information about environments in a setting called **DeployTo<environmentname>** | -| DeliverTo<deliveryTarget> | Structure with additional properties for the deliveryTarget specified. Some properties are deliveryTarget specific. The structure can contain the following properties:
**Branches** = an array of branch patterns, which are allowed to deliver to this deliveryTarget. (Default main)
**CreateContainerIfNotExist** = *[Only for DeliverToStorage]* Create Blob Storage Container if it doesn't already exist. (Default false)
| -| DeployTo<environmentname> | Structure with additional properties for the environment specified. The structure can contain the following properties:
**EnvironmentType** = specifies the type of environment. The environment type can be used to invoke a custom deployment. (Default SaaS)
**EnvironmentName** = specifies the "real" name of the environment if it differs from the GitHub environment.
**Branches** = an array of branch patterns, which are allowed to deploy to this environment. These branches can also be defined under the environment in GitHub settings and both settings are honored. If neither setting is defined, the default is the **main** branch only.
**Projects** = In multi-project repositories, this property can be a comma separated list of project patterns to deploy to this environment. (Default *)
**SyncMode** = ForceSync if deployment to this environment should happen with ForceSync, else Add. If deploying to the development endpoint you can also specify Development or Clean. (Default Add)
**ContinuousDeployment** = true if this environment should be used for continuous deployment, else false. (Default: AL-Go will continuously deploy to sandbox environments or environments, which doesn't end in (PROD) or (FAT)
**runs-on** = specifies which runner to use when deploying to this environment. (Default is settings.runs-on)
**shell** = specifies which shell to use when deploying to this environment, pwsh or powershell. (Default is settings.shell)
**companyId** = Company Id from Business Central (for PowerPlatform connection)
**ppEnvironmentUrl** = Url of the PowerPlatform environment to deploy to
| +| environments | Array of logical environment names. You can specify environments in GitHub environments or in the repo settings file. If you specify environments in the settings file, you can create your AUTHCONTEXT secret using **\\_AUTHCONTEXT**. You can specify additional information about environments in a setting called **DeployTo\** | +| DeliverTo\ | Structure with additional properties for the deliveryTarget specified. Some properties are deliveryTarget specific. The structure can contain the following properties:
**Branches** = an array of branch patterns, which are allowed to deliver to this deliveryTarget. (Default main)
**CreateContainerIfNotExist** = *\[Only for DeliverToStorage\]* Create Blob Storage Container if it doesn't already exist. (Default false)
| +| DeployTo\ | Structure with additional properties for the environment specified. The structure can contain the following properties:
**EnvironmentType** = specifies the type of environment. The environment type can be used to invoke a custom deployment. (Default SaaS)
**EnvironmentName** = specifies the "real" name of the environment if it differs from the GitHub environment.
**Branches** = an array of branch patterns, which are allowed to deploy to this environment. These branches can also be defined under the environment in GitHub settings and both settings are honored. If neither setting is defined, the default is the **main** branch only.
**Projects** = In multi-project repositories, this property can be a comma separated list of project patterns to deploy to this environment. (Default \*)
**SyncMode** = ForceSync if deployment to this environment should happen with ForceSync, else Add. If deploying to the development endpoint you can also specify Development or Clean. (Default Add)
**ContinuousDeployment** = true if this environment should be used for continuous deployment, else false. (Default: AL-Go will continuously deploy to sandbox environments or environments, which doesn't end in (PROD) or (FAT)
**runs-on** = specifies which runner to use when deploying to this environment. (Default is settings.runs-on)
**shell** = specifies which shell to use when deploying to this environment, pwsh or powershell. (Default is settings.shell)
**companyId** = Company Id from Business Central (for PowerPlatform connection)
**ppEnvironmentUrl** = Url of the PowerPlatform environment to deploy to
| | alDoc | Structure with properties for the aldoc reference document generation. The structure can contain the following properties:
**continuousDeployment** = Determines if reference documentation will be deployed continuously as part of CI/CD. You can run the **Deploy Reference Documentation** workflow to deploy manually or on a schedule. (Default false)
**deployToGitHubPages** = Determines whether or not the reference documentation site should be deployed to GitHub Pages for the repository. In order to deploy to GitHub Pages, GitHub Pages must be enabled and set to GitHub Actuibs. (Default true)
**maxReleases** = Maximum number of releases to include in the reference documentation. (Default 3)
**groupByProject** = Determines whether projects in multi-project repositories are used as folders in reference documentation
**includeProjects** = An array of projects to include in the reference documentation. (Default all)
**excludeProjects** = An array of projects to exclude in the reference documentation. (Default none)
**header** = Header for the documentation site. (Default: Documentation for...)
**footer** = Footer for the documentation site. (Default: Made with...)
**defaultIndexMD** = Markdown for the landing page of the documentation site. (Default: Reference documentation...)
**defaultReleaseMD** = Markdown for the landing page of the release sites. (Default: Release reference documentation...)
*Note that in header, footer, defaultIndexMD and defaultReleaseMD you can use the following placeholders: {REPOSITORY}, {VERSION}, {INDEXTEMPLATERELATIVEPATH}, {RELEASENOTES}* | | useProjectDependencies | Determines whether your projects are built using a multi-stage built workflow or single stage. After setting useProjectDependencies to true, you need to run Update AL-Go System Files and your workflows including a build job will change to have multiple build jobs, depending on each other. The number of build jobs will be determined by the dependency depth in your projects.
You can change dependencies between your projects, but if the dependency **depth** changes, AL-Go will warn you that updates for your AL-Go System Files are available and you will need to run the workflow. | -| CICDPushBranches | CICDPushBranches can be specified as an array of branches, which triggers a CI/CD workflow on commit. You need to run the Update AL-Go System Files workflow for the schedule to take effect.
Default is [ "main", "release/\*", "feature/\*" ] | -| CICDPullRequestBranches | CICDPullRequestBranches can be specified as an array of branches, which triggers a CI/CD workflow on a PR. You need to run the Update AL-Go System Files workflow for the schedule to take effect.
Default is [ "main" ] | +| CICDPushBranches | CICDPushBranches can be specified as an array of branches, which triggers a CI/CD workflow on commit. You need to run the Update AL-Go System Files workflow for the schedule to take effect.
Default is \[ "main", "release/\*", "feature/\*" \] | +| CICDPullRequestBranches | CICDPullRequestBranches can be specified as an array of branches, which triggers a CI/CD workflow on a PR. You need to run the Update AL-Go System Files workflow for the schedule to take effect.
Default is \[ "main" \] | | pullRequestTrigger | Setting for specifying the trigger AL-Go should use to trigger Pull Request Builds. You need to run the Update AL-Go System Files workflow for the schedule to take effect.
Default is [pull_request_target](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request_target) | | CICDSchedule | CRON schedule for when CI/CD workflow should run. Default is no scheduled run, only manually triggered or triggered by Push or Pull Request. Build your CRON string here: [https://crontab.guru](https://crontab.guru). You need to run the Update AL-Go System Files workflow for the schedule to take effect. **Note:** If you configure a CICDSchedule, AL-Go will stop triggering CICDs on push unless you have also added CICDPushBranches to your settings. | | UpdateGitHubGoSystemFilesSchedule | CRON schedule for when Update AL-Go System Files should run. When Update AL-Go System Files runs on a schedule, it uses direct Commit instead of creating a PR. Default is no scheduled run, only manual trigger. Build your CRON string here: [https://crontab.guru](https://crontab.guru). You need to run the Update AL-Go System Files workflow for the schedule to take effect. | @@ -77,24 +80,24 @@ The repository settings are only read from the repository settings file (.github | Name | Description | Default value | | :-- | :-- | :-- | -| artifact | Determines the artifacts used for building and testing the app.
This setting can either be an absolute pointer to Business Central artifacts (https://... - rarely used) or it can be a search specification for artifacts (\/\/\/\/\).
If not specified, the artifacts used will be the latest sandbox artifacts from the country specified in the country setting.
**Note:** if version is set to `*`, then the application dependency from the apps in your project will determine which artifacts to use. If select is *first*, then you will get the first artifacts matching your application dependency. If select is *latest* then you will get the latest artifacts with the same major.minor as your application dependency. | | +| artifact | Determines the artifacts used for building and testing the app.
This setting can either be an absolute pointer to Business Central artifacts (https://... - rarely used) or it can be a search specification for artifacts (\/\/\/\/\