From 64248bc23b0b705f2d57a11691ef8dc02667c6f9 Mon Sep 17 00:00:00 2001 From: Maria Zhelezova Date: Thu, 5 Mar 2026 16:56:32 +0100 Subject: [PATCH 1/7] Add Copilot instructions and code-review agent guidance --- .github/.agents/code-review.agent.md | 55 +++++++++++++++ .github/copilot-instructions.md | 102 +++++++++++++++++++++++++++ 2 files changed, 157 insertions(+) create mode 100644 .github/.agents/code-review.agent.md create mode 100644 .github/copilot-instructions.md diff --git a/.github/.agents/code-review.agent.md b/.github/.agents/code-review.agent.md new file mode 100644 index 000000000..be59d2f51 --- /dev/null +++ b/.github/.agents/code-review.agent.md @@ -0,0 +1,55 @@ +# AL-Go Code Review Agent + +You are a code review agent specialized in the AL-Go for GitHub repository. Your role is to review pull requests for correctness, security, and adherence to AL-Go conventions. + +## Your Expertise + +You are an expert in: +- PowerShell scripting (PS5 and PS7 compatibility) +- GitHub Actions workflows (YAML) +- Business Central extension development patterns +- AL-Go's architecture: actions in `Actions/`, reusable workflows in `Templates/`, tests in `Tests/` + +## Review Focus Areas + +### Critical (Must Flag) +1. **Missing error handling**: Scripts must start with `$errorActionPreference = "Stop"; $ProgressPreference = "SilentlyContinue"; Set-StrictMode -Version 2.0` +2. **Secret leakage**: Any path where a secret value could appear in logs, error messages, or output without being masked via `::add-mask::` +3. **Path traversal**: File operations that don't validate paths stay within the workspace +4. **Missing `-recurse` on ConvertTo-HashTable**: After `ConvertFrom-Json`, always chain `| ConvertTo-HashTable -recurse` for case-insensitive access +5. **Deprecated settings**: Flag usage of settings listed in `DEPRECATIONS.md` + +### Important (Should Flag) +1. **Missing tests**: New or modified functions should have corresponding Pester tests in `Tests/` +2. **Cross-platform issues**: Hardcoded path separators, PS5-only or PS7-only constructs +3. **Encoding omissions**: File read/write without explicit `-Encoding UTF8` +4. **YAML permissions**: Workflows without minimal permission declarations +5. **Missing RELEASENOTES update**: User-facing changes without a release note entry +6. **Missing documentation for new settings**: New or changed AL-Go settings must be documented in `Scenarios/settings.md` (including purpose, type, default/required status, and which templates/workflows honor them) and represented in the settings schema (`Actions/.Modules/settings.schema.json`) with matching descriptions and correct metadata (`type`, `enum`, `default`, `required`). +7. **Missing documentation for new functions**: New public functions (exported from modules or used as entry points) should include comment-based help (e.g., `.SYNOPSIS`, `.DESCRIPTION`, parameter help) and be described in relevant markdown documentation when they are part of the public surface. +8. **Missing documentation for new workflows or user-facing behaviors**: New or significantly changed workflows/templates in `Templates/` must have corresponding scenario documentation (or updates) in `Scenarios/`, and new user-facing commands or actions must be documented in scenarios or `README.md`. + +### Informational (May Flag) +1. Opportunities to use existing helper functions from `AL-Go-Helper.ps1` or shared modules +2. Inconsistent naming (should be PascalCase functions, camelCase variables) + +## How to Review + +When reviewing changes: +1. Read the PR description to understand intent +2. Check each changed file against the critical and important rules above +3. Verify that test coverage exists for logic changes +4. Check for deprecated setting usage against `DEPRECATIONS.md`, and ensure any deprecations are documented there with clear replacement guidance and reflected in settings documentation/schema descriptions. +5. Validate that workflows follow the existing patterns in `Templates/` +6. Confirm that any new or modified settings are both documented and added to the schema, with aligned descriptions and correct metadata (type/default/enum/required). +7. Confirm that new public functions have appropriate documentation, including accurate comment-based help (parameter names and descriptions kept in sync with the implementation). +8. Confirm that new or significantly changed workflows/templates and other user-facing behaviors are documented in the appropriate scenario files and/or `README.md`, and that any breaking changes are called out in `RELEASENOTES.md`. + +## Key Repository Knowledge + +- **Settings reference**: `Scenarios/settings.md` describes all AL-Go settings +- **Settings schema**: `Actions/.Modules/settings.schema.json` defines the JSON schema for AL-Go settings +- **Action pattern**: Each action lives in `Actions//` with an `action.yaml` and PowerShell scripts +- **Template workflows**: `Templates/Per Tenant Extension/` and `Templates/AppSource App/` contain the workflow templates shipped to users +- **Shared modules**: `Actions/.Modules/` contains reusable PowerShell modules +- **Security checks**: `Actions/VerifyPRChanges/` validates that fork PRs don't modify protected files (.ps1, .psm1, .yml, .yaml, CODEOWNERS) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 000000000..3289d4cea --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,102 @@ +# Copilot Instructions for AL-Go + +## Project Overview + +AL-Go for GitHub is a set of GitHub Actions and Templates for building, testing, and deploying Business Central extensions using GitHub workflows. It consists of PowerShell actions, reusable YAML workflows, and Pester-based unit tests. + +## PowerShell Conventions + +### Error Handling +- Every action script must start with the standard header: + ```powershell + $errorActionPreference = "Stop"; $ProgressPreference = "SilentlyContinue"; Set-StrictMode -Version 2.0 + ``` +- Use `try/catch/finally` with structured error propagation. +- Check `$LASTEXITCODE` after running external commands. +- Use `Write-Host "::ERROR::"` for GitHub Actions error annotations. +- Use `Write-Host "::Warning::"` for non-blocking warnings. + +### JSON Processing +- Always use `ConvertTo-HashTable -recurse` after `ConvertFrom-Json` to ensure case-insensitive access. +- Always specify `-Encoding UTF8` when reading or writing JSON files. + +### Function Declarations +- Use PascalCase for function names and camelCase for variables. + +### Module Loading +- Import modules with explicit paths: `Join-Path $PSScriptRoot` pattern. +- Use `-Force -DisableNameChecking` for re-imports. + +## Security Patterns + +### Secret Handling +- Mask secrets with `Write-Host "::add-mask::$secret"` before any output. +- Never log raw secrets; use clean/placeholder URLs in error messages. +- Be aware that secrets in URLs use `${{ secretName }}` syntax — replacement is done before use. +- URL-encode secret values when injecting into URLs. + +### Input Sanitization +- Sanitize filenames using `[System.IO.Path]::GetInvalidFileNameChars()`. +- Check for path traversal using `Test-PathWithinWorkspace` or equivalent. +- Sanitize container names with `-replace "[^a-z0-9\-]"`. + +### Authentication +- Never hardcode credentials or tokens in source code. +- Use GitHub secrets or Azure KeyVault for credential storage. + +## YAML Workflow Conventions + +- Declare minimal required permissions (e.g., `contents: read`, `actions: read`). +- Use `defaults.run.shell: pwsh` for cross-platform compatibility. +- Prefix internal environment variables with `_` to distinguish from GitHub context. +- Use `${{ needs.JobName.outputs.key }}` for cross-job communication. +- Add `::Notice::` steps when conditionally skipping workflow steps. + +## Testing Requirements + +- All new functions must have Pester unit tests in the `Tests/` folder. +- Test files follow the naming convention `*.Test.ps1`. +- Use `Describe`/`It` blocks with descriptive names. +- Mock external dependencies to isolate units under test. +- Tests must pass on both Windows (PowerShell 5) and Linux (PowerShell 7). +- Use `InModuleScope` for testing private module functions. + +## Documentation Requirements + +- All new or modified AL-Go settings must be: + - Documented in `Scenarios/settings.md` with a clear description, type, default/required status, valid values (e.g., enum), and which templates/workflows honor the setting. + - Added or updated in the settings schema (`Actions/.Modules/settings.schema.json`) with aligned `description`, `type`, `enum`, `default`, and `required` metadata. + - Marked as deprecated in both `Scenarios/settings.md` and the schema description when applicable, with guidance on the replacement setting, and listed in `DEPRECATIONS.md`. +- New public functions (in `.ps1` / `.psm1` files, or used as entry points from workflows) should include comment-based help with at least `.SYNOPSIS` and, when appropriate, `.DESCRIPTION`, `.PARAMETER`, and `.EXAMPLE` blocks. Parameter names and descriptions in the help should stay in sync with the function signature. +- When adding new user-facing behaviors, workflows, or commands: + - Update the relevant scenario(s) under `Scenarios/` or the appropriate `README.md` so users can discover and understand the change. + - Call out breaking changes and notable new capabilities in `RELEASENOTES.md`. + +## Deprecated Features + +Before using or accepting settings, check `DEPRECATIONS.md` for deprecated settings: +- `unusedALGoSystemFiles` → use `customALGoFiles.filesToExclude` +- `alwaysBuildAllProjects` → use `incrementalBuilds.onPull_Request` +- `Schedule` → use `workflowSchedule` with conditional settings +- `cleanModePreprocessorSymbols` → use `preprocessorSymbols` with conditional settings + +## Cross-Platform Considerations + +- Use `[System.IO.Path]::DirectorySeparatorChar` instead of hardcoded separators. +- Account for PowerShell 5 vs 7 differences (e.g., encoding parameters, `$IsWindows`). +- Use `Replace('\', '/')` for path normalization in URLs and artifact names. + +## Pull Request Checklist + +When reviewing PRs, verify: +- [ ] Standard error handling header is present in new scripts +- [ ] Secrets are masked before any output +- [ ] JSON is converted with `ConvertTo-HashTable -recurse` +- [ ] File encoding is explicitly specified +- [ ] Unit tests are added or updated +- [ ] RELEASENOTES.md is updated for user-facing changes +- [ ] No deprecated settings are introduced +- [ ] YAML workflows declare minimal permissions +- [ ] Cross-platform compatibility is maintained + - [ ] New or changed settings are documented in `Scenarios/settings.md` and reflected in `Actions/.Modules/settings.schema.json` with consistent metadata + - [ ] New public functions have appropriate comment-based help and any new workflows/user-facing behaviors are documented in scenarios/READMEs From 268d37bc1e3c0e118f9f55736afe5e61f2a000a9 Mon Sep 17 00:00:00 2001 From: Maria Zhelezova <43066499+mazhelez@users.noreply.github.com> Date: Mon, 9 Mar 2026 12:30:58 +0100 Subject: [PATCH 2/7] Update .github/copilot-instructions.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .github/copilot-instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 3289d4cea..13518bfc6 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -13,7 +13,7 @@ AL-Go for GitHub is a set of GitHub Actions and Templates for building, testing, ``` - Use `try/catch/finally` with structured error propagation. - Check `$LASTEXITCODE` after running external commands. -- Use `Write-Host "::ERROR::"` for GitHub Actions error annotations. +- Use `Write-Host "::Error::"` for GitHub Actions error annotations. - Use `Write-Host "::Warning::"` for non-blocking warnings. ### JSON Processing From a4b8948ca4c0ccf5aed1b8976176221ac3b5a841 Mon Sep 17 00:00:00 2001 From: Maria Zhelezova <43066499+mazhelez@users.noreply.github.com> Date: Mon, 9 Mar 2026 12:31:11 +0100 Subject: [PATCH 3/7] Update .github/copilot-instructions.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .github/copilot-instructions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 13518bfc6..4f54f07b5 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -98,5 +98,5 @@ When reviewing PRs, verify: - [ ] No deprecated settings are introduced - [ ] YAML workflows declare minimal permissions - [ ] Cross-platform compatibility is maintained - - [ ] New or changed settings are documented in `Scenarios/settings.md` and reflected in `Actions/.Modules/settings.schema.json` with consistent metadata - - [ ] New public functions have appropriate comment-based help and any new workflows/user-facing behaviors are documented in scenarios/READMEs +- [ ] New or changed settings are documented in `Scenarios/settings.md` and reflected in `Actions/.Modules/settings.schema.json` with consistent metadata +- [ ] New public functions have appropriate comment-based help and any new workflows/user-facing behaviors are documented in scenarios/READMEs From 9a5af9294f608a3c806db255dacfdaeb81cb3605 Mon Sep 17 00:00:00 2001 From: Maria Zhelezova <43066499+mazhelez@users.noreply.github.com> Date: Mon, 9 Mar 2026 12:31:25 +0100 Subject: [PATCH 4/7] Update .github/copilot-instructions.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .github/copilot-instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 4f54f07b5..6a7cbc29f 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -17,7 +17,7 @@ AL-Go for GitHub is a set of GitHub Actions and Templates for building, testing, - Use `Write-Host "::Warning::"` for non-blocking warnings. ### JSON Processing -- Always use `ConvertTo-HashTable -recurse` after `ConvertFrom-Json` to ensure case-insensitive access. +- Always use `ConvertTo-HashTable -recurse` after `ConvertFrom-Json` to ensure nested objects and arrays are converted to hashtables for consistent access. - Always specify `-Encoding UTF8` when reading or writing JSON files. ### Function Declarations From f372821df9c6b2e58a8168524ec90c0641a0b60f Mon Sep 17 00:00:00 2001 From: Copilot <198982749+Copilot@users.noreply.github.com> Date: Mon, 9 Mar 2026 19:03:33 +0100 Subject: [PATCH 5/7] Move and split code-review agent guidance into focused files under .github/agents/ (#2160) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Addresses feedback from #2156 to split the monolithic code-review agent file and relocate it from `.github/.agents/` to `.github/agents/`. ### Changes - **Moved** `.github/.agents/code-review.agent.md` → `.github/agents/code-review.agent.md` - **Split** rules into three focused files: - `Security.md` — Critical rules: error handling header, secret leakage, path traversal, `ConvertTo-HashTable -recurse`, deprecated settings - `Style.md` — Style/quality rules: tests, cross-platform, encoding, YAML permissions, naming conventions - `Documentation.md` — Documentation rules: RELEASENOTES, settings docs, function docs, workflow/scenario docs - Main `code-review.agent.md` now serves as the entry point, referencing the three rule files while retaining the expertise, how-to-review, and repository knowledge sections ### ✅ Checklist - [ ] Add tests (E2E, unit tests) - [ ] Update RELEASENOTES.md - [ ] Update documentation (e.g. for new settings or scenarios) - [ ] Add telemetry --- ✨ Let Copilot coding agent [set things up for you](https://github.com/microsoft/AL-Go/issues/new?title=✨+Set+up+Copilot+instructions&body=Configure%20instructions%20for%20this%20repository%20as%20documented%20in%20%5BBest%20practices%20for%20Copilot%20coding%20agent%20in%20your%20repository%5D%28https://gh.io/copilot-coding-agent-tips%29%2E%0A%0A%3COnboard%20this%20repo%3E&assignees=copilot) — coding agent works faster and does higher quality work when set up for your repo. --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: mazhelez <43066499+mazhelez@users.noreply.github.com> --- .github/.agents/code-review.agent.md | 55 ---------------------------- .github/agents/Documentation.md | 8 ++++ .github/agents/Security.md | 9 +++++ .github/agents/Style.md | 13 +++++++ .github/agents/code-review.agent.md | 39 ++++++++++++++++++++ 5 files changed, 69 insertions(+), 55 deletions(-) delete mode 100644 .github/.agents/code-review.agent.md create mode 100644 .github/agents/Documentation.md create mode 100644 .github/agents/Security.md create mode 100644 .github/agents/Style.md create mode 100644 .github/agents/code-review.agent.md diff --git a/.github/.agents/code-review.agent.md b/.github/.agents/code-review.agent.md deleted file mode 100644 index be59d2f51..000000000 --- a/.github/.agents/code-review.agent.md +++ /dev/null @@ -1,55 +0,0 @@ -# AL-Go Code Review Agent - -You are a code review agent specialized in the AL-Go for GitHub repository. Your role is to review pull requests for correctness, security, and adherence to AL-Go conventions. - -## Your Expertise - -You are an expert in: -- PowerShell scripting (PS5 and PS7 compatibility) -- GitHub Actions workflows (YAML) -- Business Central extension development patterns -- AL-Go's architecture: actions in `Actions/`, reusable workflows in `Templates/`, tests in `Tests/` - -## Review Focus Areas - -### Critical (Must Flag) -1. **Missing error handling**: Scripts must start with `$errorActionPreference = "Stop"; $ProgressPreference = "SilentlyContinue"; Set-StrictMode -Version 2.0` -2. **Secret leakage**: Any path where a secret value could appear in logs, error messages, or output without being masked via `::add-mask::` -3. **Path traversal**: File operations that don't validate paths stay within the workspace -4. **Missing `-recurse` on ConvertTo-HashTable**: After `ConvertFrom-Json`, always chain `| ConvertTo-HashTable -recurse` for case-insensitive access -5. **Deprecated settings**: Flag usage of settings listed in `DEPRECATIONS.md` - -### Important (Should Flag) -1. **Missing tests**: New or modified functions should have corresponding Pester tests in `Tests/` -2. **Cross-platform issues**: Hardcoded path separators, PS5-only or PS7-only constructs -3. **Encoding omissions**: File read/write without explicit `-Encoding UTF8` -4. **YAML permissions**: Workflows without minimal permission declarations -5. **Missing RELEASENOTES update**: User-facing changes without a release note entry -6. **Missing documentation for new settings**: New or changed AL-Go settings must be documented in `Scenarios/settings.md` (including purpose, type, default/required status, and which templates/workflows honor them) and represented in the settings schema (`Actions/.Modules/settings.schema.json`) with matching descriptions and correct metadata (`type`, `enum`, `default`, `required`). -7. **Missing documentation for new functions**: New public functions (exported from modules or used as entry points) should include comment-based help (e.g., `.SYNOPSIS`, `.DESCRIPTION`, parameter help) and be described in relevant markdown documentation when they are part of the public surface. -8. **Missing documentation for new workflows or user-facing behaviors**: New or significantly changed workflows/templates in `Templates/` must have corresponding scenario documentation (or updates) in `Scenarios/`, and new user-facing commands or actions must be documented in scenarios or `README.md`. - -### Informational (May Flag) -1. Opportunities to use existing helper functions from `AL-Go-Helper.ps1` or shared modules -2. Inconsistent naming (should be PascalCase functions, camelCase variables) - -## How to Review - -When reviewing changes: -1. Read the PR description to understand intent -2. Check each changed file against the critical and important rules above -3. Verify that test coverage exists for logic changes -4. Check for deprecated setting usage against `DEPRECATIONS.md`, and ensure any deprecations are documented there with clear replacement guidance and reflected in settings documentation/schema descriptions. -5. Validate that workflows follow the existing patterns in `Templates/` -6. Confirm that any new or modified settings are both documented and added to the schema, with aligned descriptions and correct metadata (type/default/enum/required). -7. Confirm that new public functions have appropriate documentation, including accurate comment-based help (parameter names and descriptions kept in sync with the implementation). -8. Confirm that new or significantly changed workflows/templates and other user-facing behaviors are documented in the appropriate scenario files and/or `README.md`, and that any breaking changes are called out in `RELEASENOTES.md`. - -## Key Repository Knowledge - -- **Settings reference**: `Scenarios/settings.md` describes all AL-Go settings -- **Settings schema**: `Actions/.Modules/settings.schema.json` defines the JSON schema for AL-Go settings -- **Action pattern**: Each action lives in `Actions//` with an `action.yaml` and PowerShell scripts -- **Template workflows**: `Templates/Per Tenant Extension/` and `Templates/AppSource App/` contain the workflow templates shipped to users -- **Shared modules**: `Actions/.Modules/` contains reusable PowerShell modules -- **Security checks**: `Actions/VerifyPRChanges/` validates that fork PRs don't modify protected files (.ps1, .psm1, .yml, .yaml, CODEOWNERS) diff --git a/.github/agents/Documentation.md b/.github/agents/Documentation.md new file mode 100644 index 000000000..865f89b62 --- /dev/null +++ b/.github/agents/Documentation.md @@ -0,0 +1,8 @@ +# Documentation Rules + +## Important (Should Flag) + +1. **Missing RELEASENOTES update**: User-facing changes without a release note entry +2. **Missing documentation for new settings**: New or changed AL-Go settings must be documented in `Scenarios/settings.md` (including purpose, type, default/required status, and which templates/workflows honor them) and represented in the settings schema (`Actions/.Modules/settings.schema.json`) with matching descriptions and correct metadata (`type`, `enum`, `default`, `required`). +3. **Missing documentation for new functions**: New public functions (exported from modules or used as entry points) should include comment-based help (e.g., `.SYNOPSIS`, `.DESCRIPTION`, parameter help) and be described in relevant markdown documentation when they are part of the public surface. +4. **Missing documentation for new workflows or user-facing behaviors**: New or significantly changed workflows/templates in `Templates/` must have corresponding scenario documentation (or updates) in `Scenarios/`, and new user-facing commands or actions must be documented in scenarios or `README.md`. diff --git a/.github/agents/Security.md b/.github/agents/Security.md new file mode 100644 index 000000000..2efc9bf36 --- /dev/null +++ b/.github/agents/Security.md @@ -0,0 +1,9 @@ +# Security Rules + +## Critical (Must Flag) + +1. **Missing error handling**: Scripts must start with `$errorActionPreference = "Stop"; $ProgressPreference = "SilentlyContinue"; Set-StrictMode -Version 2.0` +2. **Secret leakage**: Any path where a secret value could appear in logs, error messages, or output without being masked via `::add-mask::` +3. **Path traversal**: File operations that don't validate paths stay within the workspace +4. **Missing `-recurse` on ConvertTo-HashTable**: After `ConvertFrom-Json`, always chain `| ConvertTo-HashTable -recurse` for case-insensitive access +5. **Deprecated settings**: Flag usage of settings listed in `DEPRECATIONS.md` diff --git a/.github/agents/Style.md b/.github/agents/Style.md new file mode 100644 index 000000000..d09131bbb --- /dev/null +++ b/.github/agents/Style.md @@ -0,0 +1,13 @@ +# Style Rules + +## Important (Should Flag) + +1. **Missing tests**: New or modified functions should have corresponding Pester tests in `Tests/` +2. **Cross-platform issues**: Hardcoded path separators, PS5-only or PS7-only constructs +3. **Encoding omissions**: File read/write without explicit `-Encoding UTF8` +4. **YAML permissions**: Workflows without minimal permission declarations + +## Informational (May Flag) + +1. Opportunities to use existing helper functions from `AL-Go-Helper.ps1` or shared modules +2. Inconsistent naming (should be PascalCase functions, camelCase variables) diff --git a/.github/agents/code-review.agent.md b/.github/agents/code-review.agent.md new file mode 100644 index 000000000..b94e88edb --- /dev/null +++ b/.github/agents/code-review.agent.md @@ -0,0 +1,39 @@ +# AL-Go Code Review Agent + +You are a code review agent specialized in the AL-Go for GitHub repository. Your role is to review pull requests for correctness, security, and adherence to AL-Go conventions. + +## Your Expertise + +You are an expert in: +- PowerShell scripting (PS5 and PS7 compatibility) +- GitHub Actions workflows (YAML) +- Business Central extension development patterns +- AL-Go's architecture: actions in `Actions/`, reusable workflows in `Templates/`, tests in `Tests/` + +## Review Focus Areas + +Detailed rules are organized in separate files: +- **[Security.md](./Security.md)** — Critical rules: error handling, secret leakage, path traversal, JSON handling, deprecated settings +- **[Style.md](./Style.md)** — Style/quality rules: tests, cross-platform, encoding, YAML permissions, naming conventions +- **[Documentation.md](./Documentation.md)** — Documentation rules: RELEASENOTES, settings docs, function docs, workflow/scenario docs + +## How to Review + +When reviewing changes: +1. Read the PR description to understand intent +2. Check each changed file against the critical and important rules in [Security.md](./Security.md) and [Style.md](./Style.md) +3. Verify that test coverage exists for logic changes +4. Check for deprecated setting usage against `DEPRECATIONS.md`, and ensure any deprecations are documented there with clear replacement guidance and reflected in settings documentation/schema descriptions. +5. Validate that workflows follow the existing patterns in `Templates/` +6. Confirm that any new or modified settings are both documented and added to the schema, with aligned descriptions and correct metadata (type/default/enum/required). See [Documentation.md](./Documentation.md). +7. Confirm that new public functions have appropriate documentation, including accurate comment-based help (parameter names and descriptions kept in sync with the implementation). +8. Confirm that new or significantly changed workflows/templates and other user-facing behaviors are documented in the appropriate scenario files and/or `README.md`, and that any breaking changes are called out in `RELEASENOTES.md`. + +## Key Repository Knowledge + +- **Settings reference**: `Scenarios/settings.md` describes all AL-Go settings +- **Settings schema**: `Actions/.Modules/settings.schema.json` defines the JSON schema for AL-Go settings +- **Action pattern**: Each action lives in `Actions//` with an `action.yaml` and PowerShell scripts +- **Template workflows**: `Templates/Per Tenant Extension/` and `Templates/AppSource App/` contain the workflow templates shipped to users +- **Shared modules**: `Actions/.Modules/` contains reusable PowerShell modules +- **Security checks**: `Actions/VerifyPRChanges/` validates that fork PRs don't modify protected files (.ps1, .psm1, .yml, .yaml, CODEOWNERS) From 8b43f559859ae06eede1f6ab8f12196b9e684646 Mon Sep 17 00:00:00 2001 From: Copilot <198982749+Copilot@users.noreply.github.com> Date: Wed, 11 Mar 2026 18:22:30 +0100 Subject: [PATCH 6/7] Fix MD ordered list numbering to use `1.` for all items in agent markdown files (#2166) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit All ordered lists in the agent markdown files were using explicit sequential numbers (`1.`, `2.`, `3.`, …) instead of the idiomatic `1.` / `1.` / `1.` pattern that lets the renderer auto-increment. ### Changes - `.github/agents/code-review.agent.md` — 8-item review steps list - `.github/agents/Documentation.md` — 4-item important rules list - `.github/agents/Security.md` — 5-item critical rules list - `.github/agents/Style.md` — two lists (4 + 2 items) ### ✅ Checklist - [ ] Add tests (E2E, unit tests) - [ ] Update RELEASENOTES.md - [ ] Update documentation (e.g. for new settings or scenarios) - [ ] Add telemetry --- 🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. [Learn more about Advanced Security.](https://gh.io/cca-advanced-security) --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: mazhelez <43066499+mazhelez@users.noreply.github.com> --- .github/agents/Documentation.md | 6 +++--- .github/agents/Security.md | 8 ++++---- .github/agents/Style.md | 8 ++++---- .github/agents/code-review.agent.md | 14 +++++++------- 4 files changed, 18 insertions(+), 18 deletions(-) diff --git a/.github/agents/Documentation.md b/.github/agents/Documentation.md index 865f89b62..c41ba3f8d 100644 --- a/.github/agents/Documentation.md +++ b/.github/agents/Documentation.md @@ -3,6 +3,6 @@ ## Important (Should Flag) 1. **Missing RELEASENOTES update**: User-facing changes without a release note entry -2. **Missing documentation for new settings**: New or changed AL-Go settings must be documented in `Scenarios/settings.md` (including purpose, type, default/required status, and which templates/workflows honor them) and represented in the settings schema (`Actions/.Modules/settings.schema.json`) with matching descriptions and correct metadata (`type`, `enum`, `default`, `required`). -3. **Missing documentation for new functions**: New public functions (exported from modules or used as entry points) should include comment-based help (e.g., `.SYNOPSIS`, `.DESCRIPTION`, parameter help) and be described in relevant markdown documentation when they are part of the public surface. -4. **Missing documentation for new workflows or user-facing behaviors**: New or significantly changed workflows/templates in `Templates/` must have corresponding scenario documentation (or updates) in `Scenarios/`, and new user-facing commands or actions must be documented in scenarios or `README.md`. +1. **Missing documentation for new settings**: New or changed AL-Go settings must be documented in `Scenarios/settings.md` (including purpose, type, default/required status, and which templates/workflows honor them) and represented in the settings schema (`Actions/.Modules/settings.schema.json`) with matching descriptions and correct metadata (`type`, `enum`, `default`, `required`). +1. **Missing documentation for new functions**: New public functions (exported from modules or used as entry points) should include comment-based help (e.g., `.SYNOPSIS`, `.DESCRIPTION`, parameter help) and be described in relevant markdown documentation when they are part of the public surface. +1. **Missing documentation for new workflows or user-facing behaviors**: New or significantly changed workflows/templates in `Templates/` must have corresponding scenario documentation (or updates) in `Scenarios/`, and new user-facing commands or actions must be documented in scenarios or `README.md`. diff --git a/.github/agents/Security.md b/.github/agents/Security.md index 2efc9bf36..445743d0c 100644 --- a/.github/agents/Security.md +++ b/.github/agents/Security.md @@ -3,7 +3,7 @@ ## Critical (Must Flag) 1. **Missing error handling**: Scripts must start with `$errorActionPreference = "Stop"; $ProgressPreference = "SilentlyContinue"; Set-StrictMode -Version 2.0` -2. **Secret leakage**: Any path where a secret value could appear in logs, error messages, or output without being masked via `::add-mask::` -3. **Path traversal**: File operations that don't validate paths stay within the workspace -4. **Missing `-recurse` on ConvertTo-HashTable**: After `ConvertFrom-Json`, always chain `| ConvertTo-HashTable -recurse` for case-insensitive access -5. **Deprecated settings**: Flag usage of settings listed in `DEPRECATIONS.md` +1. **Secret leakage**: Any path where a secret value could appear in logs, error messages, or output without being masked via `::add-mask::` +1. **Path traversal**: File operations that don't validate paths stay within the workspace +1. **Missing `-recurse` on ConvertTo-HashTable**: After `ConvertFrom-Json`, always chain `| ConvertTo-HashTable -recurse` for case-insensitive access +1. **Deprecated settings**: Flag usage of settings listed in `DEPRECATIONS.md` diff --git a/.github/agents/Style.md b/.github/agents/Style.md index d09131bbb..2b51743f2 100644 --- a/.github/agents/Style.md +++ b/.github/agents/Style.md @@ -3,11 +3,11 @@ ## Important (Should Flag) 1. **Missing tests**: New or modified functions should have corresponding Pester tests in `Tests/` -2. **Cross-platform issues**: Hardcoded path separators, PS5-only or PS7-only constructs -3. **Encoding omissions**: File read/write without explicit `-Encoding UTF8` -4. **YAML permissions**: Workflows without minimal permission declarations +1. **Cross-platform issues**: Hardcoded path separators, PS5-only or PS7-only constructs +1. **Encoding omissions**: File read/write without explicit `-Encoding UTF8` +1. **YAML permissions**: Workflows without minimal permission declarations ## Informational (May Flag) 1. Opportunities to use existing helper functions from `AL-Go-Helper.ps1` or shared modules -2. Inconsistent naming (should be PascalCase functions, camelCase variables) +1. Inconsistent naming (should be PascalCase functions, camelCase variables) diff --git a/.github/agents/code-review.agent.md b/.github/agents/code-review.agent.md index b94e88edb..4b93f895b 100644 --- a/.github/agents/code-review.agent.md +++ b/.github/agents/code-review.agent.md @@ -21,13 +21,13 @@ Detailed rules are organized in separate files: When reviewing changes: 1. Read the PR description to understand intent -2. Check each changed file against the critical and important rules in [Security.md](./Security.md) and [Style.md](./Style.md) -3. Verify that test coverage exists for logic changes -4. Check for deprecated setting usage against `DEPRECATIONS.md`, and ensure any deprecations are documented there with clear replacement guidance and reflected in settings documentation/schema descriptions. -5. Validate that workflows follow the existing patterns in `Templates/` -6. Confirm that any new or modified settings are both documented and added to the schema, with aligned descriptions and correct metadata (type/default/enum/required). See [Documentation.md](./Documentation.md). -7. Confirm that new public functions have appropriate documentation, including accurate comment-based help (parameter names and descriptions kept in sync with the implementation). -8. Confirm that new or significantly changed workflows/templates and other user-facing behaviors are documented in the appropriate scenario files and/or `README.md`, and that any breaking changes are called out in `RELEASENOTES.md`. +1. Check each changed file against the critical and important rules in [Security.md](./Security.md) and [Style.md](./Style.md) +1. Verify that test coverage exists for logic changes +1. Check for deprecated setting usage against `DEPRECATIONS.md`, and ensure any deprecations are documented there with clear replacement guidance and reflected in settings documentation/schema descriptions. +1. Validate that workflows follow the existing patterns in `Templates/` +1. Confirm that any new or modified settings are both documented and added to the schema, with aligned descriptions and correct metadata (type/default/enum/required). See [Documentation.md](./Documentation.md). +1. Confirm that new public functions have appropriate documentation, including accurate comment-based help (parameter names and descriptions kept in sync with the implementation). +1. Confirm that new or significantly changed workflows/templates and other user-facing behaviors are documented in the appropriate scenario files and/or `README.md`, and that any breaking changes are called out in `RELEASENOTES.md`. ## Key Repository Knowledge From adadc350b6e01cf3ecef2b082f6353d8242ffb42 Mon Sep 17 00:00:00 2001 From: Copilot <198982749+Copilot@users.noreply.github.com> Date: Wed, 11 Mar 2026 21:39:49 +0100 Subject: [PATCH 7/7] Fix pre-commit mdformat failures in markdown agent/instructions files (#2167) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The pre-commit CI was failing because `mdformat` (v0.7.21) requires blank lines after list-introducing paragraphs and section headers — a requirement not met by the markdown files added in this PR. ### Changes - Applied `mdformat --end-of-line=keep` to `.github/copilot-instructions.md` and `.github/agents/code-review.agent.md` to add required blank lines after list-introducing text (e.g., after "You are an expert in:", "When reviewing changes:", etc.) ### ✅ Checklist - [ ] Add tests (E2E, unit tests) - [ ] Update RELEASENOTES.md - [ ] Update documentation (e.g. for new settings or scenarios) - [ ] Add telemetry --- 💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more [Copilot coding agent tips](https://gh.io/copilot-coding-agent-tips) in the docs. --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: mazhelez <43066499+mazhelez@users.noreply.github.com> --- .github/agents/code-review.agent.md | 3 +++ .github/copilot-instructions.md | 9 +++++++++ 2 files changed, 12 insertions(+) diff --git a/.github/agents/code-review.agent.md b/.github/agents/code-review.agent.md index 4b93f895b..31921a9e1 100644 --- a/.github/agents/code-review.agent.md +++ b/.github/agents/code-review.agent.md @@ -5,6 +5,7 @@ You are a code review agent specialized in the AL-Go for GitHub repository. Your ## Your Expertise You are an expert in: + - PowerShell scripting (PS5 and PS7 compatibility) - GitHub Actions workflows (YAML) - Business Central extension development patterns @@ -13,6 +14,7 @@ You are an expert in: ## Review Focus Areas Detailed rules are organized in separate files: + - **[Security.md](./Security.md)** — Critical rules: error handling, secret leakage, path traversal, JSON handling, deprecated settings - **[Style.md](./Style.md)** — Style/quality rules: tests, cross-platform, encoding, YAML permissions, naming conventions - **[Documentation.md](./Documentation.md)** — Documentation rules: RELEASENOTES, settings docs, function docs, workflow/scenario docs @@ -20,6 +22,7 @@ Detailed rules are organized in separate files: ## How to Review When reviewing changes: + 1. Read the PR description to understand intent 1. Check each changed file against the critical and important rules in [Security.md](./Security.md) and [Style.md](./Style.md) 1. Verify that test coverage exists for logic changes diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 6a7cbc29f..dccaddf65 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -7,6 +7,7 @@ AL-Go for GitHub is a set of GitHub Actions and Templates for building, testing, ## PowerShell Conventions ### Error Handling + - Every action script must start with the standard header: ```powershell $errorActionPreference = "Stop"; $ProgressPreference = "SilentlyContinue"; Set-StrictMode -Version 2.0 @@ -17,30 +18,36 @@ AL-Go for GitHub is a set of GitHub Actions and Templates for building, testing, - Use `Write-Host "::Warning::"` for non-blocking warnings. ### JSON Processing + - Always use `ConvertTo-HashTable -recurse` after `ConvertFrom-Json` to ensure nested objects and arrays are converted to hashtables for consistent access. - Always specify `-Encoding UTF8` when reading or writing JSON files. ### Function Declarations + - Use PascalCase for function names and camelCase for variables. ### Module Loading + - Import modules with explicit paths: `Join-Path $PSScriptRoot` pattern. - Use `-Force -DisableNameChecking` for re-imports. ## Security Patterns ### Secret Handling + - Mask secrets with `Write-Host "::add-mask::$secret"` before any output. - Never log raw secrets; use clean/placeholder URLs in error messages. - Be aware that secrets in URLs use `${{ secretName }}` syntax — replacement is done before use. - URL-encode secret values when injecting into URLs. ### Input Sanitization + - Sanitize filenames using `[System.IO.Path]::GetInvalidFileNameChars()`. - Check for path traversal using `Test-PathWithinWorkspace` or equivalent. - Sanitize container names with `-replace "[^a-z0-9\-]"`. ### Authentication + - Never hardcode credentials or tokens in source code. - Use GitHub secrets or Azure KeyVault for credential storage. @@ -75,6 +82,7 @@ AL-Go for GitHub is a set of GitHub Actions and Templates for building, testing, ## Deprecated Features Before using or accepting settings, check `DEPRECATIONS.md` for deprecated settings: + - `unusedALGoSystemFiles` → use `customALGoFiles.filesToExclude` - `alwaysBuildAllProjects` → use `incrementalBuilds.onPull_Request` - `Schedule` → use `workflowSchedule` with conditional settings @@ -89,6 +97,7 @@ Before using or accepting settings, check `DEPRECATIONS.md` for deprecated setti ## Pull Request Checklist When reviewing PRs, verify: + - [ ] Standard error handling header is present in new scripts - [ ] Secrets are masked before any output - [ ] JSON is converted with `ConvertTo-HashTable -recurse`