A self-hosted NuGet feed service for Business Central apps. Fork this repository and deploy it to your own Azure subscription directly from your fork — no separate deployment repository needed.
The service consists of:
- An Azure Function (.NET 10 isolated, Flex Consumption) hosting the endpoints
- A Storage Account where packages are stored in a NuGet-friendly folder structure
- A User-Assigned Managed Identity granting the function access to the storage account
All apps are uploaded once and served through three read-only NuGet v3 feeds:
| Feed | Service index URL | Content |
|---|---|---|
apps |
https://<functionapp>.azurewebsites.net/api/apps/index.json |
Full .app files |
runtime |
https://<functionapp>.azurewebsites.net/api/runtime/index.json |
Runtime packages, compiled per supported Business Central version by a GitHub workflow |
symbols |
https://<functionapp>.azurewebsites.net/api/symbols/index.json |
Symbols-only packages (created with altool during upload) |
Each feed implements the NuGet v3 resources needed by BcContainerHelper's NuGet search functionality:
- Service index —
GET api/{feed}/index.json - SearchQueryService —
GET api/{feed}/query?q=<query>&skip=<n>&take=<n> - PackageBaseAddress (flat container) —
GET api/{feed}/package/{id}/index.json(version list)GET api/{feed}/package/{id}/{version}/{id}.{version}.nupkg(download)
- Direct .app download —
GET api/{feed}/download/{id}/{version}returns the raw.appfor that flavor.{version}may belatest. These are stable, non-expiring URLs (anonymous for public feeds). - Logo —
GET api/logo/{id}(orapi/logo/{id}/{version}) returns the app logo extracted from the.appon upload. - NuGet push —
PUT api/{feed}/api/v2/packagestores a prebuilt.nupkgverbatim into the feed (standard NuGet push, requires a write or readwrite access key for that feed). This is how the runtime workflow publishes compiled packages; the upload endpoint below is the path that converts.appfiles into packages.
To publish Business Central apps, use the upload endpoint (it does the .app → package conversion):
- Upload —
POST api/upload(requires a Microsoft Entra bearer token via theAuthorization: Bearerheader). Accepts a raw.appfile body ormultipart/form-datawith one or more.appfiles (Business Central apps). Files posted under thedependenciesform field (.appfiles or a.zip) are stored as the app's compilation dependencies — they're not published as packages, but are kept per app+version and passed to the runtime workflow so runtime packages can be (re)generated for new Business Central versions. Optional query parameters control runtime package generation for the uploaded app(s):country(defaultw1),additionalCountries(comma-separated), andartifactType(sandboxoronprem, defaultsandbox). - Remove —
DELETE api/packages/{appId}(requires a Microsoft Entra bearer token) removes every package for an app id across all feeds: the full app, the symbols package, and the runtime indirect + compiled packages. Pass*(orall) as the app id to remove every package. Aversionquery parameter (default*= all versions) narrows deletion to a single app version, which also removes every compiled runtime package generated for that version. Also available as theRemove Packagesworkflow (dispatch with an app id and optional version; authenticates via OIDC).
Uploaded apps are processed with the AL development tools (altool, bundled with the deployment): the manifest (id, name, publisher, version, dependencies) is extracted, a symbols-only package is created for the symbols feed, and everything is wrapped as NuGet packages with dependency information and stored under {feed}/{packageId}/{version}/ in the packages blob container.
Each feed is either public (anonymous read access) or private (requires an access key). Which feeds are public is controlled by the PUBLIC_FEEDS repository variable; all feeds are private by default.
Package metadata (service index, search, version lists, nuspec and logo) is served anonymously as soon as at least one feed is public \u2014 only the package/app content downloads (.nupkg files and the api/{feed}/download/... .app endpoint) remain gated per feed. If no feed is public, metadata also requires an access key, so a fully private deployment exposes nothing anonymously.
Access keys are managed through Entra-protected endpoints (also usable by allow-listed GitHub users via the token management web app):
| Endpoint | Description |
|---|---|
GET api/accesskeys |
List every access key |
GET api/accesskeys/{name} |
Get an access key (name, key, feeds, type, description, e-mail and expiry) |
POST api/accesskeys/{name} |
Create an access key. Body: { "feeds": ["apps", "runtime", "symbols"], "type": "read", "description": "who it is for", "email": "notify@example.com", "expiresInDays": 90 }. email is required (used to notify when the key changes); type (read, write or readwrite, default read), description and expiresInDays are optional. The name is at most 64 characters (letters, digits, ., -, _), description at most 200 and e-mail at most 200. Returns the generated key |
POST api/accesskeys/{name}/revoke |
Revoke a key (expire it immediately, keeping the record) |
POST api/accesskeys/{name}/renew |
Renew a key. Optional body { "expiresInDays": 90 }; omit for no expiry |
POST api/accesskeys/{name}/rotate |
Rotate a key: issue a new active key under the same name and keep the previous key value valid for a grace period. Body { "oldKeyValidDays": 7 } |
POST api/accesskeys/rotate-all |
Rotate every active key (skips expired/revoked and ephemeral keys). Body { "oldKeyValidDays": 7 } |
DELETE api/accesskeys/{name} |
Remove an access key permanently |
POST api/token |
Issue short-lived feed tokens (a read token for apps and a readwrite token for runtime). Used by the runtime workflow, which authenticates with a Microsoft Entra token obtained via GitHub OIDC — so no long-lived credential is passed at dispatch |
Each key has a type: read keys grant read access to their feeds, write keys can push packages (PUT api/{feed}/api/v2/package) to their feeds, and readwrite keys can do both. A read key can never push, so keys handed to consumers cannot publish. (The upload endpoint that converts .app files is separate and always requires a Microsoft Entra token.)
$token = az account get-access-token --resource https://management.core.windows.net/ --query accessToken -o tsv
Invoke-RestMethod `
-Method Post `
-Uri "https://<functionapp>.azurewebsites.net/api/accesskeys/partner1" `
-Headers @{ Authorization = "Bearer $token" } `
-Body '{ "feeds": ["apps", "symbols"], "type": "read" }' `
-ContentType "application/json"Keys are stored in a private blob (config/accesskeys.json) that is managed exclusively by these endpoints — do not edit it manually. The registry is loaded into memory at startup and kept in memory for the lifetime of the function app.
When accessing a private feed, clients pass the key as basic auth password, Authorization: Bearer header, X-NuGet-ApiKey header, or ?token= query parameter.
$feedUrl = "https://<functionapp>.azurewebsites.net/api/apps/index.json"
Get-BcNuGetPackage -nuGetServerUrl $feedUrl -packageName "<publisher>.<appname>" -select ExactOr register as a trusted feed (use the access key as token for private feeds):
$bcContainerHelperConfig.TrustedNuGetFeeds = @(
@{ "Url" = "https://<functionapp>.azurewebsites.net/api/apps/index.json"; "Token" = "<access key>" }
)$token = az account get-access-token --resource https://management.core.windows.net/ --query accessToken -o tsv
Invoke-RestMethod `
-Method Post `
-Uri "https://<functionapp>.azurewebsites.net/api/upload" `
-Headers @{ Authorization = "Bearer $token" } `
-InFile ".\MyApp_1.0.0.0.app" `
-ContentType "application/octet-stream"Deployment runs entirely from your fork using GitHub Actions and Bicep. The templates live in bicep/. There is no Terraform state to manage: az deployment reconciles against the live resources in your subscription, applying only the differences on each run (ARM incremental mode). Removing a resource from a template does not delete it — delete such resources manually.
The deploy workflow authenticates with a user-assigned managed identity using GitHub OIDC federation — no app registration and no stored credentials. This identity (and the resource group) must exist before the workflow can run, so it is created once locally with your own credentials via bicep/bootstrap.bicep. All roles are scoped to the deployment resource group only.
$repo = "<owner/repo>" # Owner and repo of BcNuGetHelper fork
$location = "<azure location>" # e.g. westeurope
$baseName = "<base name>" # e.g. nghfreddydk (3-17 lowercase letters/digits, globally unique)
$rg = "$($baseName)-rg" # e.g. nghfreddydk-rg
$subscription = az account show --query id -o tsv # subscription ID
# OIDC subjects. GitHub is rolling out a claim format that embeds account and repository IDs,
# so register both the classic and the ID-based subject.
$repoInfo = Invoke-RestMethod "https://api.github.com/repos/$repo"
$subjectClassic = "repo:$($repo):ref:refs/heads/main"
$subjectWithIds = "repo:$($repoInfo.owner.login)@$($repoInfo.owner.id)/$($repoInfo.name)@$($repoInfo.id):ref:refs/heads/main"
# Verify the base name is available before creating anything
if ((az storage account check-name --name $baseName --query nameAvailable -o tsv) -ne "true") {
throw "Storage account name '$baseName' is not available - choose another base name"
}
$body = '{"name": "' + $baseName + '-func", "type": "Microsoft.Web/sites"}'
if ((az rest --method post --url "https://management.azure.com/subscriptions/$subscription/providers/Microsoft.Web/checknameavailability?api-version=2023-12-01" --body $body --query nameAvailable -o tsv) -ne "true") {
throw "Function app name '$($baseName)-func' is not available - choose another base name"
}
# Create the resource group, the deploy identity, its federated credentials and role assignments
$deploy = az deployment sub create `
--location $location `
--template-file bicep/bootstrap.bicep `
--parameters baseName=$baseName location=$location resourceGroupName=$rg `
githubSubjectClassic=$subjectClassic githubSubjectWithIds=$subjectWithIds `
--query properties.outputs -o json | ConvertFrom-Json
# Configure the repository secrets and variables (requires gh auth login)
$tenantId = az account show --query tenantId -o tsv
gh secret set AZURE_CLIENT_ID --repo $repo --body $deploy.deployClientId.value
gh secret set AZURE_TENANT_ID --repo $repo --body $tenantId
gh secret set AZURE_SUBSCRIPTION_ID --repo $repo --body $subscription
gh variable set BASE_NAME --repo $repo --body $baseName
gh variable set AZURE_LOCATION --repo $repo --body $location
gh variable set RESOURCE_GROUP_NAME --repo $repo --body $rg
# Optional: feeds served without authentication
# gh variable set PUBLIC_FEEDS --repo $repo --body "apps,runtime,symbols"
# Optional: also allow extra client/application ids to call the admin endpoints
# (the deploy identity is always allowed; this appends to the allow-list)
# gh variable set ADMIN_CLIENT_ID --repo $repo --body "<client-id>"
# Optional: GitHub logins allowed to use the token-management web app
# gh variable set WEBAPPUSERS --repo $repo --body "octocat,another-user"Roles granted to the deploy identity: Contributor (create resources), Role Based Access Control Administrator (create the role assignment for the function's managed identity) and Storage Blob Data Contributor (function content deployment to the deployments container).
Two federated credentials are registered because GitHub is rolling out a new OIDC subject claim format that embeds account and repository IDs (
repo:owner@id/repo@id:...). Registering both the classic and the ID-based subject makes login work either way. If login still fails withAADSTS700213, copy the exact "subject claim" shown in the failed Azure login step into a federated credential.
All settings are configured as repository secrets and variables (Settings → Secrets and variables → Actions). The script in step 2 sets them all via the GitHub CLI; the tables below describe them for reference.
| Secret | Required | Description |
|---|---|---|
AZURE_CLIENT_ID |
Yes | Client id of the managed identity created above (az identity show --name github-deploy --resource-group $rg --query clientId -o tsv) |
AZURE_TENANT_ID |
Yes | Your Entra ID tenant id |
AZURE_SUBSCRIPTION_ID |
Yes | The Azure subscription to deploy to |
GH_APP_PRIVATE_KEY |
No | PEM private key of the GitHub App used to dispatch the runtime workflow (see Runtime package generation). Stored as a Function App setting |
SMTP_PASSWORD |
No | SMTP password for access-key change e-mail notifications. The rest of the SMTP config is set as variables (below) |
| Variable | Required | Default | Description |
|---|---|---|---|
BASE_NAME |
Yes | — | Base name for all Azure resources. Lowercase letters and digits only, 3–17 characters, globally unique (used for storage account names). Example: mybcnuget |
AZURE_LOCATION |
Yes | — | Azure region to deploy to |
RESOURCE_GROUP_NAME |
No | <BASE_NAME>-rg |
Name of the resource group (must match the one created in step 2) |
PUBLIC_FEEDS |
No | (empty — all feeds private) | Comma-separated list of feeds served without authentication, e.g. apps,runtime,symbols |
SMTP_HOST |
No | (empty — notifications off) | SMTP server host for access-key change e-mail notifications |
SMTP_PORT |
No | — | SMTP port (e.g. 587 for STARTTLS) |
SMTP_USERNAME |
No | — | SMTP username |
SMTP_FROM |
No | — | From address for notification e-mails (e.g. nuget@example.com) |
SMTP_FROM_NAME |
No | (the SMTP_FROM address) |
Display name shown as the e-mail sender (e.g. Contoso) and used for the {{sender}} sign-off |
ADMIN_CLIENT_ID |
No | (deploy identity AZURE_CLIENT_ID) |
Restricts the admin endpoints (upload, access keys, token, remove, regenerate) to specific client/application ids. The deploy workflow always locks these to the deploy identity, so only the OIDC workflow can call them. Set this variable to a comma-separated list of extra client ids to additionally allow other callers (the deploy identity stays allowed) |
GH_APP_CLIENT_ID |
No | (empty — runtime generation disabled) | Client id of the GitHub App used to dispatch the runtime workflow |
GH_APP_INSTALLATION_ID |
No | — | Installation id of that GitHub App on this repository |
WEBAPPUSERS |
No | (empty — web app disabled) | Comma-separated list of GitHub logins allowed to sign in to the token-management web app. When empty, no one can use the web app |
Run the Deploy workflow manually (Actions → Deploy → Run workflow). The workflow:
- Logs in to Azure using OIDC (no stored credentials)
- Deploys
bicep/main.bicepto the resource group (az deployment group create, incremental) to create/update all resources - Builds the .NET 10 function app and deploys it
| Resource | Name |
|---|---|
| Resource group | <RESOURCE_GROUP_NAME> |
| Storage account (packages + deployments) | <BASE_NAME> |
| User-assigned managed identity | <BASE_NAME>-id |
| App Service plan (Flex Consumption) | <BASE_NAME>-plan |
| Function app | <BASE_NAME>-func |
| Application Insights + Log Analytics | <BASE_NAME>-ai / <BASE_NAME>-log |
A browser-based app for managing feed access keys is served by the function app at
https://<BASE_NAME>-func.azurewebsites.net/api/app/. The Deploy Function App workflow prints
this link and a scannable QR code to its run summary once deployment succeeds.
Sign-in uses GitHub. Access is restricted to the logins listed in the WEBAPPUSERS repository
variable — everyone else is refused after signing in. Two sign-in methods are supported:
- Sign in with GitHub (device flow) — available when the runtime GitHub App is configured
(
GH_APP_CLIENT_ID) with Device Flow enabled (see Runtime package generation). The web app reuses that app's client id; the flow is proxied through the backend (api/auth/device/code,api/auth/device/token) so no client secret is needed. - Personal access token — paste a GitHub token with the
read:userscope. Always available as a fallback.
Once signed in, allowed users can:
- Add an access key with a name, a required contact e-mail (used to notify the recipient when the
key changes), a description (who/what it is for), a set of feeds (
apps,runtime,symbols, or all), an access level (read,write,readwrite) and an optional expiry. - Revoke a key (expires it immediately but keeps the record).
- Renew a key. For a revoked or expiring key this extends (or clears) its expiry. For an active key the button is labelled Rotate: a new key value is issued immediately and the previous value keeps working for a grace period you choose (in days), so consumers can switch over without downtime. Rotate all does the same for every active key at once.
- Remove a key permanently.
The same operations are available on the access key endpoints using a Microsoft Entra token, for automation.
When SMTP is configured, the service e-mails the key's contact address on key changes:
- Created, Revoked and Renewed — always.
- Rotated — when an active key is renewed/rotated; the e-mail states how long the old key stays valid.
- Deleted — only if the key was still active. A key that was already revoked/expired doesn't send a second notice.
Notifications are enabled only when all SMTP settings are configured — the SMTP_HOST, SMTP_PORT,
SMTP_USERNAME and SMTP_FROM variables and the SMTP_PASSWORD secret. If any is missing, key
changes still work but no e-mail is sent. Sending uses STARTTLS, and e-mail failures are logged
without blocking the operation.
The messages come from the email-templates/ folder — one HTML file per event
(created.html, revoked.html,
renewed.html, rotated.html,
deleted.html). Each file's subject is taken from a leading
<!-- subject: ... --> comment and the rest is the HTML body. Bodies support the customer-facing
placeholders {{feeds}}, {{feedurls}} (feed names with their index.json links, used in
created.html/rotated.html), {{type}} (access level), {{key}} (the access key), {{expires}},
{{email}}, {{sender}} (the sign-off name — Smtp__FromName if set, otherwise the SMTP_FROM
address) and, in rotated.html, {{oldkeydays}} (grace days the old key stays valid). Values are
HTML-encoded, and the internal key name and description are intentionally not available. Customize
the notifications by editing these files in your fork.
Runtime packages contain the app compiled against a specific Business Central version, and one
must be produced for every supported minor version the app targets. That compilation needs a
Business Central container on a Windows build agent, which the function app cannot do itself.
Instead, after an app is uploaded the function app dispatches the
Generate Runtime NuGet Packages workflow, which
compiles the runtime packages (via BcContainerHelper)
and pushes them back to the runtime feed through the NuGet push endpoint.
The localizations and artifact type to compile for are per app, passed as query parameters on
the upload request (country, additionalCountries, artifactType) rather than as deployment
settings. The set of Business Central versions is determined automatically from the app's
application dependency (every supported minor version at or above it).
The dispatch only passes the backend URL (and tokenless download URLs) — no feed credential.
The workflow logs in to Azure with the existing deploy identity via GitHub OIDC, then calls
POST api/token to obtain short-lived feed tokens (read for apps, read/write for runtime).
So the credential that can push packages is never stored or passed at dispatch; it is minted per
run and expires. Because api/token is an admin endpoint, the deploy workflow locks the admin
endpoints to the deploy identity by default (ADMIN_CLIENT_ID defaults to AZURE_CLIENT_ID), so
only the OIDC workflow can request feed tokens. Override the ADMIN_CLIENT_ID variable to widen
that allow-list.
To dispatch a workflow securely — without a user-bound Personal Access Token — the function app authenticates as a GitHub App. To enable runtime generation:
- Create a GitHub App (Settings → Developer settings → GitHub Apps → New). Grant repository permissions Actions: Read and write (to dispatch the workflow) and Metadata: Read-only (mandatory). No other permissions are needed. Generate a private key (PEM) and note the Client ID.
- Install the app on your fork and note the Installation ID (the number at the end of the installation settings URL).
- Set the repository variables
GH_APP_CLIENT_IDandGH_APP_INSTALLATION_ID, and the secretGH_APP_PRIVATE_KEY(see the tables above). The private key is stored as a Function App setting (GitHubApp__PrivateKey) — encrypted at rest by Azure, but readable by anyone with config-read access to the app. - No extra OIDC setup is needed — the workflow reuses the deploy identity and the existing
AZURE_CLIENT_ID/AZURE_TENANT_ID/AZURE_SUBSCRIPTION_IDsecrets. The admin endpoints are locked to that identity by default (seeADMIN_CLIENT_IDabove), so the workflow can callPOST api/tokenout of the box; only overrideADMIN_CLIENT_IDif you need to allow other callers. - Make sure Actions are enabled on your fork (GitHub disables them on new forks by default), otherwise the dispatched workflow won't run.
When these settings are absent the upload still succeeds; only the runtime workflow dispatch is skipped.
The same GitHub App also powers the token-management web app sign-in —
no separate OAuth App or setting is needed. To enable the Sign in with GitHub button there, open
the app (Settings → Developer settings → GitHub Apps → your app → General) and tick Enable Device
Flow, then save. The web app automatically uses the same GH_APP_CLIENT_ID. Signing in needs no
extra permissions — it only reads the user's login to check it against WEBAPPUSERS.
The device flow returns a GitHub user access token. If the app has Expire user authorization tokens enabled (the default for new apps), that token lasts about 8 hours, after which web-app users are returned to the sign-in screen and must authorize again. Turn that setting off if you want longer-lived sessions. Personal-access-token sign-in always works regardless of this setting, so enabling device flow is optional.
Runtime packages are per BC minor version, so new versions ship over time. The stored .app and
its dependency artifact let the packages be regenerated without re-uploading. The
Regenerate Runtime Packages workflow runs weekly (and
on demand); it authenticates via OIDC and calls POST api/regenerate, which re-dispatches the
runtime workflow for the stored apps. The runtime workflow only builds versions that are missing, so
re-running is cheap when nothing new has shipped. By default it targets the latest version of each
app; dispatch with allVersions: true (or POST api/regenerate?allVersions=true) to cover every
stored version.
Requirements: .NET 10 SDK, Azure Functions Core Tools v4, Azurite.
cd BcNuGetHelper
func startWithout a PackagesStorageAccountName setting the app falls back to the local Azurite emulator (UseDevelopmentStorage=true).
A static, brandable catalog website can be published to GitHub Pages. It lists every app that is available on a public feed and, per app, shows the logo, description and dependencies (from the latest version) plus a table of all versions with direct download links for each public feed flavor (Full app / Runtime / Symbols).
Because browser downloads only work for public feeds, the site lists apps only when at least one feed is public (PUBLIC_FEEDS). If no feed is public, only the branded front page is rendered. The build reads metadata anonymously from the public feeds — no credentials are used.
To enable it:
- In your fork, go to Settings → Pages and set Source to GitHub Actions.
- Set the
PUBLIC_FEEDSvariable to the feeds you want to expose (e.g.apps,runtime,symbols). - Re-brand the site by editing
site/branding.json(see below) so it shows your company instead of the defaults. - Run the Deploy Pages workflow (Actions → Deploy Pages → Run workflow).
Edit site/branding.json (company name, tagline, colors, logo, favicon, footer, links) and drop your own files in site/assets/:
logo.svg— header/app logofavicon.svg— browser iconcustom.css— appended after the generated theme, so any rule you add wins
logo and favicon may also be absolute URLs (https://…), in which case they're used as-is instead of being loaded from assets/.
Set "showNupkg": false in site/branding.json to hide the .nupkg download buttons and show only .app (default is true).
Instead of editing the file, you can set a repository variable named BRANDING to the raw branding JSON; when present it overrides site/branding.json. This is handy for keeping branding in repository settings rather than in the fork's source.
Build it locally to preview:
./site/Build-Site.ps1 -BaseUrl "https://<functionapp>.azurewebsites.net" -PublicFeeds "apps,runtime,symbols"
# open ./_site/index.html.github/workflows/deploy.yml Full deployment (Bicep + function app)
.github/workflows/deploy-function.yml Function app only (manual trigger)
.github/workflows/deploy-pages.yml Build & publish the catalog website to GitHub Pages
.github/workflows/generate-runtime-nuget.yml Compile & publish runtime packages (dispatched on upload)
.github/workflows/retry-runtime.yml Re-run failed runtime jobs on fresh runners (up to 3 attempts)
.github/workflows/regenerate-runtime.yml Re-dispatch runtime generation for new BC versions (scheduled)
.github/workflows/remove-packages.yml Remove packages for an app id (or all) from every feed
.github/workflows/test.yml End-to-end tests against the deployed service
.github/actions/fetch-feed-tokens/ Composite action: OIDC login + short-lived feed tokens
.github/scripts/runtime/ Runtime-package generation scripts (BcContainerHelper)
bicep/ Bicep templates (bootstrap + main infrastructure)
BcNuGetHelper/ Azure Function app (.NET 10 isolated)
webapp/ Token-management web app (React + Vite, served at /api/app)
email-templates/ Notification e-mail templates (one HTML file per event)
site/ Static catalog website (generator + branding)
tests/ Test scripts