Skip to content

Commit c0591a5

Browse files
Copilotmazhelez
Copilot
and
mazhelez
committed
Add comprehensive DeliveryTargets documentation and update existing references
Co-authored-by: mazhelez <[email protected]>
1 parent a654528 commit c0591a5

File tree

3 files changed

+330
-1
lines changed

3 files changed

+330
-1
lines changed

‎README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@ Try out the [AL-Go workshop](https://aka.ms/algoworkshop) for an in-depth worksh
3636
1. [Enable KeyVault access for your AppSource App during development and/or tests](Scenarios/EnableKeyVaultForAppSourceApp.md)
3737
1. [Set up your own GitHub runner to increase build performance](Scenarios/SelfHostedGitHubRunner.md)
3838
1. [Introducing a dependency to another GitHub repository](Scenarios/AppDependencies.md)
39+
1. [DeliveryTargets and NuGet/GitHub Packages](Scenarios/DeliveryTargets.md)
3940
1. [Enabling Telemetry for AL-Go workflows and actions](Scenarios/EnablingTelemetry.md)
4041
1. [Add a performance test app to an existing project](Scenarios/AddAPerformanceTestApp.md)
4142
1. [Publish your app to AppSource](Scenarios/PublishToAppSource.md)

‎Scenarios/DeliveryTargets.md

Lines changed: 306 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,306 @@
1+
# DeliveryTargets and NuGet/GitHub Packages in AL-Go
2+
3+
AL-Go for GitHub supports continuous delivery to multiple targets, including NuGet feeds and GitHub Packages. This document provides comprehensive guidance on how to set up and configure delivery targets for your Business Central apps, particularly focusing on Per-Tenant Extensions (PTEs).
4+
5+
## Table of Contents
6+
7+
- [Overview](#overview)
8+
- [DeliveryTargets Concept](#deliverytargets-concept)
9+
- [GitHub Packages Setup](#github-packages-setup)
10+
- [NuGet Feed Setup](#nuget-feed-setup)
11+
- [Configuration Examples](#configuration-examples)
12+
- [Troubleshooting](#troubleshooting)
13+
- [Advanced Scenarios](#advanced-scenarios)
14+
- [Important Notes](#important-notes)
15+
16+
## Overview
17+
18+
AL-Go for GitHub provides experimental support for delivering your Business Central apps to NuGet feeds and GitHub Packages. This enables you to:
19+
20+
- **Automate app distribution**: Automatically publish your apps to package repositories after successful builds
21+
- **Manage dependencies**: Use published packages as dependencies in other projects
22+
- **Enable partner collaboration**: Share your apps with partners through package feeds
23+
- **Implement CI/CD best practices**: Integrate package delivery into your continuous integration pipeline
24+
25+
> [!IMPORTANT]
26+
> **Experimental Feature**: NuGet and GitHub Packages delivery is currently experimental. While the functionality is stable and has been used in production by several partners, the package structure and configuration options may change in future versions.
27+
28+
## DeliveryTargets Concept
29+
30+
DeliveryTargets in AL-Go define where and how your built applications should be delivered after a successful build. Each delivery target is configured through:
31+
32+
1. **Context Secret**: A secret named `<DeliveryTarget>Context` containing connection information
33+
2. **Delivery Script**: An optional PowerShell script named `DeliverTo<DeliveryTarget>.ps1` for custom delivery logic
34+
3. **Settings**: Optional configuration in AL-Go settings files
35+
36+
### Supported Delivery Targets
37+
38+
| Target | Purpose | Context Secret | Status |
39+
|--------|---------|----------------|--------|
40+
| GitHubPackages | GitHub Packages NuGet feed | `GitHubPackagesContext` | ✅ Experimental |
41+
| NuGet | Custom NuGet feed | `NuGetContext` | ✅ Experimental |
42+
| Storage | Azure Storage Account | `StorageContext` | ✅ Stable |
43+
| AppSource | Microsoft AppSource | `AppSourceContext` | ✅ Stable |
44+
45+
## GitHub Packages Setup
46+
47+
GitHub Packages provides a free NuGet feed for each GitHub organization. This is the recommended approach for most scenarios.
48+
49+
### Step 1: Create Personal Access Token
50+
51+
1. Navigate to [GitHub Personal Access Tokens](https://github.com/settings/tokens/new)
52+
2. Create a **Classic Personal Access Token** (Fine-grained tokens don't support packages yet)
53+
3. Select the following scopes:
54+
- `write:packages` - Required for publishing packages
55+
- `read:packages` - Required for consuming packages
56+
- `repo` - Required if your repositories are private
57+
58+
### Step 2: Create GitHubPackagesContext Secret
59+
60+
Create an organizational secret named `GitHubPackagesContext` with the following compressed JSON format:
61+
62+
```json
63+
{"token":"ghp_YOUR_TOKEN_HERE","serverUrl":"https://nuget.pkg.github.com/YOUR_ORG/index.json"}
64+
```
65+
66+
Replace:
67+
- `YOUR_TOKEN_HERE` with your personal access token
68+
- `YOUR_ORG` with your GitHub organization name
69+
70+
> [!TIP]
71+
> Use the BcContainerHelper function `New-ALGoNuGetContext` to create a correctly formatted JSON structure.
72+
73+
### Step 3: Configure Repository Settings (Optional)
74+
75+
You can control delivery behavior by adding settings to your AL-Go settings file:
76+
77+
```json
78+
{
79+
"DeliverToGitHubPackages": {
80+
"ContinuousDelivery": true,
81+
"Branches": ["main", "release/*"]
82+
}
83+
}
84+
```
85+
86+
### Step 4: Verify Setup
87+
88+
After creating the secret, run your CI/CD workflow. You should see a "Deliver to GitHubPackages" job in the workflow summary.
89+
90+
## NuGet Feed Setup
91+
92+
For custom NuGet feeds (e.g., Azure DevOps Artifacts, private NuGet servers), use the NuGetContext secret.
93+
94+
### Step 1: Create NuGetContext Secret
95+
96+
Create a secret named `NuGetContext` with the following format:
97+
98+
```json
99+
{"token":"YOUR_NUGET_TOKEN","serverUrl":"https://pkgs.dev.azure.com/YOUR_ORG/YOUR_PROJECT/_packaging/YOUR_FEED/nuget/v3/index.json"}
100+
```
101+
102+
Common NuGet feed URLs:
103+
- **Azure DevOps**: `https://pkgs.dev.azure.com/{org}/{project}/_packaging/{feedName}/nuget/v3/index.json`
104+
- **GitHub Packages**: `https://nuget.pkg.github.com/{org}/index.json`
105+
- **NuGet.org**: `https://api.nuget.org/v3/index.json`
106+
107+
### Step 2: Configure Dependency Resolution (Optional)
108+
109+
Unlike GitHub Packages, NuGet feeds configured with `NuGetContext` are not automatically used for dependency resolution. To use your custom feed for dependencies, add it to `trustedNuGetFeeds`:
110+
111+
```json
112+
{
113+
"trustedNuGetFeeds": [
114+
{
115+
"url": "https://pkgs.dev.azure.com/YOUR_ORG/YOUR_PROJECT/_packaging/YOUR_FEED/nuget/v3/index.json",
116+
"authTokenSecret": "NuGetContext",
117+
"patterns": ["*"]
118+
}
119+
]
120+
}
121+
```
122+
123+
## Configuration Examples
124+
125+
### Example 1: GitHub Packages for Organization
126+
127+
**Organizational Secret**: `GitHubPackagesContext`
128+
```json
129+
{"token":"ghp_1234567890abcdef","serverUrl":"https://nuget.pkg.github.com/contoso/index.json"}
130+
```
131+
132+
**AL-Go-Settings.json** (optional):
133+
```json
134+
{
135+
"DeliverToGitHubPackages": {
136+
"ContinuousDelivery": true,
137+
"Branches": ["main"]
138+
}
139+
}
140+
```
141+
142+
### Example 2: Azure DevOps Artifacts
143+
144+
**Repository Secret**: `NuGetContext`
145+
```json
146+
{"token":"YOUR_AZURE_DEVOPS_TOKEN","serverUrl":"https://pkgs.dev.azure.com/contoso/BusinessCentral/_packaging/BC-Apps/nuget/v3/index.json"}
147+
```
148+
149+
**AL-Go-Settings.json**:
150+
```json
151+
{
152+
"trustedNuGetFeeds": [
153+
{
154+
"url": "https://pkgs.dev.azure.com/contoso/BusinessCentral/_packaging/BC-Apps/nuget/v3/index.json",
155+
"authTokenSecret": "NuGetContext",
156+
"patterns": ["Contoso.*"]
157+
}
158+
]
159+
}
160+
```
161+
162+
### Example 3: Multi-Environment Setup
163+
164+
**AL-Go-Settings.json**:
165+
```json
166+
{
167+
"DeliverToGitHubPackages": {
168+
"ContinuousDelivery": true,
169+
"Branches": ["main", "develop"]
170+
},
171+
"environments": [
172+
{
173+
"name": "PRODUCTION",
174+
"DeliverToNuGet": {
175+
"ContinuousDelivery": true,
176+
"Branches": ["main"]
177+
}
178+
}
179+
]
180+
}
181+
```
182+
183+
## Troubleshooting
184+
185+
### Common Issues
186+
187+
#### 1. Missing Context Secret
188+
**Error**: `Secret 'GitHubPackagesContext' not found`
189+
**Solution**: Ensure the secret is created at the organization level (or repository level) and is accessible to your repository.
190+
191+
#### 2. Authentication Failed
192+
**Error**: `401 Unauthorized` when publishing packages
193+
**Solution**:
194+
- Verify your personal access token has the correct scopes
195+
- Check if your token has expired
196+
- Ensure your token has access to the target organization
197+
198+
#### 3. Package Not Found During Dependency Resolution
199+
**Error**: Unable to find package during build
200+
**Solution**:
201+
- Verify the package was published successfully
202+
- Check that dependency resolution is configured correctly
203+
- Ensure the package name and version match your app.json dependencies
204+
205+
#### 4. Curly Brackets Masked in Logs
206+
**Error**: Seeing `***` instead of JSON in logs
207+
**Solution**: Ensure your JSON secrets are compressed (single line) without formatting.
208+
209+
### Debugging Steps
210+
211+
1. **Check Workflow Logs**: Look for the "Deliver to [Target]" job in your CI/CD workflow
212+
2. **Verify Package Publication**: Check your organization's packages page
213+
3. **Test Dependency Resolution**: Look for "Resolving Dependencies" and "installing app dependencies" in build logs
214+
4. **Validate Secret Format**: Use `New-ALGoNuGetContext` to generate correctly formatted secrets
215+
216+
## Advanced Scenarios
217+
218+
### Custom Delivery Scripts
219+
220+
For advanced scenarios, you can create custom delivery scripts:
221+
222+
1. Create a PowerShell script named `DeliverTo<TargetName>.ps1` in your `.github` folder
223+
2. Create a context secret named `<TargetName>Context`
224+
3. AL-Go will automatically detect and use your custom delivery target
225+
226+
Example custom delivery script:
227+
```powershell
228+
# .github/DeliverToCustomFeed.ps1
229+
Param(
230+
[string] $artifacts,
231+
[string] $deliveryTarget,
232+
[string] $deliveryContext
233+
)
234+
235+
# Custom delivery logic here
236+
Write-Host "Delivering to custom feed: $deliveryTarget"
237+
```
238+
239+
### Branch-Specific Delivery
240+
241+
Configure different delivery targets for different branches:
242+
243+
```json
244+
{
245+
"DeliverToGitHubPackages": {
246+
"ContinuousDelivery": true,
247+
"Branches": ["develop", "feature/*"]
248+
},
249+
"DeliverToNuGet": {
250+
"ContinuousDelivery": true,
251+
"Branches": ["main"]
252+
}
253+
}
254+
```
255+
256+
### Multiple Feed Configuration
257+
258+
You can configure multiple trusted NuGet feeds for dependency resolution:
259+
260+
```json
261+
{
262+
"trustedNuGetFeeds": [
263+
{
264+
"url": "https://nuget.pkg.github.com/contoso/index.json",
265+
"authTokenSecret": "GitHubPackagesContext",
266+
"patterns": ["Contoso.*"]
267+
},
268+
{
269+
"url": "https://pkgs.dev.azure.com/contoso/BC/_packaging/External/nuget/v3/index.json",
270+
"authTokenSecret": "AzureDevOpsContext",
271+
"patterns": ["External.*"]
272+
}
273+
]
274+
}
275+
```
276+
277+
## Important Notes
278+
279+
### Security Considerations
280+
281+
- **Use appropriate token scopes**: Only grant necessary permissions to your tokens
282+
- **Organization vs Repository secrets**: Use organization secrets for shared configurations
283+
- **Token expiration**: Regularly rotate your personal access tokens
284+
- **Compressed JSON**: Always use compressed JSON format for secrets to avoid masking issues
285+
286+
### Limitations
287+
288+
- **Fine-grained tokens**: GitHub Packages doesn't support fine-grained personal access tokens yet
289+
- **Package visibility**: GitHub Packages inherit repository visibility settings
290+
- **Retention policies**: Consider package retention policies for your feeds
291+
- **Version conflicts**: Be mindful of version conflicts when using multiple feeds
292+
293+
### Best Practices
294+
295+
1. **Use semantic versioning**: Follow semantic versioning for your packages
296+
2. **Test in isolation**: Test delivery configuration in a separate repository first
297+
3. **Monitor package sizes**: Be aware of package size limits
298+
4. **Document dependencies**: Clearly document your app dependencies
299+
5. **Regular cleanup**: Implement package cleanup policies
300+
301+
## Next Steps
302+
303+
- [Learn more about AL-Go Settings](settings.md)
304+
- [Explore Continuous Delivery options](../Workshop/ContinuousDelivery.md)
305+
- [Set up dependencies between repositories](../Workshop/Dependencies2.md)
306+
- [Understand AL-Go Secrets](secrets.md)

‎Workshop/ContinuousDelivery.md

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -70,7 +70,29 @@ Continuous delivery to **AppSource** is supported by the AppSource template and
7070

7171
## NuGet
7272

73-
Still work-in-progress. Delivery to NuGet is supposed to be delivery to a NuGet feed, where your partners can get access to your apps or runtime packages. This section will be updated when we release delivery to NuGet in it's final version.
73+
AL-Go for GitHub supports experimental delivery to NuGet feeds and GitHub Packages. This enables you to automatically publish your apps to package repositories for distribution and dependency management.
74+
75+
> [!NOTE]
76+
> **Experimental Feature**: NuGet and GitHub Packages delivery is currently experimental but stable. The functionality has been used in production by several partners for over 6 months.
77+
78+
For comprehensive documentation on setting up NuGet and GitHub Packages delivery, including detailed configuration examples and troubleshooting, see the [DeliveryTargets and NuGet/GitHub Packages](../Scenarios/DeliveryTargets.md) guide.
79+
80+
### Quick Setup for GitHub Packages
81+
82+
1. **Create Personal Access Token**: Create a classic personal access token with `write:packages` scope
83+
2. **Create Organizational Secret**: Create `GitHubPackagesContext` secret with format:
84+
```json
85+
{"token":"ghp_YOUR_TOKEN","serverUrl":"https://nuget.pkg.github.com/YOUR_ORG/index.json"}
86+
```
87+
3. **Run CI/CD**: Your apps will automatically be published to GitHub Packages after successful builds
88+
89+
### Quick Setup for Custom NuGet Feed
90+
91+
1. **Create NuGetContext Secret**: Create `NuGetContext` secret with your custom feed URL and token
92+
2. **Configure Dependency Resolution**: Add your feed to `trustedNuGetFeeds` setting if you want to use it for dependencies
93+
3. **Run CI/CD**: Your apps will be delivered to the specified NuGet feed
94+
95+
For detailed step-by-step instructions, configuration examples, and troubleshooting, refer to the [comprehensive DeliveryTargets guide](../Scenarios/DeliveryTargets.md).
7496

7597
## Custom delivery
7698

0 commit comments

Comments
 (0)