Skip to content

Your first GitHub Actions workflow (v3)

This is the headline onboarding page for the ALOps v3 GitHub Preview launch. It takes you from zero to a working Business Central build workflow on GitHub Actions.

If you're new to GitHub Actions itself, GitHub's quickstart is a good 10-minute primer first.

What you'll need

  • A GitHub repository containing your AL extension.
  • A runner that can execute Windows-class tasks. The AL compiler and many BC operations need a Windows runtime, so the typical setup is one of:
    • A self-hosted Windows runner (recommended — full control over BC service tier, Docker, persisted symbol cache).
    • A windows-latest GitHub-hosted runner (works for compile-only workflows; no persistent BC service tier).
  • An ALOps license. If you don't have one yet, see the License page.

Configure your license

GitHub Actions reads the license from an environment variable named alops-licenseid (or ALOPS_LICENSEID — both are accepted).

The cleanest setup is to add a repository secret:

  1. In your repo, go to Settings → Secrets and variables → Actions.
  2. Click New repository secret.
  3. Name: ALOPS_LICENSEID. Value: the License Key from your ALOps invoice.

You'll reference the secret in your workflow's env: block. The full setup, including organization-level secrets and Azure Key Vault patterns, is on the License page.

Minimum viable workflow

Create .github/workflows/bc-build.yml:

name: BC Build

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: windows-latest        # or [self-hosted, windows]

    env:
      ALOPS_LICENSEID: ${{ secrets.ALOPS_LICENSEID }}

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Diagnose the build agent
        uses: HodorNV/ALOps-V3/alops-info@v3   # <!-- TODO: confirm action repo path -->
        with:
          free_mem_threshold: '20'
          free_mem_threshold_action: 'Warn'
          docker_containers_action: 'Ignore'

      - name: Compile the AL extension
        uses: HodorNV/ALOps-V3/alops-appcompiler@v3   # <!-- TODO: confirm action repo path -->
        with:
          altool_package_version: '17.0.30.49729-beta'
          compilation_mode: 'Serial'
          alsourcepath: ${{ github.workspace }}
          appversiontemplate: '1.0.${{ github.run_number }}.0'
          updatebuildnumber: 'true'

      - name: Upload the .app artifact
        uses: actions/upload-artifact@v4
        with:
          name: app
          path: '**/*.app'

What this workflow does:

  1. Checkout — actions/checkout@v4 pulls your repo onto the runner.
  2. alops-info — runs a diagnostic report on the runner: CPU, memory, disk, .NET versions, Docker status, BC application versions discovered. Warns if free memory is under 20%. A useful smoke-test at the top of every workflow.
  3. alops-appcompiler — downloads the altool.exe NuGet package, resolves your app's symbols, and compiles every app.json it finds under alsourcepath. The version template 1.0.${{ github.run_number }}.0 ties the app version to the GitHub run number.
  4. actions/upload-artifact — attaches every compiled .app to the workflow run.

Run it

Commit and push. GitHub picks it up, runs the workflow on the next push or pull request, and the result is on the Actions tab.

Self-hosted vs hosted runners

Concern windows-latest (hosted) Self-hosted Windows
BC service tier Not pre-installed; container-per-run only Persisted across runs
Docker Available, but cold-cache every run Image cache persists
Compile time (medium app) ~2–4 min ~30–90 s
Symbol cache Lost between runs Persisted on disk
Cost Per-minute billing on private repos Your own hardware
Setup Zero One-time runner registration

Compile-only workflows are fine on windows-latest. Anything that publishes to a service tier or runs tests against BC will be much faster on a self-hosted runner.

Next steps

  • Publish to a service tier — add an alops-apppublish step to install the compiled .app into a running BC instance. See the v3 build steps catalog.
  • Use Docker for ephemeral environments — alops-dockercreate + alops-dockerstart spin up a containerized BC service tier per workflow run.
  • Hand-crafted starters — see Examples → v3 — GitHub Actions for ready-to-copy workflows.