DOCSEARCHbyAlgolia
Submit Docs

AL-Go for GitHub

repository·main·Indexed 19 days ago

https://github.com/microsoft/al-go

A collection of GitHub templates and actions designed to automate and maintain professional DevOps processes for Microsoft Dynamics 365 Business Central AL projects. It includes actions for compiling apps, building Power Platform solutions, analyzing tests, generating reference documentation via ALDoc and DocFx, and managing build artifacts.

Tokens
75.6K
Snippets
137
Records
360
Agent score
65%

What's inside AL-Go

  1. What is AL-Go for GitHub?

    main
    AL-Go for GitHub is a plug-and-play DevOps solution designed specifically for Business Central development on GitHub. It is an open-source, free-to-use tool (though GitHub hosting costs still apply) that supports both Per-Tenant Extensions (PTEs) and AppSource apps. It is designed to be easy to maintain without requiring prior expertise in Docker, PowerShell, or YAML, effectively turning DevOps into a tool rather than a specialized investment area.

  2. Overview of AL-Go Actions

    main

    AL-Go Actions is a collection of GitHub Actions designed to be used by AL-Go for GitHub templates. These actions automate various stages of the application lifecycle, including app creation, dependency management, testing, deployment, and release note generation.

    For more detailed information and learning resources, visit https://aka.ms/AL-Go.

  3. Use the AL-Go Per Tenant Extension Template

    main
    The AL-Go Per Tenant Extension Template is a specialized repository template designed for managing Per-tenant Extensions (PTEs) for Microsoft Dynamics 365 Business Central. Developers can use this template to establish a standardized CI/CD and management workflow for their specific Business Central tenants using AL-Go.

  5. Ways to add an app to your repository

    main

    You can integrate a new application into your AL-Go for GitHub repository using one of the following methods:

    • Create a new app workflow: Use the built-in GitHub Action workflow to generate a new app structure and start coding immediately.
    • Add existing app or test app workflow: Upload one or more .app files, and AL-Go will extract the source code for you.
    • Direct upload: Upload your source files directly into the GitHub repository.
    • VS Code: Clone the repository and add your source files using VS Code (optionally using the AL:Go extension in VS Code).

  6. Maintain AL-Go for GitHub versioning

    main

    Microsoft recommends always running the latest version of AL-Go for GitHub.

    Old versions may stop working at any time because they rely on older, unsupported versions of GitHub Actions. These dependencies may be removed or fail due to unresolved dependencies on GitHub runners. Fixes are generally only provided in preview versions or subsequent official releases.

  7. Customizing AL-Go for GitHub

    main

    AL-Go for GitHub is designed as a plug-and-play DevOps solution for Microsoft Dynamics 365 Business Central. While it supports most standard needs out-of-the-box, you can customize it if the default functionality does not match your requirements.

    Important Guidelines:

    • Feature Suggestions: Before customizing, check if your requirement should be a core feature by creating a feature suggestion.
    • Update Risk: If you modify AL-Go System Files (scripts and workflows) using methods other than the official customization guidelines, your changes will be removed during the next AL-Go update.
    • Maintenance: The more you customize the system, the higher the risk that future AL-Go updates will break your customizations, requiring manual updates to your custom code.

  8. Define custom build modes

    main
    Starting in version 5.0, you can define custom build modes in addition to the default Default, Translated, and Clean modes. Custom build modes allow you to define unique ways to build your apps. By default, a custom build mode behaves like the Default mode unless you override it using script overrides in your repository.

  9. Pull Power Platform changes action

    main

    The Pull Power Platform changes action retrieves the latest changes from your Power Platform development environment and brings them into your repository.

    Key details for users:

    • Publishing Requirement: Changes must be published in the Power Platform environment before they can be included via the Pull action.
    • Conflict Management: Most Power App source files contain state information and are generally safe to overwrite in case of conflicts.
    • Reviewing Changes: It is recommended to review the connection files and the YAML files under Srs specifically when reviewing pulled changes.

  10. Understanding GitHub Personal vs. Organizational accounts for AL-Go

    main

    When setting up AL-Go, it is important to distinguish between Personal and Organizational accounts to manage code ownership and collaboration correctly.

    Personal Accounts

    • Purpose: Acts as your individual identity and a sandbox for your work.
    • Usage: Use this for private or public repositories that are not production code.
    • Limits: Free tier provides 2,000 GitHub Actions execution minutes per month.

    Organizational Accounts

    • Purpose: Enhances collaboration and serves as the home for production code.
    • Usage:
      • ISVs (AppSource apps): Should place apps in repositories within an organization (likely a Teams account).
      • VARs (Per Tenant Extensions): Should place extensions in an organization owned by the customer, with the partner added as a collaborator.
    • Benefits:
      • Code Ownership: The organization owner owns the code.
      • Shared Resources: Allows sharing of secrets, GitHub runners, and access tokens across repositories.
      • Shared Runners: Runners defined at the organization level can be used by all repositories.
      • Shared Secrets: Teams or Enterprise accounts can create organization-level secrets for use in repositories.
      • Shared Billing: Costs are billed to the organization rather than a personal plan.

  11. How DeliveryTargets work in AL-Go

    main

    DeliveryTargets define where and how built Business Central applications are distributed after a successful build. AL-Go uses three components to manage a target:

    1. Context Secret: A secret named <DeliveryTarget>Context (e.g., GitHubPackagesContext) containing connection credentials.
    2. Delivery Script: An optional PowerShell script named DeliverTo<DeliveryTarget>.ps1 located in the .github folder for custom logic.
    3. Settings: Optional configuration within AL-Go settings files to control behavior like branch filtering.

    Supported targets include:

    • GitHubPackages: GitHub Packages NuGet feed (Experimental)
    • NuGet: Custom NuGet feed (Experimental)
    • Storage: Azure Storage Account (Stable)
    • AppSource: Microsoft AppSource (Stable)

  12. Understand AppSource Delivery and Preview modes

    main

    Continuous Delivery (CD)

    If continuousDelivery is set to true in your deliverToAppSource configuration, every app build will be automatically delivered to AppSource. The app will undergo validation and become available in AppSource as a Preview.

    Moving to Production

    To move an app from Preview to Production, you must either:

    1. Press Go Live in the Partner Center.
    2. Run the Publish To AppSource workflow manually in AL-Go for GitHub.