|
1 | 1 | # Code Scanning Setup Guide |
2 | 2 |
|
3 | | -This document explains how to resolve code scanning configuration issues in this repository and maintain compliance with organizational policies. |
| 3 | +This document explains the CodeQL code scanning configuration for this repository. |
4 | 4 |
|
5 | 5 | ## Current Configuration |
6 | 6 |
|
7 | | -This repository has two CodeQL code scanning configurations: |
| 7 | +This repository uses a **custom CodeQL workflow** (`.github/workflows/codeql-analysis.yml`) that provides thorough analysis with the `security-and-quality` query suite. |
8 | 8 |
|
9 | | -1. **Default Setup** (managed by GitHub) — Configured in **Settings > Code security > Code scanning**. This is GitHub's built-in scanning that runs automatically without a workflow file. |
| 9 | +### Workflow Details |
10 | 10 |
|
11 | | -2. **Custom Workflow** (`.github/workflows/codeql.yml`) — A workflow file in the repository that provides more control over the scanning process, including the `security-and-quality` query suite. |
| 11 | +- **Triggers**: Pushes and pull requests to `develop`/`main`, monthly scheduled scan, manual dispatch |
| 12 | +- **Runner**: `ubuntu-latest` |
| 13 | +- **Build target**: `net9.0-android` (compatible with Ubuntu runners) |
| 14 | +- **Query suite**: `security-and-quality` (more thorough than default) |
12 | 15 |
|
13 | | -## Known Issue: Stale Configuration Error |
| 16 | +## Previous Issue: Stale Configuration |
14 | 17 |
|
15 | | -The custom CodeQL workflow (`codeql.yml`) was previously **manually disabled**, which causes the code scanning status page to show an error or stale configuration at: |
| 18 | +The original workflow file (`codeql.yml`) was **manually disabled** in GitHub Actions UI. A manually disabled workflow cannot be re-enabled through code changes alone — modifying the file content has no effect on the disabled state. This caused the code scanning status page to show a stale configuration error. |
16 | 19 |
|
17 | | -> **Security** > **Code scanning** > **Tool status** > **CodeQL** > **Configurations** |
| 20 | +The fix was to rename the workflow file from `codeql.yml` to `codeql-analysis.yml`. GitHub Actions identifies workflows by their file path, so the renamed file is treated as a new (active) workflow. |
18 | 21 |
|
19 | | -This happens because GitHub detects the workflow configuration but finds no recent scan results from it. |
| 22 | +## Managing Duplicate Scanning Configurations |
20 | 23 |
|
21 | | -## How to Resolve |
| 24 | +If both the custom workflow and GitHub's **Default Setup** are active, you may see duplicate scan results. To avoid this: |
22 | 25 |
|
23 | | -You have two options — choose **one**: |
| 26 | +1. Go to **Settings** > **Code security** > **Code scanning** |
| 27 | +2. Disable the **Default setup** since the custom workflow provides more thorough analysis |
24 | 28 |
|
25 | | -### Option A: Use the Custom Workflow (Recommended) |
| 29 | +## Why a Custom Build Is Required |
26 | 30 |
|
27 | | -The custom workflow provides more thorough analysis with the `security-and-quality` query suite. |
| 31 | +CodeQL's **Autobuild** step cannot build .NET MAUI projects because: |
28 | 32 |
|
29 | | -1. Go to **Actions** > **CodeQL** (the workflow, not the default setup) |
30 | | -2. Click **Enable workflow** to re-enable the disabled `codeql.yml` |
31 | | -3. Optionally, trigger a manual run via **Run workflow** to verify it works |
32 | | -4. Go to **Settings** > **Code security** > **Code scanning** and disable the **Default setup** to avoid duplicate scanning |
33 | | -5. Verify the workflow completes successfully and results appear under **Security** > **Code scanning** |
34 | | - |
35 | | -### Option B: Use the Default Setup Only |
36 | | - |
37 | | -If you prefer the simpler GitHub-managed scanning: |
38 | | - |
39 | | -1. Verify the Default Setup is enabled in **Settings** > **Code security** > **Code scanning** |
40 | | -2. **Delete** the file `.github/workflows/codeql.yml` from the repository to remove the stale configuration |
41 | | -3. Commit and push the deletion |
42 | | -4. The stale configuration error will clear after the next scheduled scan |
43 | | - |
44 | | -## Why Was the Workflow Failing? |
45 | | - |
46 | | -The original `codeql.yml` used CodeQL's **Autobuild** step, which could not build this .NET MAUI project because: |
47 | | - |
48 | | -- The .NET SDK was not set up in the workflow |
49 | | -- MAUI workloads (required for building MAUI projects) were not installed |
| 33 | +- The .NET SDK is not set up in the runner by default |
| 34 | +- MAUI workloads (required for building MAUI projects) are not installed |
50 | 35 | - Autobuild does not automatically install platform-specific workloads |
51 | 36 |
|
52 | | -The updated workflow in this repository fixes these issues by: |
| 37 | +The custom workflow fixes these issues by: |
53 | 38 |
|
54 | 39 | - Adding a `setup-dotnet` step for .NET 9 |
55 | | -- Installing the `maui-android` workload (compatible with Ubuntu runners) |
56 | | -- Replacing the Autobuild step with an explicit `dotnet build` targeting `net9.0-android` |
| 40 | +- Installing the `android` and `maui-android` workloads |
| 41 | +- Replacing Autobuild with an explicit `dotnet build` targeting `net9.0-android` |
57 | 42 |
|
58 | 43 | ## Verifying Code Scanning Compliance |
59 | 44 |
|
|
0 commit comments