The Challenge

At this time, AL-Go for GitHub doesn’t work on GHE.COM enterprises, but there might be a solution for this ahead. I was contacted by Fellowmind in Sweden, who wanted to have this functionality and I guess there is likely nobody better qualified (outside Microsoft) to build this, than me, so… I accepted the challenge and I am working with Niklas Silvergrund from Fellowmind to test the solution.

If you want to try this out yourself, there is a version of AL-Go in my Freddy-DK organization, which supports GHE.COM. Documentation on how to get started is here: https://github.com/Freddy-DK/AL-Go/blob/main/Scenarios/UsingGitHubEnterprise.md

I will keep this repo up-to-date with Microsofts AL-Go for GitHub and work with Microsoft to get support for GHE.COM into the main product, but I can obviously not promise any date.

Try it out, and report any problems by creating an issue in my fork, and I will make sure to fix them, before the functionality is merged.

Main differences between github.com and GHE.COM

Isolation & access: On GHE.com, managed user accounts can only access resources within your enterprise’s dedicated instance – no interacting with the broader github.com ecosystem (no personal accounts, no public open-source repos mixed in). GitHub.com is fully open and interconnected.

Data residency: GHE.com lets you choose the geographic region where your code and data are stored, which is the main compliance driver for adopting it. GitHub.com doesn’t offer this control – your data lives wherever GitHub’s standard infrastructure puts it.

API endpoints: Integrations must hit your enterprise-specific URL (e.g., api.octocorp.ghe.com) rather than the standard api.github.com.

Identity: GHE.com uses managed user accounts tied to your enterprise’s identity provider, separating enterprise work cleanly from any open-source/personal GitHub activity.

Purpose: GitHub.com is the general-purpose platform for individuals and organizations of any size. GHE.com exists for enterprises with strict data residency or compliance requirements who still want a cloud-hosted (not self-managed) solution – as opposed to GitHub Enterprise Server, which is the fully self-hosted on-prem option.

Changes needed in BcContainerHelper

BcContainerHelper is used by AL-Go for GitHub for handling GitHub packages (NuGet), and this functionality needed some changes due to the GitHub packages NuGet feed URL is different – **https://nuget..ghe.com/** vs. **https://nuget.github.com/** also the GitHub API URL is different, so this is deducted from the NuGet Server Url.

The PR can be found here: https://github.com/microsoft/navcontainerhelper/pull/4167

Changes needed in AL-Go for GitHub

Most changes come from the fact that the URL is different, **https://.ghe.com/** vs. **https://github.com/**. This also changes the API URL by adding api in front of the hostname.

Inside GitHub workflows, we can use environment variables like GITHUB_SERVER_URL and GITHUB_API_URL, which takes care of most of these things.

A bigger challenge is that the GITHUB_TOKEN in workflows on GHE cannot be used for authenticating towards github.com – not even for public repositories and since AL-Go for GitHub still lives on github.com and every enterprise shouldn’t have to have their own version of AL-Go, this poses a few challenges when running Update AL-Go System Files.

Another problem is that you cannot use a template from github.com on ghe.com, so how do I create my repo with https://aka.ms/algopte – if I cannot select my enterprise. The solution here is to create an indirect AL-Go template in your enterprise and keep that up-to-date (I have created a small tool for that) and then your “normal” repositories will use a PTE or AppSource template from your own enterprise and everything is normal.

Beside this, a few other fixes for github.com hardcoded stuff has been fixed, but everything should be working now…

The PR can be found here: https://github.com/microsoft/AL-Go/pull/2309

Sources

• About GitHub Enterprise Cloud with data residency
• Network details for GHE.com
• About GitHub Enterprise Cloud

Enjoy

/Freddy

After publishing my layoff announcement on LinkedIn, which had approximately 1.1 mio views, 7200+ likes and 550+ comments, I decided that my biggest asset was probably my name and reputation. So I created my own company, Freddy.DK ApS, with the goal to stay active in the Business Central community as long as it is rewarding and fun.

And… it has definitely been both rewarding and fun… it is impossible to describe in a few words what I have done, but I will try to list some of the highlights.

Recharging in Greenland

While I truly see my layoff from Microsoft as a gift, it obviously also adds some tension about what’s next. My recommendation to anybody who experience things like this is to pull the plug and recharge, whether you are experiencing Greenland, walking the Camino or doing other adventures is not important, but doing something to clear your mind is truly worth it.

Directions for partners

Torben Kragelund (CEO in the Directions for Partners org) called me before I even announced the layoff and asked me whether I would consider coming and working for the Directions team. The Directions conferences and the Days Of Knowledge events has always been dear to my heart, so I didn’t hesitate in accepting.

And… it has been an amazing journey. From being “on the other side”, to being part of the team has been truly rewarding and you suddenly realize the amount of work needed to pull off conferences like Directions EMEA. I do think that the Directions conferences and the Days of Knowledge events are more important than ever and we need to ensure that we keep evolving these events for partners throughout the world to ensure that the community stays strong and relevant.

I truly believe that every Business Central professional should visit at least one of these events, being Directions, Days Of Knowledge or BC Days – the payback is instant.

Microsoft MVP

From Least Valuable Employee to Most Valuable Professional in less than a year:-)

Having worked with all the Business Central MVPs for a decade, I’ve grown to truly value and respect this group of people. Becoming an MVP and joining the group was a huge milestone for me and I will try to honor this badge to be eligible to many renewals.

BTW – before actually becoming an MVP, I received my MVP of the MVPs award from the Microsoft MVPs. That award is dear to my heart, THANKS!

AL-Go for GitHub

During my last years at Microsoft, I created a product called AL-Go for GitHub and as you might know, this product has now grown to become a central part of app development in Microsoft and with many partners.

While AL-Go for GitHub is plug-and-play, there are still a million settings and ways to setup AL-Go to match your needs. One of my first customers was Bunker Holding Group, who had a very large and impressive setup on Azure DevOps and wanted to move to AL-Go for GitHub. While this sounded easy, it came with a lot demands, requests and new ideas, which wasn’t part of AL-Go.

One of their problems was that their IT department didn’t want people to have admin rights, nor did they want to have people running Docker. This lead to the development of Fkh – Freddy’s Kubernetes Helper, which basically ensures bunker that they are ready when Microsoft stops supporting BcContainerHelper.

So, if you need help on implementing, maintaining or understanding AL-Go for GitHub, you probably won’t find anyone more qualified than me:-)

Fkh – Freddy’s Kubernetes Helper

As already mentioned, the idea behind Fkh (pronounced F-cage) came from my meetings with Bunker Holding to get over the love/hate relationship with Docker running on developer PCs.

Fkh (https://github.com/Freddy-DK/Fkh) is Open-Source and installs in your own Azure Subscription.

Fkh lets authorised GitHub users work with Business Central containers and perform developer tasks on demand — directly from VS Code, a CLI, a Web frontend, or GitHub Actions workflows.

A GitHub-authenticated Azure Function acts as the provisioning gate; Terraform manages all Azure/Kubernetes infrastructure, all Docker containers are running in a Kubernestes cluster, in which you will have a Linux node running MS SQL Server with a persisted drive ensuring that containers doesn’t loose their data and a Windows node running standard Business Central containers connecting to the Linux SQL Server.

Expect many more blog posts about this product…

AI

The impact on AI on the global workforce is/will be huge and it is important to look at AI from many angles. It is very common to look at AI from the angle that AI is going to take our jobs, but I truly believe that there is more to it than that.

AI will definitely destroy jobs, but it will also create jobs and it will redesign jobs. I do think however that tasks and not occupations are the real unit of impact and that the upskilling of the workforce is one of the most important things we can do. World Economic Forum says that 59% of the workforce will need upskilling and training in AI by 2030.

So, while many Tech companies are riding the front of the wave and developers are throwing themselves into agentic development and autonomous agents, many “normal” companies are left in the calm water, not knowing that whether the wave will hit them, thinking: “What now?”

This is one of the reasons why we started a collaboration with Knowledge Partner and are offering AI training for their customers, to get them up to speed on how to use the tools they already have access to, boost personal productivity, but primarily to get an understanding of AI and what it can do for you – in order to get people to think about AI and agents. Read more about this here: https://dalgaskompas.com/

We are planning to extend this collaboration to other partners; running AI training in their name for their customers.

Why Shibas?

One question I got from a lot of people is: “Freddy, why are you always displaying images of a fox?”

It is not a fox, it is a Shiba Inu and the simple reason is, that I am the happy owner of a Shiba Inu, which is probably the most intelligent dog breed that exists, Shiba Inus are famously independent, stubborn, and cat-like and there is a famous saying that goes: a dog may have a master; a Shiba has staff.

The future

The future for Freddy-DK ApS revolves around 4 major pillars:

• Directions for partners conferences and events
• Helping customer and partners with AL-Go for GitHub and Freddy’s Kubernetes Helper (Fkh)
• AI Training and helping partners and customers with their challenges in this area.
• Community contributions (blogging, vlogging, speaking, open-sourcing etc) to help keep the Business Central community strong and vibrant.

Enjoy

Freddy Kristiansen

After 23 engaging years at Microsoft – and having made it through at least 10 rounds of layoffs – my name was pulled from the hat, and I was asked to pack my things and leave.

That is obviously not entirely how it went, but it definitely is how it felt.

On the bright side, this gives me the chance to pursue a long-overdue dream: starting my own business and helping customers and partners in areas where I can truly make a difference.

Running my own business also gives me the flexibility to prioritize myself, my family and our overall wellbeing to a higher extent than has been possible for a long time.

So, what’s next?

As already stated, I’m starting my own business and will soon begin offering services to customers and partners who could use my help – more details coming soon.

I’ll also be dusting off my golf clubs, getting back into a regular exercise routine, and hopefully hitting the bike trails again.

But first, a break: I’ll spend June wrapping things up, then head to Greenland and Iceland in July with my wife and close friends – finally taking a real vacation, without a Microsoft laptop.

Follow me here on my blog, on LinkedIn or on my future homepage, which I will share here as well.

Godspeed

Freddy

Unfortunately, the API comes with very little documentation and the sparse documentation doesn’t contain any information about Business Central. If you however want to investigate things by yourself, the primary docs are:

• https://docs.microsoft.com/en-us/azure/marketplace/azure-app-apis – which is a one pager, describing how to authenticate and then points to
• https://ingestionapi-swagger.azureedge.net/ – for documentation on how to do things.
• https://arsenvlad.medium.com/using-partner-center-ingestion-api-for-managing-azure-application-offers-in-azure-marketplace-b47b290dd947 – a video describing the API. Unfortunately, the video isn’t up to date.

Instead of describing the API and have all partners create their own code to investigate and submit their apps, the latest BcContainerHelper (4.0.3) contains functions to do just this, using the Partner Center Ingestion API.

Authentication

In order to get started, you need a way to authenticate to the Partner Center ingestion API. This can be done using Service 2 Service authentication (which is recommended for workflows and pipelines) or you can use User Impersonation.

Service 2 Service (S2S)

To get started with S2S, you need to complete Step 1 from here: https://docs.microsoft.com/en-us/azure/marketplace/azure-app-apis. After this, you should have a ClientID and a ClientSecret, stored in a KeyVault and the actual authentication is done using the New-BcAuthContext function from BcContainerHelper:

$authcontext = New-BcAuthContext `
    -clientID ($PublisherAppClientIdSecret.SecretValue | Get-PlainText) `
    -clientSecret $PublisherAppClientSecretSecret.SecretValue `
    -Scopes "https://api.partner.microsoft.com/.default" `
    -TenantID "<your AAD tenant>"

User Impersonation

If you, for some reason, can’t or won’t create an AAD App registration for S2S authentication, then the other option for getting an authcontext is to use user impersonation.

$authcontext = New-BcAuthContext `
    -includeDeviceLogin `
    -Scopes "https://api.partner.microsoft.com/user_impersonation offline_access" `
    -tenantID "<your AAD tenant>"

This will invoke the device flow and display a code, which you need to use when authenticating to https://aka.ms/devicelogin

Now, you will have an authcontext, which contains an access token and a refresh token. The access token can typically be used for authentication for 60 minutes. The refreshtoken can be used to get a new access token for typically 90 days and you can store the refresh token in a keyvault to be able to get a new authContext based on the refreshtoken by using this code:

$authcontext = New-BcAuthContext `
    -refreshToken $refreshtoken `
    -Scopes "https://api.partner.microsoft.com/user_impersonation offline_access" `
    -tenantID "<your AAD tenant>"

AuthContext

The $authContext needs to be specified to all functions and you should never need to look insider the Auth Context. Reason for carrying around the AuthContext and not “just” an AccessToken is, that the AccessToken expires after 60 minutes and frequently, pipelines/scripts/tests run longer than 60 minutes. For this reason, the AuthContext contains enough information to renew the AccessToken and all functions in ContainerHelper will check and renew if necessary.  If you ever need to create an authorization header based on the AuthContext, you can do it like this:

$authContext = Renew-BcAuthContext -bcAuthContext $authContext 
$headers += @{ "Authorization" = "Bearer $($authcontext.AccessToken)" }

But again, you won’t need to for the scenarios below, the authcontext is automatically renewed in all functions and uses either the ClientID and ClientSecret or the refresh token to renew.

When you have an AuthContext – you can validate by running:

Get-AppSourceProduct -authContext $authcontext -silent

And you should see a list of all your apps in AppSource.

Submitting an app to AppSource Validation

Currently the Partner Center Ingestion API doesn’t support submitting an App to production directly. You must promote (click Go Live) the submission after technical validation.

The New-AppSourceSubmission function does include an -autoPromote parameter, which waits for the technical validation to complete and after that, it will automatically invoke the promote action. When the API supports AutoPromote, the inner workings of the function will change to utilize this instead of waiting.

With your AuthContext from above, you can get all your products by using:

$products = Get-AppSourceProduct -authContext $authcontext -silent

and get the Product Id of the product you want to work with:

$productName = 'BingMaps.AppSource'
$productId = ($products | Where-Object { $_.name -eq $productName }).id

If you want to get full details of the product, you can use:

$product = Get-AppSourceProduct -authContext $authcontext -productId $productId -includeAll

Now, you can inspect properties of $product. Exaamples:

$product.FeatureAvailability[0].marketStates

marketCode state   
---------- -----   
AE         Disabled
AT         Disabled
AU         Disabled
BE         Disabled
CA         Disabled
CH         Disabled
CO         Disabled
CZ         Disabled
DE         Disabled
DK         Enabled 
EE         Disabled
ES         Disabled 
...

$product.Property

resourceType          : AzureProperty
industries            : {}
categories            : {}
additionalCategories  : {}
submissionVersion     : 
productTags           : {}
appVersion            : 3.0.164.0
useEnterpriseContract : False
termsOfUse            : The terms that applies to Microsoft Dynamics 365 Business Central can be downloaded here: 
                        https://www.microsoft.com/en-us/licensing/product-licensing/products.aspx 
                         
                        If you have signed up to the trial version of Microsoft Dynamics 365 Business Central with an organizational email address, you are governed by the Microsoft 
                        Online Service Trial Agreement, which can be found here: https://go.microsoft.com/fwlink/?linkid=828977 
extendedProperties    : {}
hideKeys              : {}
applicableProducts    : {}
marketingOnlyChange   : False
globalAmendmentTerms  : 
customAmendments      : {}
leveledIndustries     : 
leveledCategories     : @{geolocation=System.Object[]}
@odata.etag           : "0800a065-0000-0800-0000-62ee043a0000"
id                    : 009f7479-f506-216f-d445-5315d5fb9e62

You can also get information about your latest submission by using:

Get-AppSourceSubmission -authContext $authcontext -productId $productId -includeWorkflowDetails
GET https://api.partner.microsoft.com/v1.0/ingestion/products/5fbe0803-a545-4504-b41a-d9d158112360/submissions
GET https://api.partner.microsoft.com/v1.0/ingestion/products/5fbe0803-a545-4504-b41a-d9d158112360/submissions/1152921505695125040
GET https://api.partner.microsoft.com/v1.0/ingestion/products/5fbe0803-a545-4504-b41a-d9d158112360/submissions/1152921505695125040/workflowdetails

resourceType       : Submission
state              : Published
substate           : InStore
targets            : {@{type=Scope; value=Preview}}
resources          : {@{type=Availability; value=4b8c7499-1cb3-acf6-9b5b-c45d2a7040e2}, @{type=Listing; value=0202f16e-e12b-a657-124e-27ed76542ad5}, @{type=Package; 
                     value=2d212b32-f3f4-4d43-ac9b-5783f7a6099f}, @{type=Property; value=ae0f3f9e-b893-bbde-4dd1-3ac0b50496ef}...}
publishedTimeInUtc : 2022-08-04T13:53:31.2590809Z
pendingUpdateInfo  : @{updateType=Create; status=Completed}
releaseNumber      : 28
friendlyName       : Submission 28
areResourcesReady  : True
id                 : 1152921505695125040
WorkflowDetails    : {@{type=Push; state=Success; targetEnvironment=Preview; workflowSteps=System.Object[]; startDateTimeInUtc=2022-08-04T10:37:37.4038218; 
                     completeDateTimeInUtc=2022-08-04T10:51:26.8132496}, @{type=Push; state=Success; targetEnvironment=Live; workflowSteps=System.Object[]; 
                     startDateTimeInUtc=2022-08-04T10:51:57.0499235; completeDateTimeInUtc=2022-08-04T13:53:30.8277395}}

The state/substate of your submission can have the following values:

• Published/InStore – your submission was published and the offer is available in AppSource
• InProgress/Submitted – your submission was submitted and validation is running (during this phase, your submission can be cancelled)
• Published/ReadyToPublish – your submission is in preview and ready to promote / Go Live. At this time you can create a new submission if you don’t want to take this version live.
• ?/? – your submission is in certification/publish phase. This phase cannot be cancelled and you cannot create a new submission until you app has been published.

You can also monitor a submission while running using the Get-AppSourceSubmission function:

$submission = Get-AppSourceSubmission -authContext $authcontext -productId $productId -includeWorkflowDetails
GET https://api.partner.microsoft.com/v1.0/ingestion/products/5fbe0803-a545-4504-b41a-d9d158112360/submissions
GET https://api.partner.microsoft.com/v1.0/ingestion/products/5fbe0803-a545-4504-b41a-d9d158112360/submissions/1152921505695131860
GET https://api.partner.microsoft.com/v1.0/ingestion/products/5fbe0803-a545-4504-b41a-d9d158112360/submissions/1152921505695131860/workflowdetails

PS C:\> $submission.WorkflowDetails

type                  : Push
state                 : InProgress
targetEnvironment     : Preview
workflowSteps         : {@{name=Automated validation; state=Success; startDateTimeInUtc=2022-08-06T06:38:53.8153199; completeDateTimeInUtc=2022-08-06T06:42:08.3546437}, 
                        @{name=Preview Creation; state=Success; startDateTimeInUtc=2022-08-06T06:42:11.2274863; completeDateTimeInUtc=2022-08-06T06:47:30.8841703}, @{name=Publisher 
                        Signoff; state=NotStarted; startDateTimeInUtc=0001-01-01T00:00:00; completeDateTimeInUtc=0001-01-01T00:00:00}}
startDateTimeInUtc    : 2022-08-06T06:37:47.6696794
completeDateTimeInUtc : 0001-01-01T00:00:00

type                  : Push
state                 : NotStarted
targetEnvironment     : Live
workflowSteps         : {@{name=Certification; state=NotStarted; startDateTimeInUtc=0001-01-01T00:00:00; completeDateTimeInUtc=0001-01-01T00:00:00}, @{name=Publish; 
                        state=NotStarted; startDateTimeInUtc=0001-01-01T00:00:00; completeDateTimeInUtc=0001-01-01T00:00:00}}
startDateTimeInUtc    : 0001-01-01T00:00:00
completeDateTimeInUtc : 0001-01-01T00:00:00

The workflowDetails is an array, consisting of two PSCustomObjects. The first is the details about the preview (before pressing Go Live button) and the second is the details about the Go Live (after pressing Go Live button). A little later, the workflowDetails will look like this:

$submission = Get-AppSourceSubmission -authContext $authcontext -productId $productId -includeWorkflowDetails
GET https://api.partner.microsoft.com/v1.0/ingestion/products/5fbe0803-a545-4504-b41a-d9d158112360/submissions
GET https://api.partner.microsoft.com/v1.0/ingestion/products/5fbe0803-a545-4504-b41a-d9d158112360/submissions/1152921505695131860
GET https://api.partner.microsoft.com/v1.0/ingestion/products/5fbe0803-a545-4504-b41a-d9d158112360/submissions/1152921505695131860/workflowdetails

PS C:\> $submission

resourceType       : Submission
state              : Published
substate           : ReadyToPublish
targets            : {@{type=Scope; value=Preview}}
resources          : {@{type=Availability; value=a179fdd3-9950-5235-493d-ffe6dd02b4aa}, @{type=Listing; value=280ae301-a6ca-293c-88b3-8b49cfe58480}, @{type=Package; 
                     value=6ba6a084-9bba-4c3c-8eae-cea773809696}, @{type=Property; value=009f7479-f506-216f-d445-5315d5fb9e62}...}
publishedTimeInUtc : 2022-08-06T06:47:36.5830633Z
pendingUpdateInfo  : @{updateType=Create; status=Completed}
releaseNumber      : 29
friendlyName       : Submission 29
areResourcesReady  : True
id                 : 1152921505695131860
WorkflowDetails    : {@{type=Push; state=Success; targetEnvironment=Preview; workflowSteps=System.Object[]; startDateTimeInUtc=2022-08-06T06:37:47.6696794; 
                     completeDateTimeInUtc=2022-08-06T06:47:35.721944}, @{type=Push; state=NotStarted; targetEnvironment=Live; workflowSteps=System.Object[]; 
                     startDateTimeInUtc=0001-01-01T00:00:00; completeDateTimeInUtc=0001-01-01T00:00:00}}
type                  : Push
state                 : Success
targetEnvironment     : Preview
workflowSteps         : {@{name=Automated validation; state=Success; startDateTimeInUtc=2022-08-06T06:38:53.8153199; completeDateTimeInUtc=2022-08-06T06:42:08.3546437}, 
                        @{name=Preview Creation; state=Success; startDateTimeInUtc=2022-08-06T06:42:11.2274863; completeDateTimeInUtc=2022-08-06T06:47:30.8841703}, @{name=Publisher 
                        Signoff; state=Success; startDateTimeInUtc=2022-08-06T06:47:32.6862082; completeDateTimeInUtc=2022-08-06T06:47:35.721944}}
startDateTimeInUtc    : 2022-08-06T06:37:47.6696794
completeDateTimeInUtc : 2022-08-06T06:47:35.721944

type                  : Push
state                 : NotStarted
targetEnvironment     : Live
workflowSteps         : {@{name=Certification; state=NotStarted; startDateTimeInUtc=0001-01-01T00:00:00; completeDateTimeInUtc=0001-01-01T00:00:00}, @{name=Publish; 
                        state=NotStarted; startDateTimeInUtc=0001-01-01T00:00:00; completeDateTimeInUtc=0001-01-01T00:00:00}}
startDateTimeInUtc    : 0001-01-01T00:00:00
completeDateTimeInUtc : 0001-01-01T00:00:00

This means that your partner center UI will look like this:

And you can press Go Live (or run Promote-AppSourceSubmission) in order to take the app live (or invoke certification / marketing validation)

New-AppSourceSubmission

At this state, you can submit a new version for validation – you do not need to take the submission live. Submitting a new version of your app is done using the New-AppSourceSubmission function:

New-AppSourceSubmission -authContext $authContext -productId $product.Id -appFile $appFile -silent
Extracting C:\Users\freddyk\Downloads\BingMaps.AppSource-main-Apps-3.0.164.0\Freddy Kristiansen_BingMaps.AppSource_3.0.164.0.app
Automated validation........ Success
Preview Creation.......... Success
Publisher Signoff Success
New AppSource submission succeeded

resourceType       : Submission
state              : Published
substate           : ReadyToPublish
targets            : {@{type=Scope; value=Preview}}
resources          : {@{type=Availability; value=553dfb07-1fe0-6e19-a136-cf6f310127b4}, @{type=Listing; value=383dfff3-5479-dba7-7480-f61f3022ecfd}, @{type=Package; 
                     value=141ca192-e27b-4529-be55-f96de1e1710d}, @{type=Property; value=86c43c9b-6184-ff69-4621-a644cc167977}...}
publishedTimeInUtc : 2022-08-06T07:26:10.2335664Z
pendingUpdateInfo  : @{updateType=Create; status=Completed}
releaseNumber      : 31
friendlyName       : Submission 31
areResourcesReady  : True
id                 : 1152921505695131645

If you include the -autoPromote flag, the function will wait and automatically promote the submission to production / Go Live. If you include the doNotWait flag, the function will not wait for completion. If you include the autoPromote AND the doNotWait flag, the function will (in the current version) still wait for the preview creation to be complete and then promote the submission. For a later version of the API (when IsAutoPromote is supported for Business Central Apps) the function will be rewritten to utilize the API’s support of autoPromote instead of waiting and calling the API again.

This also means, that if you cancel the function while waiting for preview to complete – the autoPromote flag has no effect.

When you specify –LibraryAppFiles to New-AppSourceSubmission, you can specify an array of files. If you only specify one file, it is uploaded as is to Partner Center. If you specify an array of files, they will be zipped together into a file with the same name as the AppFile specified, followed by .libraries.zip, meaning that if you want to control the filename, you need to do the zipping yourself.

If your submission fails, you will be able to see the error message in the portal. Currently, I have not found a way to get the error message through the API. I have submitted a question for the team and expect to know more soon (and change the code)

Enjoy

Freddy Kristiansen
Technical Evangelist

This means that you will get new updates before they are released. It also means that the actions you are using are instantly updated when we deploy a new version for preview and thus might be out of sync with your workflows.

One example of this is the preview, which was released yesterday (June 26th, 2022) to fix issue #168 will cause CI/CD workflows to stop publishing artifacts until you have run the Update AL-Go System Files.

Technically, the reason for this is that the RunPipeline action now published artifacts into a folder called .buildartifacts (instead of output) and the earlier CICD.yaml will look in the output folder:

After updating the AL-Go System Files, everything will work normally again.

Note that this problem will NOT occur for people using the released bits. They can safely update to the latest version after it is released, and they will get workflows and actions updated together.

Enjoy

Freddy Kristiansen
Technical Evangelist

This blog post will describe some details about how this function works.

The function takes a containerName, a scriptblock and an argument list as parameters and will execute this scriptblock inside the container.

The function does however have two ways of performing the exact same function. If the user is using PowerShell as administrator AND the setting called usePsSession is not specifically set to false, then the function will use PowerShell remoting to execute the PowerShell code snippet inside the container.

PowerShell remoting is only available when running with elevated permissions (as administrator). If you are not, or if you have set usePsSession to false – then the function will use docker exec to execute the PowerShell code snippet inside the container.

Using PowerShell remoting

Invoking a PowerShell snippet using PowerShell remoting is done by establishing a PowerShell Session to the container (caching that session for future use) and invoking the scriptblock using that session.

Establishing a PowerShell session takes approx. 0.9 second (on my machine). Any subsequent usages of that session take approx. 4 milliseconds. The caching of the session is very important for performance on chatty scripts. To illustrate this, you can run this script:

$bcContainerHelperConfig.usePsSession = $true
$containerName = "bcserver"
Remove-BcContainerSession -containerName $containerName

Measure-Command {
    $what = Invoke-scriptInBcContainer $containerName -scriptBlock { Param($year)
        "Summer of $year"
    } -argumentList 69
} | ForEach-Object { Write-Host "Time spent: $($_.TotalMilliseconds)" }
Write-Host -ForegroundColor Yellow $what

$cnt = 100
Measure-Command {
    1..$cnt | % {
        $what = Invoke-scriptInBcContainer $containerName -scriptBlock { Param($year)
            "Summer of $year"
        } -argumentList 69
    }
} | ForEach-Object { Write-Host "Time spent: $($_.TotalMilliseconds/$cnt)" }
Write-Host -ForegroundColor Yellow $what

The output of this script on my machine is:

NOTE that the subsequent runs ONLY is if the Invoke-ScriptInBcContainer happens in the SAME PowerShell session on the host.

Using Docker Exec

If PowerShell remoting is not possible (or you elect not to use it), BcContainerHelper will wrap your scriptblock in some pre- and post- code to best simulate that you are running in a session inside the container and write this PowerShell script to the disk in a folder, which is shared with the container (under the hostHelperFolder on the host).

Now it will serialize the parameters, converting all secureStrings to encrypted strings (else they would not be accessible inside the container) and use docker exec to run the PowerShell script file.

The return value is written to another file, picked up by the host after docker exec.

Sounds cumbersome, but wrapped inside Invoke-ScriptInBcContainer is becomes easy to use. Running the same script as above (just with usePsSession set to false), reveals:

In this case, it doesn’t really matter whether the subsequent calls are in seperate PowerShell sessions.

Two ways of running your pipelines/workflows

When running on Azure DevOps and using one DevOps task to create the container, another one to compile and another one to publish – each of these tasks are seperate PowerShell sessions and the difference between running using PowerShell remoting or Docker exec might not be as outspoken.

When running the Run-AlPipeline function (the do-it-all function used in later versions of the CI/CD HOL and also AL-Go for GitHub), everything happens in one PowerShell session, and it can really take advantage of using PowerShell sessions. Here we might see a 25% performance cut by using Docker exec.

AL-Go for GitHub even adds a RemoveBcContainer override when calling Run-AlPipeline in order to remove the session by killing the underlying process instead of removing the session and potentially hanging.

If you are using individual tasks, you have two options to avoid the famous freezing DevOps tasks:

1. Set UsePsSession to false
2. Wrap your code in a try / finally, where you use Remove-BcContainerSession with -killPsSessionProcess in the finally section of your task.

Error handling in Invoke-ScriptInBcContainer

In the latest version of BcContainerHelper, error handling using Invoke-ScriptInBcContainer has improved significantly.

Try running this script with UsePsSession true or false:

$appInfo = Invoke-scriptInBcContainer $containerName -scriptBlock {
    Get-NavAppInfo -ServerInstance X
}

As there is no serverInstance X – it will fail, but it does add some additional information:

this was certainly not the case before 3.0.9:-)

As a bonus, it will actually dump all event log entries that have been added while the script was running. It will also investigate whether any of the event log entries is an out-of-memory exception and if that is the case, it will re-throw an out-of-memory exception.

You will also see whether your script caused the ServiceTier to crash and end up as not running.

Returning objects

Now try to run this script:

$appInfo = Invoke-scriptInBcContainer -containerName $containerName -scriptBlock {
    Get-NavAppInfo -ServerInstance $serverInstance
}
Write-Host -ForegroundColor Yellow "There are $($appInfo.Count) apps"
$appInfo[0] | Out-Host

You will see a slightly different output. When running using a PsSession, the serialized objects have a few extra fields added:

The PSComputerName and RunspaceId are added to all objects serialized from Invoke-ScriptInBcontainer to the host. You can just ignore these; I do not use them for anything and I haven’t done any effort to try and remove them.

You cannot return a SecureString

Only known limitation to using Invoke-ScriptInBcContainer with Docker Exec is, that you cannot return a SecureString from the container. Oher than that, there should be parity between the functionality of using PsSession and Docker Exec.

If not, please file an issue on https://github.com/microsoft/navcontainerhelper/issues.

Enjoy

Freddy Kristiansen
Technical Evangelist

Hopefully the fixes, which are going into BcContainerHelper today will fix this once and for good.

Not a BcContainerHelper problem

My immediate thinking was that this is not a BcContainerHelper problem, but that doesn’t mean that it cannot be fixed in BcContainerHelper. There are several workarounds in BcContainerHelper to cope with wrongdoings of other software packages, even just-in-time patching of Business Central some times.

I learned that people were seeing their DevOps tasks complete and then freeze. Everything was A-OK but the pipeline would just hang and eventually timeout and fail. I had even seen the same once on GitHub Actions, but some partners were complaining that they had this very frequently.

There was a bug files on Azure Pipelines here, and then another bug on BcContainerHelper here. Julian from GWS was so kind to setup a repository on Azure DevOps, running 20 simultaneous builds and almost certain, that at least one would fail in every run.

I got access to the repo and started debugging. My first hunch was, that some process, thread or job was running on the agent and the DevOps agent would wait for this to complete before finishing the task.

I was right!

The PsSession

It turned out to be the PsSession, which is a PowerShell session, which is created by Invoke-ScriptInBcContainer, cached and re-used again and again. First attempt was to just remove the PsSession, but this also caused the task to freeze.

The problem seemed to be that removing the session (using the PowerShell command Remove-PsSession) would hang – and exiting the PowerShell task would implicitly remove the session, meaning that the task would hang – some times.

2 solutions possible

There could only be two solutions:

1. Find a better way to remove the session
2. Avoid using the session

and I kind of found a solution to both.

Find a better way to remove the session

I did manage to find a way, where I could remove the session without freezing PowerShell. Instead of using Remove-PsSession, I could locate the process ID of the session (using process isolation, this process ID is the process ID on the host) and simply stop the process.

This works – but unfortunately, I don’t have any way of intercepting the implicit session removal when the PowerShell task is ending, so it would still freeze if I didn’t remove the session manually.

I don’t think the right solution would be to ask everybody to remove all sessions in all tasks in all pipelines – we need a better solution.

Avoid using the PsSession

This was a fairly easy fix. Add

"UsePsSession":  false

To c:\ProgramData\BcContainerHelper\BcContainerHelper.config.json and you should be good. This causes Invoke-ScriptInBcContainer to use docker exec instead of a PsSession.

It actually packages your scriptblock in a script .ps1 file, encodes the parameters and uses docker exec to run the script. Return values are written to another file and then returned from the function, but… – to be honest I never did much optimization of running Invoke-ScriptInBcContainer without a PsSession and I was almost certain that there would be bugs.

I was pleased to see that most bugs were in error handling. If something went wrong in the scriptblock, then the error wasn’t returned correctly. Beside this, the old version didn’t support if hostHelperFolder is different from ContainerHelperFolder. This could be a problem for some.

In the next pre-release of BcContainerHelper, these issues are fixed, and you should now get the correct error surfaced from the function. This new functionality could potentially break behavior, so I have added a setting, which you can set to false to get the “old and faulty” behavior back (if this worked for you):

$bcContainerHelperConfig.addTryCatchToScriptBlock = $false

If you discover an example where the new behavior doesn’t work, please don’t just set this setting to false and live with it. Please open an issue on https://github.com/microsoft/navcontainerhelper/issues and explain which scriptblock the new mechanism doesn’t work with.

Out of memory

Additionally, one type of error, which has been hard to detect earlier is Out Of Memory. When I (inside an Invoke-ScriptInBcContainer) use the PowerShell CmdLet to publish an app to the service tier and this causes the servicetier to crash due to lack of memory, I would typically get errors like: “The socket connection was aborted.” as this is what the PowerShell session sees.

In this new version (both using sessions and docker exec), I will (if the scriptblock throws an exception) inspect the eventlog for entries pushed by Business Central or MS SQL – and if any of those have thrown an OutOfMemory exception, I will throw an OutOfMemory error (the root cause) instead of the socket connection error (the symptom).

This should help the troubleshooting in some cases.

The pre-release

So, if you have had this problem in your pipelines, please install the next pre-release (preview605 or newer) of BcContainerHelper on your agents and add this setting to bcContainerHelper.settings.json on your agents:

"UsePsSession":  false

Then this should fix the issue. Let me know whether it works. I was considering adding the setting as default for GitHub Actions and Azure Pipelines, but it does have a performance impact, so I decided not to.

BTW. Even though I only saw this once on AL-Go for GitHub, I will (in the next version) use the mechanism to stop the PsSession process by default, meaning that AL-Go for GitHub should not have hanging sessions.

Thanks

Freddy Kristiansen
Technical Evangelist

Instead, it will explain ways for you to store secrets, which are used for AL-Go for GitHub. In almost every DevOps setup, you will have to store some keys, passwords, tokens or like. In GitHub, these are called secrets and AL-Go will look for a set of secrets by their name.

This blog post will also touch upon how you can use GitHub organizations and environments with your customer projects.

GitHub secrets vs. Azure KeyVault

AL-Go for GitHub supports two ways of storing your secrets, GitHub secrets or Azure KeyVault. If you store your secrets in an Azure KeyVault you need to provide access to the Azure KeyVault using a GitHub secret. This is done by following this guideline including the Add a role assignment step. The location of the GitHub secret created determines the access to the KeyVault, meaning that you can have and use multiple KeyVaults if you like.

GitHub secrets can be repository secrets, created for a single repository, they can be organization secrets, created one or more repositories in the organization or they can be environment secrets, created for a single environment.

You can set GitHub secrets through the GitHub API (or GH command line), but you cannot access the secrets from your local machine.

Repository secrets

Repository secrets are available to all repositories (private or public, personal or organizational). If a secret is created for a repository, it is only accessible within GitHub actions for that repository. Repository secrets are not included when forking a repository (obviously).

For repositories created under your personal account, this is really the only place you can store secrets for the workflows. For repositories created under an organization, you can also use organization secrets.

Organization secrets

If a secret is created for an organization, you can select which repositories the secret should be available for:

The InsiderSasToken is a good example of an organization secret, which typically is available to all repositories and when you renew the value of the token every 6 months, it automatically renews for all repos.

The LicenseFileUrl is an example of an organization secret, which typically will be available to a selected number of repositories. If you have two different License files, which each should be available to a number of repositories, you specify which secret to use in the settings of the individual repository. More about this later.

Environment secrets

If a secret is created for an environment, the secret is only available during deployment to that environment. Environments (and thus also environment secrets) are only available for public repositories or for repositories in organizations with Teams or Enterprise subscription.

Currently, you can place 3 secrets under the environment:

• EnvironmentName contains the actual Business Central Environment name. If not specified, the name of the environment in GitHub is used.
• AuthContext contains the authorization context for the environment.
• Projects is only used if the repository is multi-project. The secret contains a comma separated list of the projects to be published to the environment. Default is all. (Note that every project can have multiple apps, which are all included)

If you are using a private repository in a free GitHub subscription, where environments are not available, you can create environments in the settings file and you can create these secrets as **\_EnvironmentName** and **\_AuthContext**.

At the time writing this blog post, you cannot specify projects unless using environment secrets. In a future version, it will be possible to specify projects as a setting instead.

Priority order

If secrets exist in multiple places, the order of priority is

1. Environment secret
2. Repository secret
3. Organization secret
4. Azure KeyVault specified in environment secret
5. Azure KeyVault specified in repository secret
6. Azure KeyVault specified in organization secret

As earlier stated, environment secrets are only available during deployment to the specific environment.

Forks

If you fork a GitHub repository to your personal or organization account, you obviously do NOT get a copy of the secrets from that repository. GitHub actions in the main repository, also cannot access the secrets while running a CI/CD workflow based on a Pull Request from a fork (An evil PR could reveal the secrets).

This means that if your repository contains an AppSource App (which currently always requires a license file URL), you will always get this error during the CI/CD workflow run on the Pull Request from a fork:

and in the details:

If you review the code and decide to merge anyway, the CI/CD workflow will re-run based on the commit and will now have access to the secrets.

For this and other reasons, the recommendation is to use feature branches, from which the Pull Request will have access to the necessary secrets and the ability to build, publish and test your app.

In a future version AL-Go we will modify the CI/CD workflow to still perform the compile during the Pull Request but skip the publish step and the test run step and replace the error with a warning stated that the app has not been published and tested.

Named secrets

AL-Go for GitHub uses settings and secrets to enable functionality.

If the Code Sign certificate secrets are available, then the CI/CD workflow automatically signs your app, if the LicenseFileUrl secret is available, it is used during build, if a StorageContext secret is available, the CI/CD workflow will automatically publish build artifacts to a storage account, etc. etc.

Below is a list of named secrets you can create in order to get and use additional functionality.

When adding new functionality to AL-Go for GitHub, more secrets might be added.

Secret name indirections

As already mentioned, secrets are located by name and secrets can be shared between multiple repositories. Let’s say you have two License files. One license file should be used for 5 of your repositories and another license file should be used for another 5 of your repositories. You can however not create two organization secrets called LicenseFileUrl and assign them to 5 repositories each and you don’t really want to add the secrets to the individual repositories, as this means you would have to modify every single repo when you have an update to the secret.

For this, you can use secret name indirections. In the individual repository, you can create a setting called LicenseFileUrlSecretName containing the value ContosoLicenseFile, then the secret called ConsotoLicenseFile is used as LicenseFileUrl in this repository.

The same mechanism can be used for all secrets. Create a setting in the repository called **SecretName** and your secret will be read from that name instead.

Recommendations

My recommendation when it comes to organizations and secrets are as follows:

• One GitHub organization per partner (use Teams or Enterprise subscription)
  • for IP owned by the partner
  • Use organizational secrets for developer license, certificates etc.
  • Use environment secrets for authorization to customer environments
  • Setup self-hosted agents for the organization to improve build performance
• One GitHub organization per customer (Free or Teams license)
  • for IP owned by or shared with the customer
  • use organization secrets for authorization to customer environments
  • Optionally use self-hosted agents for performance

Hope this helps

Freddy Kristiansen
Technical Evangelist

As an example, achim-t have run test scripts at least 20 times here, since it wasn’t possible for me to repro the problems, but also this, this and several other issues are from people having issues. Typically, the problem goes away when you use hyperv isolation, when you switch off Windows Defender or other anti-virus software – or when you are running on a Windows Server OS.

New Generic Image

As a result, a new generic image (currently version 1.0.2.4), which should resolve most of these issues (for NAV/BC versions 15 and up) is available in preview at this time – add -dev to the generic image name and you will get the preview.

-useGenericImage "$(Get-BestGenericImageName)-dev"

Also, the latest BcContainerHelper preview will automatically select the preview image when creating containers, there you don’t have to do anything. The next BcContainerHelper will even present you with a warning if you are running an OS, isolation mode and/or NAV/BC version which might require you to use Hyper-V or switch off Windows Defender while creating the container.

You can determine which generic image version you are using by looking for the Generic Tag in the container output (the -dev part is included in the next BcContainerHelper version):

The new generic image will likely be promoted to prod within the next week, so please let me know if you run into any issues when using this version, by creating an issue on https://github.com/microsoft/navcontainerhelper/issues.

Note: Do not respond to other people’s issues – create your own, thanks.

Thanks

Freddy Kristiansen
Technical Evangelist

Currently we don’t have any automated way of publishing your app to AppSource – that is something we are working on and some day in the future, when it becomes possible, you will get a workflow in AL-Go for GitHub which handles this automatically.

This blog post will talk about PTEs, and what features are available in AL-Go for GitHub to assist you deploying your PTEs to customers.

Environments

In this blog post I will distinguish between 4 different types of environments:

The DEV environment (Development) which currently can be a local docker based environment or an online sandbox environment, but in the future, you will also be able to use hosted docker based environment or Azure Container Instances or Azure VMs. Stay tuned for this functionality coming to a repository near you.

The QA environment (Quality Assurance) is an online sandbox environment, which always holds the latest successful build of your app. This environment contains standard demo data from Business Central and your app and is the environment for which continuous deployment is setup.

The FAT environment (Final Acceptance Test) is an online sandbox environment, which is a copy of the customers production environment and is used to allow the customer to test the solution before releasing to production.

The PROD environment (Production) is your customers live production environment. Only released bits makes it to the production environment, which is the life nerve of your customer.

You might have different terminologies, or you might have different needs, but the essence of these 3 environments is, that the QA environment is subject to continuous deployment for every successful build from main. The FAT environment is where you publish your release candidate to allow your customer hands on and the PROD environment is the holy grail.

The actual creation of the environments is not part of AL-Go for GitHub – the environments are created in the Dynamics 365 Business Central admin center.

In this blog post, I will explain how to setup deployment for these 3 types of environments for one project to one or two different customers, both using the Environments feature in GitHub, which comes with paid licenses or the settings file option from AL-Go for GitHub.

In my case, my GitHub organization (BusinessCentralApps) is a paid Team license:

Setting up environments using GitHub Environments

I created these three environments in my Admin Center:

In my repository (Contoso-App3), under Settings -> Environments, I have added 3 environments, with no additional settings.

Note that I have added an annotation to the final acceptance test environment and the production environment. All environments with annotations like (FAT), (PROD), (Final Acceptance Test) or (Production) will be ignored by the continuous deployment step in the CI/CD workflow. Environments created as production environments in Admin Center cannot be used for continuous deployment (even if the environment doesn’t have any annotation).

If the name of the environment in the admin center is different from name in environments, you can create an environment secret called EnvironmentName under the environment, containing the actual environment name:

Note, that it you enter the value in Upper Case, the actual environment name will be hidden in the output of the workflow.

You can also create a repository secret called MyFAT_EnvironmentName if you prefer to have your secrets in the repository instead of under the Environment.

You also need to setup authentication to the environments. For this, you can setup S2S like described here, or you can use delegation and create your AUTHCONTEXT secret value using this PowerShell script (on a machine with the BcContainerHelper 3.0.8 or higher):

$AuthContext = New-BcAuthContext -includeDeviceLoginGet-ALGoAuthContext -bcAuthContext $AuthContext | Set-Clipboard

In the repository, under Settings -> Secrets -> Actions click New Repository Secret and create a secret called AUTHCONTEXT with this value.

After this, I can run the CI/CD workflow and see that my QA environment (and only my QA environment) receives my App3.

Every time you add features and functionality to our app and complete a pull request to the main branch, the CI/CD branch will run and deploy to the QA environment.

After the development is done, you run the Publish To Environment workflow, select which build to publish (latest is the latest build) and enter the name of your Final Acceptance Test name (MyFAT in our case):

After the workflow completes

We can investigate the deploy step and see the actual name of our environment

Now, the customer will perform final acceptance test of the solution and if he discovers any bugs, we will fix the bugs and redeploy to the FAT environment.

If you look in the output, you will notice that when publishing to environments of type Sandbox, AL-Go for Github will use the development endpoint.

When the solution has been accepted by the customer, we create a release of the app:

when done, we can publish to PROD

and looking at the workflow output, you will see that the automation API is used for the deployment:

at the same time, the Create Release workflow also updated the version number in the repository, and you can now work on the next version of your app.

Environment protection rules

When using the environments feature in GitHub, you can setup environment protection to ensure that the customer (or customer responsible) approves the deployment before it actually happens.

Individual AUTHCONTEXT

If the PROD environment uses a different authorization context than the QA and FAT environments, you can create an environment secret (a secret defined under the Environment in the repository) called AUTHCONTEXT and this will override the global AUTHCONTEXT secret when deploying to PROD. You can also create a repository secret called PROD_AUTHCONTEXT, which also will take precedence over the global AUTHCONTEXT for the PROD environment.

Setup environments when using a free GitHub tier

Even though the environments feature is not available when using a free GitHub subscription, AL-Go for GitHub still allows you to publish to environments.

Obviously, you cannot setup environment protection rules and you cannot have environment secrets, but you can create your environments in the repository settings file and you can use repository secrets like **\_** to add “environment secrets”. These secrets will obviously be available throughout the workflows, but AL-Go for GitHub will use them during deployment.

In a different Business Central tenant (another customer who also want our app), I have added 3 new environments (DE):

When you have multiple customers for one repository, you will likely name the environments in AL-Go for GitHub after the name of the customer or like.

I have added 3 additional environments from a different customer to our repository using the repository settings file (.github\AL-Go-Settings.json):

and added repository secrets for the actual name and the authorization context for these environments:

and now, when I run the CI/CD workflow, I can see that it deploys to two QA environments:

and when done, both environments will now contain this new build

When publishing to environments, I can use a naming pattern like *(FAT):

to deploy to all final acceptance test environments:

and *(Production) or any other naming patterns based on the environment name in GitHub or settings. to deploy to all production environments.

The very very short version

The very very short story of this long blog post is, that you can define any number of environments in GitHub environments or AL-Go-Settings and the ones without annotations (and are not production environments) will be deployed during CI/CD. The remaining environments can be deployed to using the Publish To Environment workflow, by specifying the environment name or pattern.

The authorization context and the actual environment name (if different from the GitHub name) must be added as secrets (AUTHCONTEXT and EnvironmentName) under the environment or following the naming pattern **\_**.

Enjoy

Freddy Kristiansen
Technical Evangelist