Make AL:Go pipelines for your PTE Application
In this Blog series we will cover more about creating and managing your AL:Go pipelines.
This blog is split into multiple parts. We will do the first part for your PTE application and then for the App Source application. After completing those two parts, we will focus more on the customization of pipelines to meet your needs. Generally looking, creating a PTE pipeline is easier, and doesn’t require too many additional settings like signing a certificate. So, let’s warm up and get familiar with it by starting with AL:Go PTE pipelines!
AL:Go PTE GitHub Template
AL:Go GitHub template for PTE application can be found here:
Of course you could use this repository as template:
But I think in most cases you already have an extension for which you would need pipelines.
Start by cloning AL-Go-PTE repository:
You would need folders:
- .AL-Go
- .github
Copy those folders to your extension repository.
Clean project:
After pasting new folders:
Well done, this is the first step! 🚀
💡 This can be also done by running pipeline workflow called: Add existing app or test app
Basic settings in new copied files
The next step is to change settings.json in .AL-Go folder:
Depending on which code base container you would like to run you would define country, in this case, I am using w1, but you can run on specific localization.
An important part is to change “appFolders” settings, initially, it comes with the default which is [], but running with this setting doesn’t work. This setting depends on your project structure, if you are using it like I am for this test:
You would define [ “\\” ] since you don’t have a sub folder for your application.
In most cases, you would have a sub folder like .src, so you would define that one after \\.
Runners
One thing that I would like to address now is runner for this pipeline is by default windows-latest.
You would need to change this if you would like to use self-hosted runner. This is just one of the things which I would like to cover in separate blog post after PTE and App Source pipelines.
Adding access token to pipeline
Some of the pipelines do require GitHub account to create Pull Requests for you and so. In order to do so, you would need to generate a token for the GitHub account which would do that:
It is under: Personal Access Tokens (Classic)
What to do with it?
Go to Settings for your repository and create a Repository secret with the name: GHTOKENWORKFLOW
Running your first pipeline (Update AL-Go System Files)
You just cloned all and copied, correct, but refresh also the code base:
It would remove you un-necessary workflows like for Power Platform.
💡 One IMPORTANT thing to keep in mind is that if you run this action it will overwrite any customization you did.
So, when running this to keep with updates of AL-Go you would need to resolve conflicts, like this:
I would like to keep using self-hosted runner.
When run and if there are any updates it will create Pull Request for you:
About CI/CD Pipeline
When you commit /PR merge to the master/default branch, now it will automatically start CI/CD pipeline.
Artifacts are automatically generated and each CI/CD run increases the application build number, by +0.0.1
Build App when PR is created
Yes, this one comes by default when copied.
When you create Pull Request it will automatically have build pipeline scheduled. This will make sure that your extension is always compilable!
Pipelines Set (Workflows)
Which pipelines (workflows) do you get with AL:Go template:
- CI/CD – running with each commit/PR merge to master/default branch
- Create release – creating release of the application
- Increment version number – increasing version number in app.json for the extension
- Test Current – test against current version artifact of Business Central
- Text Next Major, Minor – test against next major/minor version artifact of Business Central
- Update AL-Go System Files – updates code base of AL-Go and creates PR with changes (possible destructive changes)
This are in my opinion the ones which are mostly used, rest you will use rarely.
CI/CD Pipeline
CI/CD – running with each commit/PR merge to master/default branch
When PR is completed:
CI/CD automatically runs.
Release pipeline
With Create release pipeline you can create release version.
But you would need some input parameters for the pipeline, parameters:
- Use workflow from – from which branch you want to create release
- Name of the release – in most cases name of the application
- Tag of the release – should be application version of the release
- Create Release Branch? – creating new branch for the release
- New version number for the master branch after the release
- Direct commit? – whether pipeline will create pull request for the version update or directly commit
Deploy extension to cloud environment
Let’s see now how you can publish app directly from GitHub pipeline.
You need to get BC Auth Context first:
You get Auth Context by executing following command:
$AuthContext = New-BcAuthContext -includeDeviceLogin Get-ALGoAuthContext -bcAuthContext $AuthContext | Set-Clipboard
The next step is to create an Auth Context secret for your runner, on repository settings.
Depending on environment where you want to publish, you would create specific AuthContext secret for repository:
So, creating Prod-Copy-AuthContext with previously generated BCAuthContext:
You can have also multiple AuthContext to deploy to multiple environments at same time!
However, there is one catch, if you use a self-hosted runner like me, you would need to change that, otherwise you will have issues with publishing.
In AL-GO-Settings.json you will define the environment name and runs-on which defines the runner for your pipeline.
You may also notice parameter “DependencyInstallMode” which is new parameter added for Deploy.ps1:
`deployTo<environment>` now has an additional property called DependencyInstallMode, which determines how dependencies are deployed if GenerateDependencyArtifact is true. Default value is `install` to install dependencies if not already installed. Other values are `ignore` for ignoring dependencies, `upgrade` for upgrading dependencies if possible and `forceUpgrade` for force upgrading dependencies.
Annnnd yes, this pipeline can also publish your app to production environments, you would need to set continuous delivery to false in order to do that:
– `deliverTo<deliverytarget>` now has an additional property called `ContinuousDelivery`, indicating whether or not to run continuous delivery to this deliveryTarget. Default is true.
Settings per pipeline (workflow)
This will be covered separately in the next steps, but just to mention shorty. You could have global settings and per pipeline.
Global settings for pipelines can be set in AL-Go-Settings.json
If you would like to have settings for specific pipelines you could do the name of workflow followed by .settings.json, like this:
What is the difference?
Well having it under AL-Go Setting it will apply to all pipelines (workflows). For example if you define this part:
In AL-Go-Settings.json it will also do publish to environment when running CI/CD pipeline, but if you define this settings under PublishToEnvironment.settings.json, then it will be applying only to that pipeline (workflow).
We will come back to different settings in some other parts of this blog series.
This blog post ended already longer than planned. We will draw a line here and summarize. With this blog post, you learned how you can set pipelines for your GitHub AL project. Pipelines can save you time. By the end of this blog series about Pipelines on GitHub, you will have full knowledge of how to set up and what are all the benefits and use cases from pipelines. Start easy and simple, follow this first blog post of the series, set the first simple build and CI/CD pipelines, add publish to environment workflow, and then in the next series extend your pipelines further and further. 🚀
