From cbd75fa3d3e7cd9354b5d0ac7bb50242d5c474c7 Mon Sep 17 00:00:00 2001 From: italo viana Date: Fri, 28 Aug 2026 13:11:35 -0300 Subject: [PATCH] docs(ast-orchestrator): document the AST branch pattern across the four ALMs The merge gate compared the merged branch to a single name with exact equality, so the guides could only describe two setups: one branch, or every branch. It is now a regular expression resolved at two levels, which the "Merge target branch" section had no way to express. That section is replaced with "AST branch pattern" in the GitHub, GitLab, Bitbucket and Azure DevOps guides: where each level is configured, the resolution order (repository -> integration -> orchestrator ref as a legacy fallback -> every branch), how a pattern is matched and validated, worked examples, and the branch picker now on the on-demand Run AST dialog. Anchoring and the fail-closed behaviour are stated explicitly because both are observable: `main` does not match `maintenance`, and a pattern that errors or times out while a merge is evaluated skips the scan rather than dispatching it. Values already stored keep their exact meaning, so the guides say plainly that there is nothing to migrate. Ref keeps its own entry and a note saying it is the orchestrator's branch, not a branch policy -- it stays the filter only when nothing else is set. Also updates the configuration step, validation checklist, troubleshooting table and frontmatter of each guide, and the AST row of the GitLab repositories validation table. Backend: convisoappsec/platform-backend#14364 Frontend: convisoappsec/platform-frontend#3094 Co-Authored-By: Claude Opus 5 --- .../azure-devops-ast-orchestrator.md | 90 +++++++++++++++---- .../bitbucket-ast-orchestrator.md | 90 +++++++++++++++---- docs/integrations/github-ast-orchestrator.md | 90 +++++++++++++++---- docs/integrations/gitlab-ast-orchestrator.md | 90 +++++++++++++++---- docs/integrations/gitlab-repositories.md | 2 +- 5 files changed, 285 insertions(+), 77 deletions(-) diff --git a/docs/integrations/azure-devops-ast-orchestrator.md b/docs/integrations/azure-devops-ast-orchestrator.md index 5aaa19ce..5655fb64 100644 --- a/docs/integrations/azure-devops-ast-orchestrator.md +++ b/docs/integrations/azure-devops-ast-orchestrator.md @@ -2,13 +2,15 @@ id: azure-devops-ast-orchestrator title: Azure DevOps AST Orchestrator sidebar_label: AST Orchestrator -description: Configure a centralized Azure DevOps pipeline to run Conviso AST after PR merges using only CONVISO_API_KEY. +description: Configure a centralized Azure DevOps pipeline to run Conviso AST after PR merges on every branch matching your AST branch pattern, using only CONVISO_API_KEY. keywords: [ Azure DevOps AST Orchestrator, Application Security Testing, Azure Pipelines, pipeline-orchestrator, + AST branch pattern, + multi-branch AST, conviso-ast-repository-token, Conviso Platform, ] @@ -38,7 +40,7 @@ What Conviso checks before dispatching: 1. The event is a pull request that was **merged**. 2. **AST scans on merge** is enabled on the Azure DevOps integration. 3. The repository is an **imported asset** that is **enabled**. -4. The PR **destination branch** matches the configured merge target (see [Merge target branch](#merge-target-branch) below). +4. The PR **destination branch** matches the configured [AST branch pattern](#ast-branch-pattern). The pipeline always appears on the **orchestrator** project (not on the application repository). @@ -66,23 +68,65 @@ You need: | **Orchestrator pipeline** | Azure Pipeline whose YAML is `azure-pipelines.yml`. Conviso triggers this pipeline only. | | **Target repository** | Application repo imported as an asset. It must **not** rely on a local Conviso pipeline for this flow. | | **Ref** | Branch or tag **of the orchestrator** where Azure loads `azure-pipelines.yml` when Conviso starts the run. | -| **Merge target branch** | The PR **destination** branch on the **target** repo that is allowed to trigger a scan (for example `main`). See below. | +| **AST branch pattern** | Regular expression matched against the merged PR's **destination** branch on the **target** repo. Only a branch it matches triggers a scan. See below. | | **Asset** | Imported repository in Conviso where findings are stored. | -### Merge target branch +### AST branch pattern -Conviso compares the merged PR’s **destination branch** to: +Conviso decides whether a merge triggers a scan by matching the merged PR's **destination branch** +against a **regular expression** you configure — the **AST branch pattern**. One pattern can name +several branches (`main|develop`) or a whole family of them (`release/.*`). -1. The asset’s configured AST / branch mapping, if set; otherwise -2. The integration **Ref** (`orchestrator_ref`). +Before this, the platform compared that branch to a **single name**, with exact equality. Only two +setups were expressible: one branch, or every branch. -| Configuration | What triggers a scan | +#### Where you set it + +| Level | Where | Applies to | +| --- | --- | --- | +| **Repository** | The **Branch pattern** column on the repository table, in the integration's configuration step | That repository only | +| **Integration** | **Branch pattern that runs the AST**, on the integration configuration page | Every repository of this integration that has no pattern of its own | + +#### Which one applies + +The first level that is configured wins: + +1. The repository's own **Branch pattern**. +2. The integration's **Branch pattern that runs the AST**. +3. The integration **Ref** — *legacy fallback*, so nothing changes for a setup that was already using Ref as a branch filter. +4. Nothing configured — **every branch** triggers a scan. + +:::note Ref is the orchestrator's branch, not a branch policy +**Ref** means "which branch of the orchestrator project holds `azure-pipelines.yml`". It was reused as a branch +filter before the branch pattern existed, and it still is when nothing else is set — but it is no +longer the field to use for branch policy. Set a branch pattern instead, and leave Ref meaning the +one thing it should mean. +::: + +#### How a pattern is matched + +* **The whole branch name must match.** `main` matches `main` and nothing else — not `maintenance`, not `remain`. +* **A plain branch name behaves exactly as it did before.** Every value already configured in your account keeps meaning exactly what it means today. There is nothing to migrate and nothing you need to do. +* **`|` is how you list branches:** `main|develop|homolog`. +* **The pattern is validated when you save it.** One that does not compile, is longer than 500 characters, or is too slow to evaluate is refused, with the reason shown under the field. +* **A pattern that fails at merge time does not dispatch.** If a stored expression errors or times out while a merge is being evaluated, Conviso skips the scan rather than spending your CI budget on a decision it could not make. + +#### Examples + +| Pattern | Merges that trigger a scan | | --- | --- | -| Asset branch = `master`, Ref = `main` | Only merges **into `master`** on that asset | -| Asset branch empty, Ref = `main` | Only merges **into `main`** on that asset | -| Asset branch empty and Ref empty | No branch filter (any destination branch can trigger). Prefer setting Ref explicitly. | +| *(nothing set at any level)* | Every branch | +| `main` | `main` only | +| `main\|develop` | `main` and `develop` | +| `release/.*` | Every branch under `release/` | +| `main\|release/.*` | `main`, and every branch under `release/` | +| `main` *(stored before this feature)* | `main` only — unchanged | + +#### Running the AST on demand -**Ref is still the orchestrator branch that holds `azure-pipelines.yml`.** It is reused as the default merge-target filter when the asset has no branch of its own. Those are two roles of the same field — do not confuse “where the YAML lives” with “any branch on the target”. +**Run AST** on the asset offers a **Branch to scan** picker, listing only the branches that match +that asset's pattern. If the pattern matches none of the asset's branches, the button is disabled +and says so — adjust the pattern in the integration settings. --- @@ -368,22 +412,26 @@ Do **not** add an Azure DevOps PAT for clone. The job calls `conviso-ast-reposit | **Orchestrator project** | Project that contains the orchestrator pipeline | Second path segment of the same URL | | **Orchestrator pipeline ID** | The number from Step 3, e.g. `42` | `definitionId=` in the pipeline URL | | **Orchestrator ref** | Branch holding the YAML — usually `main` | Same branch from Step 1. Conviso prefixes plain values with `refs/heads/`; a tag must be written as `refs/tags/` | +| **Branch pattern that runs the AST** | Optional regular expression for the branches on the **target** repositories that should trigger a scan, e.g. `main\|develop` | Leave empty to keep using **Orchestrator ref** as the filter. See [AST branch pattern](#ast-branch-pattern) | 4. Save. ![Step 5: Orchestrator configuration in Conviso](/img/azure-devops/ast-step-02-orchestrator-config.png) -### Step 6 – Assets and merge target +### Step 6 – Assets and branch pattern 1. Confirm each application repository is **imported** and **enabled**. -2. Set the asset branch mapping when the merge target is **not** the same as Ref (example: Ref `main` on the orchestrator, merges into `master` on the asset → map the asset to `master`). -3. If the asset has no branch mapping, merges must go into the branch named by **Ref** (or any branch only if Ref is also empty — avoid that setup). +2. Set **Branch pattern that runs the AST** on the integration page when more than one branch should be scanned — `main|develop`, or `release/.*`. +3. Override it for a single repository from the **Branch pattern** column on the repository table, when that one ships from a different branch than the rest. +4. If you set neither, the integration **Ref** is still used as the filter (legacy behavior); if Ref is empty too, every branch triggers a scan. + +See [AST branch pattern](#ast-branch-pattern) for how the expression is matched and validated. --- ## End-to-end flow (after setup) -1. Developer merges a PR into the configured merge target on an imported, enabled asset. +1. Developer merges a PR into a branch matching the AST branch pattern, on an imported, enabled asset. 2. Conviso validates the event and configuration, then starts the orchestrator pipeline on the **Ref** branch. 3. Template parameters include the repository, branch, and related ids Conviso needs for the run. 4. Job steps: issue repository token → clone target → run `conviso-ast` → upload session artifact. @@ -397,7 +445,7 @@ Do **not** add an Azure DevOps PAT for clone. The job calls `conviso-ast-reposit | Variable | `CONVISO_API_KEY` exists as a **secret pipeline variable** on the orchestrator | | Path | `azure-pipelines.yml` is on the **Ref** branch | | Conviso | Organization + project + pipeline ID + Ref saved; **AST scans on merge** on | -| Asset | Target repo imported, enabled; merge target branch matches mapping or Ref | +| Asset | Target repo imported, enabled; the merged branch matches the AST branch pattern (repository level, integration level, or Ref as the legacy fallback) | | After merge | New pipeline run on the orchestrator; findings (or a clean result) on the asset | ![Validation: successful orchestrator pipeline run](/img/azure-devops/ast-step-06-run-success.png) @@ -408,13 +456,17 @@ Manual test (optional): on the orchestrator, **Run pipeline**. Set `repo_full_na | Symptom | Cause / fix | |---------|-------------| -| Merge done, no pipeline | **AST scans on merge** off; organization/project/pipeline ID/Ref incomplete; asset disabled or not imported; PR destination ≠ asset branch / Ref; connecting user lacks **Edit subscriptions** so no Service Hook was registered ([details](./azure-devops.md#service-hook-permissions)) | +| Merge done, no pipeline | **AST scans on merge** off; organization/project/pipeline ID/Ref incomplete; asset disabled or not imported; the merged branch does not match the AST branch pattern; connecting user lacks **Edit subscriptions** so no Service Hook was registered ([details](./azure-devops.md#service-hook-permissions)) | +| A branch you expected to scan is skipped | The pattern does not match the whole branch name. `main` does not match `main-hotfix`; use `main.*` if that is what you meant. Check the repository pattern first — it overrides the integration's | +| No branch scans any more, after editing a pattern | A stored pattern that fails to compile or times out is treated as "do not dispatch". Reopen the field, save a valid expression, and confirm it is accepted | +| The pattern is refused when you save it | It does not compile, is longer than 500 characters, or is too slow to evaluate. The reason is shown under the field | +| **Run AST** is disabled on the asset | The pattern matches none of the asset's branches. Adjust it in the integration settings | | `Repository is not available for this API key` | Wrong environment (`CONVISO_API_KEY` vs `api_url`); Azure integration not authorized; asset not imported/enabled for that company | | Unreadable / HTML response from Platform | Use the production API host (`https://api.convisoappsec.com`). The template remaps `https://app.convisoappsec.com` automatically | | Initialize containers fails | Confirm `options: --entrypoint ""` is present on the container | | `CONVISO_API_KEY` empty / unauthorized | Confirm the secret is a **pipeline variable** (Edit → Variables). A Library / variable group is not enough unless the YAML also references that group — this template does not | | Scanner missing `CONVISO_COMPANY_ID` | Manual run without `company_id` and without pipeline variable `CONVISO_COMPANY_ID` | -| Wrong code scanned | Merge target / `branch` mismatch; confirm you merged into the configured destination branch | +| Wrong code scanned | `branch` mismatch; confirm you merged into a branch the AST branch pattern matches | ## Migrating from `System.AccessToken` or `ADO_GIT_PAT` diff --git a/docs/integrations/bitbucket-ast-orchestrator.md b/docs/integrations/bitbucket-ast-orchestrator.md index a6d635ad..13bf5f27 100644 --- a/docs/integrations/bitbucket-ast-orchestrator.md +++ b/docs/integrations/bitbucket-ast-orchestrator.md @@ -2,13 +2,15 @@ id: bitbucket-ast-orchestrator title: Bitbucket AST Orchestrator sidebar_label: AST Orchestrator -description: Configure a centralized Bitbucket Pipelines repository to run Conviso AST after PR merges using only CONVISO_API_KEY. +description: Configure a centralized Bitbucket Pipelines repository to run Conviso AST after PR merges on every branch matching your AST branch pattern, using only CONVISO_API_KEY. keywords: [ Bitbucket AST Orchestrator, Application Security Testing, Bitbucket Pipelines, pipeline-orchestrator, + AST branch pattern, + multi-branch AST, conviso-ast-repository-token, Conviso Platform, ] @@ -38,7 +40,7 @@ What Conviso checks before dispatching: 1. The event is a pull request that was **merged**. 2. **AST scans on merge** is enabled on the Bitbucket integration. 3. The repository is an **imported asset** that is **enabled**. -4. The PR **destination branch** matches the configured merge target (see [Merge target branch](#merge-target-branch) below). +4. The PR **destination branch** matches the configured [AST branch pattern](#ast-branch-pattern). The pipeline always appears on the **orchestrator** repository (not on the application repository). @@ -63,24 +65,66 @@ You need: | **Orchestrator repository** | Bitbucket repo that contains `bitbucket-pipelines.yml`. Conviso triggers this repo only. | | **Target repository** | Application repo imported as an asset. It must **not** rely on a local Conviso Pipelines file for this flow. | | **Ref** | Branch or tag **of the orchestrator** where Bitbucket loads `bitbucket-pipelines.yml` when Conviso starts the custom pipeline. | -| **Merge target branch** | The PR **destination** branch on the **target** repo that is allowed to trigger a scan (for example `main`). See below. | +| **AST branch pattern** | Regular expression matched against the merged PR's **destination** branch on the **target** repo. Only a branch it matches triggers a scan. See below. | | **Custom pipeline** | Entry under `pipelines.custom` that Conviso triggers by name (`run-ast-scan`). | | **Asset** | Imported repository in Conviso (`workspace/repo`) where findings are stored. | -### Merge target branch +### AST branch pattern -Conviso compares the merged PR’s **destination branch** to: +Conviso decides whether a merge triggers a scan by matching the merged PR's **destination branch** +against a **regular expression** you configure — the **AST branch pattern**. One pattern can name +several branches (`main|develop`) or a whole family of them (`release/.*`). -1. The asset’s configured AST / branch mapping, if set; otherwise -2. The integration **Ref** (`orchestrator_ref`). +Before this, the platform compared that branch to a **single name**, with exact equality. Only two +setups were expressible: one branch, or every branch. -| Configuration | What triggers a scan | +#### Where you set it + +| Level | Where | Applies to | +| --- | --- | --- | +| **Repository** | The **Branch pattern** column on the repository table, in the integration's configuration step | That repository only | +| **Integration** | **Branch pattern that runs the AST**, on the integration configuration page | Every repository of this integration that has no pattern of its own | + +#### Which one applies + +The first level that is configured wins: + +1. The repository's own **Branch pattern**. +2. The integration's **Branch pattern that runs the AST**. +3. The integration **Ref** — *legacy fallback*, so nothing changes for a setup that was already using Ref as a branch filter. +4. Nothing configured — **every branch** triggers a scan. + +:::note Ref is the orchestrator's branch, not a branch policy +**Ref** means "which branch of the orchestrator repository holds `bitbucket-pipelines.yml`". It was reused as a branch +filter before the branch pattern existed, and it still is when nothing else is set — but it is no +longer the field to use for branch policy. Set a branch pattern instead, and leave Ref meaning the +one thing it should mean. +::: + +#### How a pattern is matched + +* **The whole branch name must match.** `main` matches `main` and nothing else — not `maintenance`, not `remain`. +* **A plain branch name behaves exactly as it did before.** Every value already configured in your account keeps meaning exactly what it means today. There is nothing to migrate and nothing you need to do. +* **`|` is how you list branches:** `main|develop|homolog`. +* **The pattern is validated when you save it.** One that does not compile, is longer than 500 characters, or is too slow to evaluate is refused, with the reason shown under the field. +* **A pattern that fails at merge time does not dispatch.** If a stored expression errors or times out while a merge is being evaluated, Conviso skips the scan rather than spending your CI budget on a decision it could not make. + +#### Examples + +| Pattern | Merges that trigger a scan | | --- | --- | -| Asset branch = `master`, Ref = `main` | Only merges **into `master`** on that asset | -| Asset branch empty, Ref = `main` | Only merges **into `main`** on that asset | -| Asset branch empty and Ref empty | No branch filter (any destination branch can trigger). Prefer setting Ref explicitly. | +| *(nothing set at any level)* | Every branch | +| `main` | `main` only | +| `main\|develop` | `main` and `develop` | +| `release/.*` | Every branch under `release/` | +| `main\|release/.*` | `main`, and every branch under `release/` | +| `main` *(stored before this feature)* | `main` only — unchanged | + +#### Running the AST on demand -**Ref is still the orchestrator branch that holds `bitbucket-pipelines.yml`.** It is reused as the default merge-target filter when the asset has no branch of its own. Those are two roles of the same field — do not confuse “where the Pipelines file lives” with “any branch on the target”. +**Run AST** on the asset offers a **Branch to scan** picker, listing only the branches that match +that asset's pattern. If the pattern matches none of the asset's branches, the button is disabled +and says so — adjust the pattern in the integration settings. --- @@ -209,23 +253,27 @@ pipelines: - **Workspace** — Bitbucket workspace slug of the orchestrator repository. - **Repository** — repository slug (not the full URL). - **Ref** — orchestrator branch/tag that contains `bitbucket-pipelines.yml` (e.g. `main`). + - **Branch pattern that runs the AST** — optional regular expression for the branches on the **target** repositories that should trigger a scan, e.g. `main|develop`. Leave it empty to keep using **Ref** as the filter. See [AST branch pattern](#ast-branch-pattern). 4. Save. *Step 4: Orchestrator workspace, repository, ref, and AST scans toggle.* ![Step 4: Orchestrator configuration in Conviso](/img/bitbucket-alm/ast-04-orchestrator-config.png) -### Step 5 – Assets and merge target +### Step 5 – Assets and branch pattern 1. Confirm each application repository is **imported** and **enabled**. -2. Set the asset branch mapping when the merge target is **not** the same as Ref (example: Ref `main` on the orchestrator, merges into `master` on the asset → map the asset to `master`). -3. If the asset has no branch mapping, merges must go into the branch named by **Ref** (or any branch only if Ref is also empty — avoid that setup). +2. Set **Branch pattern that runs the AST** on the integration page when more than one branch should be scanned — `main|develop`, or `release/.*`. +3. Override it for a single repository from the **Branch pattern** column on the repository table, when that one ships from a different branch than the rest. +4. If you set neither, the integration **Ref** is still used as the filter (legacy behavior); if Ref is empty too, every branch triggers a scan. + +See [AST branch pattern](#ast-branch-pattern) for how the expression is matched and validated. --- ## End-to-end flow (after setup) -1. Developer merges a PR into the configured merge target on an imported, enabled asset. +1. Developer merges a PR into a branch matching the AST branch pattern, on an imported, enabled asset. 2. Conviso validates the event and configuration, then starts custom pipeline **`run-ast-scan`** on the orchestrator / **Ref**. 3. Variables include at least: `repo_full_name`, `branch` (PR destination), `commit_sha`, `pr_id`, `api_url`, `company_id`, `asset_id` (blank values may be omitted). 4. Job steps: issue repository token → clone target at `branch` → run `conviso-ast` → upload session artifact. @@ -239,7 +287,7 @@ pipelines: | Variable | `CONVISO_API_KEY` exists on the orchestrator (secured) | | Path | `bitbucket-pipelines.yml` with `pipelines.custom.run-ast-scan` is on the **Ref** branch | | Conviso | Workspace + repository + Ref saved; **AST scans on merge** on | -| Asset | Target repo imported, enabled; merge target branch matches mapping or Ref | +| Asset | Target repo imported, enabled; the merged branch matches the AST branch pattern (repository level, integration level, or Ref as the legacy fallback) | | After merge | New Pipelines run on the orchestrator for `run-ast-scan`; findings (or a clean result) on the asset | *Validation: successful orchestrator pipeline run.* @@ -256,12 +304,16 @@ Manual test (optional): on the orchestrator, **Run pipeline** → custom pipelin | Symptom | Cause / fix | |---------|-------------| -| Merge done, no pipeline | **AST scans on merge** off; workspace/repository/Ref incomplete; asset disabled or not imported; PR destination ≠ asset branch / Ref; webhooks unhealthy | +| Merge done, no pipeline | **AST scans on merge** off; workspace/repository/Ref incomplete; asset disabled or not imported; the merged branch does not match the AST branch pattern; webhooks unhealthy | +| A branch you expected to scan is skipped | The pattern does not match the whole branch name. `main` does not match `main-hotfix`; use `main.*` if that is what you meant. Check the repository pattern first — it overrides the integration's | +| No branch scans any more, after editing a pattern | A stored pattern that fails to compile or times out is treated as "do not dispatch". Reopen the field, save a valid expression, and confirm it is accepted | +| The pattern is refused when you save it | It does not compile, is longer than 500 characters, or is too slow to evaluate. The reason is shown under the field | +| **Run AST** is disabled on the asset | The pattern matches none of the asset's branches. Adjust it in the integration settings | | `Requested selector is not found` | `pipelines.custom.run-ast-scan` missing on the **exact Ref** configured in Conviso | | Token / clone fails (HTTP 4xx) | `repo_full_name` not an imported asset for that API key/company; wrong environment (`CONVISO_API_KEY` vs `api_url`); Bitbucket integration not authorized / OAuth user lacks access | | Unreadable / HTML response from Platform | Use the API host (`api.*`), not `app.*` / `staging.*`. The template normalizes those hosts automatically | | Scanner missing `CONVISO_COMPANY_ID` | Manual run without `company_id` and without variable `CONVISO_COMPANY_ID` | -| Wrong code scanned | Merge target / `branch` mismatch; confirm you merged into the configured destination branch | +| Wrong code scanned | `branch` mismatch; confirm you merged into a branch the AST branch pattern matches | ## Related guides diff --git a/docs/integrations/github-ast-orchestrator.md b/docs/integrations/github-ast-orchestrator.md index c56704de..95eb2508 100644 --- a/docs/integrations/github-ast-orchestrator.md +++ b/docs/integrations/github-ast-orchestrator.md @@ -2,13 +2,15 @@ id: github-ast-orchestrator title: GitHub AST Orchestrator sidebar_label: AST Orchestrator -description: Configure a centralized GitHub Actions repository to run Conviso AST after PR merges using only CONVISO_API_KEY. +description: Configure a centralized GitHub Actions repository to run Conviso AST after PR merges on every branch matching your AST branch pattern, using only CONVISO_API_KEY. keywords: [ GitHub AST Orchestrator, Application Security Testing, GitHub Actions, pipeline-orchestrator, + AST branch pattern, + multi-branch AST, conviso-ast-repository-token, Conviso Platform, ] @@ -38,7 +40,7 @@ What Conviso checks before dispatching: 1. The event is a pull request that was **merged** (`action: closed` and `merged: true`). 2. **AST Scans** is enabled on the GitHub integration. 3. The repository is an **imported asset** that is **enabled**. -4. The PR **base branch** matches the configured merge target (see [Merge target branch](#merge-target-branch) below). +4. The PR **base branch** matches the configured [AST branch pattern](#ast-branch-pattern). The Actions run always appears on the **orchestrator** repository (not on the application repository). @@ -64,23 +66,65 @@ You need: | **Orchestrator repository** | GitHub repo that contains `.github/workflows/ast.yml`. Conviso triggers this repo only. | | **Target repository** | Application repo imported as an asset. It must **not** rely on a local Conviso workflow for this flow. | | **Ref** | Branch or tag **of the orchestrator** where GitHub loads `ast.yml` when Conviso calls `workflow_dispatch`. If you leave Ref empty in Conviso, dispatch defaults to **`main`**. | -| **Merge target branch** | The PR **base** branch on the **target** repo that is allowed to trigger a scan (for example `main`). See below. | +| **AST branch pattern** | Regular expression matched against the merged PR's **base** branch on the **target** repo. Only a branch it matches triggers a scan. See below. | | **Asset** | Imported repository in Conviso (`owner/repo`) where findings are stored. | -### Merge target branch +### AST branch pattern -Conviso compares the merged PR’s **base branch** to: +Conviso decides whether a merge triggers a scan by matching the merged PR's **base branch** +against a **regular expression** you configure — the **AST branch pattern**. One pattern can name +several branches (`main|develop`) or a whole family of them (`release/.*`). -1. The asset’s configured AST / branch mapping, if set; otherwise -2. The integration **Ref** (`orchestrator_ref`). +Before this, the platform compared that branch to a **single name**, with exact equality. Only two +setups were expressible: one branch, or every branch. -| Configuration | What triggers a scan | +#### Where you set it + +| Level | Where | Applies to | +| --- | --- | --- | +| **Repository** | The **Branch pattern** column on the repository table, in the integration's configuration step | That repository only | +| **Integration** | **Branch pattern that runs the AST**, on the integration configuration page | Every repository of this integration that has no pattern of its own | + +#### Which one applies + +The first level that is configured wins: + +1. The repository's own **Branch pattern**. +2. The integration's **Branch pattern that runs the AST**. +3. The integration **Ref** — *legacy fallback*, so nothing changes for a setup that was already using Ref as a branch filter. +4. Nothing configured — **every branch** triggers a scan. + +:::note Ref is the orchestrator's branch, not a branch policy +**Ref** means "which branch of the orchestrator repository holds `ast.yml`". It was reused as a branch +filter before the branch pattern existed, and it still is when nothing else is set — but it is no +longer the field to use for branch policy. Set a branch pattern instead, and leave Ref meaning the +one thing it should mean. +::: + +#### How a pattern is matched + +* **The whole branch name must match.** `main` matches `main` and nothing else — not `maintenance`, not `remain`. +* **A plain branch name behaves exactly as it did before.** Every value already configured in your account keeps meaning exactly what it means today. There is nothing to migrate and nothing you need to do. +* **`|` is how you list branches:** `main|develop|homolog`. +* **The pattern is validated when you save it.** One that does not compile, is longer than 500 characters, or is too slow to evaluate is refused, with the reason shown under the field. +* **A pattern that fails at merge time does not dispatch.** If a stored expression errors or times out while a merge is being evaluated, Conviso skips the scan rather than spending your CI budget on a decision it could not make. + +#### Examples + +| Pattern | Merges that trigger a scan | | --- | --- | -| Asset branch = `master`, Ref = `main` | Only merges **into `master`** on that asset | -| Asset branch empty, Ref = `main` | Only merges **into `main`** on that asset | -| Asset branch empty and Ref empty | No branch filter (any base branch can trigger). Prefer setting Ref explicitly. | +| *(nothing set at any level)* | Every branch | +| `main` | `main` only | +| `main\|develop` | `main` and `develop` | +| `release/.*` | Every branch under `release/` | +| `main\|release/.*` | `main`, and every branch under `release/` | +| `main` *(stored before this feature)* | `main` only — unchanged | + +#### Running the AST on demand -**Ref is still the orchestrator branch that holds the workflow.** It is reused as the default merge-target filter when the asset has no branch of its own. Those are two roles of the same field — do not confuse “where `ast.yml` lives” with “any branch on the target”. +**Run AST** on the asset offers a **Branch to scan** picker, listing only the branches that match +that asset's pattern. If the pattern matches none of the asset's branches, the button is disabled +and says so — adjust the pattern in the integration settings. --- @@ -275,21 +319,25 @@ jobs: - **Orchestrator Repo** — `owner/repo` of the orchestrator. - **Workflow Filename or ID** — `ast.yml`. - **Ref** — orchestrator branch/tag that contains `.github/workflows/ast.yml` (e.g. `main`). If empty, Conviso dispatches with ref **`main`**. + - **Branch pattern that runs the AST** — optional regular expression for the branches on the **target** repositories that should trigger a scan, e.g. `main|develop`. Leave it empty to keep using **Ref** as the filter. See [AST branch pattern](#ast-branch-pattern). 4. Save. ![Orchestrator Configuration](../../static/img/github/github-ast-orchestrator.png) -### Step 5 – Assets and merge target +### Step 5 – Assets and branch pattern 1. Confirm each application repository is **imported** and **enabled**. -2. Set the asset branch mapping when the merge target is **not** the same as Ref (example: Ref `main` on the orchestrator, merges into `master` on the asset → map the asset to `master`). -3. If the asset has no branch mapping, merges must go into the branch named by **Ref** (or any branch only if Ref is also empty — avoid that setup). +2. Set **Branch pattern that runs the AST** on the integration page when more than one branch should be scanned — `main|develop`, or `release/.*`. +3. Override it for a single repository from the **Branch pattern** column on the repository table, when that one ships from a different branch than the rest. +4. If you set neither, the integration **Ref** is still used as the filter (legacy behavior); if Ref is empty too, every branch triggers a scan. + +See [AST branch pattern](#ast-branch-pattern) for how the expression is matched and validated. --- ## End-to-end flow (after setup) -1. Developer merges a PR into the configured merge target on an imported, enabled asset. +1. Developer merges a PR into a branch matching the AST branch pattern, on an imported, enabled asset. 2. Conviso validates the event and configuration, then calls `workflow_dispatch` on `owner/orchestrator` / `ast.yml` / **Ref**. 3. Inputs include at least: `repo_full_name`, `branch` (PR base), `commit_sha`, `pr_number`, `api_url`, `company_id`, `asset_id` (blank values may be omitted). 4. Job steps: issue repository token → checkout target at `branch` → run `conviso-ast` → upload session artifact. @@ -303,7 +351,7 @@ jobs: | Secret | `CONVISO_API_KEY` exists on the orchestrator | | Path | `.github/workflows/ast.yml` is on the **Ref** branch | | Conviso | Orchestrator `owner/repo` + `ast.yml` + Ref saved; **AST Scans** on | -| Asset | Target repo imported, enabled; merge target branch matches mapping or Ref | +| Asset | Target repo imported, enabled; the merged branch matches the AST branch pattern (repository level, integration level, or Ref as the legacy fallback) | | After merge | New run under orchestrator **Actions**; findings (or a clean result) on the asset | *Successful orchestrator run: Get repository token → Checkout → Run Conviso AST.* @@ -320,12 +368,16 @@ Manual test (optional): on the orchestrator, **Actions → AST Scan Orchestrator | Symptom | Cause / fix | |---------|-------------| -| Merge done, no Actions run | **AST Scans** off; orchestrator fields incomplete; asset disabled or not imported; PR base branch ≠ asset branch / Ref; GitHub App cannot see the repos | +| Merge done, no Actions run | **AST Scans** off; orchestrator fields incomplete; asset disabled or not imported; the merged branch does not match the AST branch pattern; GitHub App cannot see the repos | +| A branch you expected to scan is skipped | The pattern does not match the whole branch name. `main` does not match `main-hotfix`; use `main.*` if that is what you meant. Check the repository pattern first — it overrides the integration's | +| No branch scans any more, after editing a pattern | A stored pattern that fails to compile or times out is treated as "do not dispatch". Reopen the field, save a valid expression, and confirm it is accepted | +| The pattern is refused when you save it | It does not compile, is longer than 500 characters, or is too slow to evaluate. The reason is shown under the field | +| **Run AST** is disabled on the asset | The pattern matches none of the asset's branches. Adjust it in the integration settings | | Workflow never listed | File not under `.github/workflows/`, or not on the **Ref** branch Conviso uses | | Token step fails (HTTP 4xx) | `repo_full_name` not an imported asset for that API key/company; wrong environment (`CONVISO_API_KEY` vs `api_url`) | | Checkout 403 | GitHub App lacks access to the **target** repository | | Scanner missing `CONVISO_COMPANY_ID` | Manual run without `company_id` input and without variable `CONVISO_COMPANY_ID` | -| Wrong code scanned | Merge target / `branch` input mismatch; confirm you merged into the configured base branch | +| Wrong code scanned | `branch` input mismatch; confirm you merged into a branch the AST branch pattern matches | ## Related guides diff --git a/docs/integrations/gitlab-ast-orchestrator.md b/docs/integrations/gitlab-ast-orchestrator.md index 8c737d87..fe089605 100644 --- a/docs/integrations/gitlab-ast-orchestrator.md +++ b/docs/integrations/gitlab-ast-orchestrator.md @@ -2,13 +2,15 @@ id: gitlab-ast-orchestrator title: GitLab AST Orchestrator sidebar_label: AST Orchestrator -description: Configure a centralized GitLab CI project to run Conviso AST after MR merges using only CONVISO_API_KEY. +description: Configure a centralized GitLab CI project to run Conviso AST after MR merges on every branch matching your AST branch pattern, using only CONVISO_API_KEY. keywords: [ GitLab AST Orchestrator, Application Security Testing, GitLab CI, pipeline-orchestrator, + AST branch pattern, + multi-branch AST, conviso-ast-repository-token, Conviso Platform, ] @@ -38,7 +40,7 @@ What Conviso checks before dispatching: 1. The event is a merge request that was **merged**. 2. **AST scans on merge** is enabled on the GitLab integration. 3. The repository is an **imported asset** that is **enabled**. -4. The MR **target branch** matches the configured merge target (see [Merge target branch](#merge-target-branch) below). +4. The MR **target branch** matches the configured [AST branch pattern](#ast-branch-pattern). The pipeline always appears on the **orchestrator** project (not on the application project). @@ -63,23 +65,65 @@ You need: | **Orchestrator project** | GitLab project that contains `.gitlab-ci.yml`. Conviso triggers this project only. | | **Target repository** | Application project imported as an asset. It must **not** rely on a local Conviso CI file for this flow. | | **Ref** | Branch or tag **of the orchestrator** where GitLab loads `.gitlab-ci.yml` when Conviso creates the pipeline. | -| **Merge target branch** | The MR **target** branch on the **target** project that is allowed to trigger a scan (for example `main`). See below. | +| **AST branch pattern** | Regular expression matched against the merged MR's **target** branch on the **target** project. Only a branch it matches triggers a scan. See below. | | **Asset** | Imported repository in Conviso (`group/project` path) where findings are stored. | -### Merge target branch +### AST branch pattern -Conviso compares the merged MR’s **target branch** to: +Conviso decides whether a merge triggers a scan by matching the merged MR's **target branch** +against a **regular expression** you configure — the **AST branch pattern**. One pattern can name +several branches (`main|develop`) or a whole family of them (`release/.*`). -1. The asset’s configured AST / branch mapping, if set; otherwise -2. The integration **Ref** (`orchestrator_ref` / pipeline ref). +Before this, the platform compared that branch to a **single name**, with exact equality. Only two +setups were expressible: one branch, or every branch. -| Configuration | What triggers a scan | +#### Where you set it + +| Level | Where | Applies to | +| --- | --- | --- | +| **Project** | The **Branch pattern** column on the project table, in the integration's configuration step | That project only | +| **Integration** | **Branch pattern that runs the AST**, on the integration configuration page | Every project of this integration that has no pattern of its own | + +#### Which one applies + +The first level that is configured wins: + +1. The project's own **Branch pattern**. +2. The integration's **Branch pattern that runs the AST**. +3. The integration **Ref** — *legacy fallback*, so nothing changes for a setup that was already using Ref as a branch filter. +4. Nothing configured — **every branch** triggers a scan. + +:::note Ref is the orchestrator's branch, not a branch policy +**Ref** means "which branch of the orchestrator project holds `.gitlab-ci.yml`". It was reused as a branch +filter before the branch pattern existed, and it still is when nothing else is set — but it is no +longer the field to use for branch policy. Set a branch pattern instead, and leave Ref meaning the +one thing it should mean. +::: + +#### How a pattern is matched + +* **The whole branch name must match.** `main` matches `main` and nothing else — not `maintenance`, not `remain`. +* **A plain branch name behaves exactly as it did before.** Every value already configured in your account keeps meaning exactly what it means today. There is nothing to migrate and nothing you need to do. +* **`|` is how you list branches:** `main|develop|homolog`. +* **The pattern is validated when you save it.** One that does not compile, is longer than 500 characters, or is too slow to evaluate is refused, with the reason shown under the field. +* **A pattern that fails at merge time does not dispatch.** If a stored expression errors or times out while a merge is being evaluated, Conviso skips the scan rather than spending your CI budget on a decision it could not make. + +#### Examples + +| Pattern | Merges that trigger a scan | | --- | --- | -| Asset branch = `master`, Ref = `main` | Only merges **into `master`** on that asset | -| Asset branch empty, Ref = `main` | Only merges **into `main`** on that asset | -| Asset branch empty and Ref empty | No branch filter (any target branch can trigger). Prefer setting Ref explicitly. | +| *(nothing set at any level)* | Every branch | +| `main` | `main` only | +| `main\|develop` | `main` and `develop` | +| `release/.*` | Every branch under `release/` | +| `main\|release/.*` | `main`, and every branch under `release/` | +| `main` *(stored before this feature)* | `main` only — unchanged | + +#### Running the AST on demand -**Ref is still the orchestrator branch that holds `.gitlab-ci.yml`.** It is reused as the default merge-target filter when the asset has no branch of its own. Those are two roles of the same field — do not confuse “where the CI file lives” with “any branch on the target”. +**Run AST** on the asset offers a **Branch to scan** picker, listing only the branches that match +that asset's pattern. If the pattern matches none of the asset's branches, the button is disabled +and says so — adjust the pattern in the integration settings. --- @@ -209,6 +253,7 @@ If Conviso fails to trigger with **Insufficient permissions to set pipeline vari 3. Under **Orchestrator pipeline**, fill: - **Project ID** — numeric GitLab project ID of the orchestrator. - **Ref** — orchestrator branch/tag that contains `.gitlab-ci.yml` (e.g. `main`). + - **Branch pattern that runs the AST** — optional regular expression for the branches on the **target** projects that should trigger a scan, e.g. `main|develop`. Leave it empty to keep using **Ref** as the filter. See [AST branch pattern](#ast-branch-pattern). 4. Save. The Project ID is shown in GitLab under the orchestrator project → **Settings → General**: @@ -223,17 +268,20 @@ Then paste it into Conviso and set the ref: ![Orchestrator pipeline configuration in Conviso](../../static/img/gitlab-alm/ast-01-orchestrator-config.png) -### Step 5 – Assets and merge target +### Step 5 – Assets and branch pattern 1. Confirm each application project is **imported** and **enabled**. -2. Set the asset branch mapping when the merge target is **not** the same as Ref (example: Ref `main` on the orchestrator, merges into `master` on the asset → map the asset to `master`). -3. If the asset has no branch mapping, merges must go into the branch named by **Ref** (or any branch only if Ref is also empty — avoid that setup). +2. Set **Branch pattern that runs the AST** on the integration page when more than one branch should be scanned — `main|develop`, or `release/.*`. +3. Override it for a single project from the **Branch pattern** column on the project table, when that one ships from a different branch than the rest. +4. If you set neither, the integration **Ref** is still used as the filter (legacy behavior); if Ref is empty too, every branch triggers a scan. + +See [AST branch pattern](#ast-branch-pattern) for how the expression is matched and validated. --- ## End-to-end flow (after setup) -1. Developer merges an MR into the configured merge target on an imported, enabled asset. +1. Developer merges an MR into a branch matching the AST branch pattern, on an imported, enabled asset. 2. Conviso validates the event and configuration, then creates a pipeline on the orchestrator project / **Ref**. 3. Variables include at least: `repo_full_name`, `branch` (MR target), `commit_sha`, `mr_iid`, `api_url`, `company_id`, `asset_id` (blank values may be omitted). 4. Job steps: issue repository token → clone target at `branch` → run `conviso-ast` → upload session artifact. @@ -247,7 +295,7 @@ Then paste it into Conviso and set the ref: | Variable | `CONVISO_API_KEY` exists on the orchestrator (Masked; Protected only if Ref is protected) | | Path | `.gitlab-ci.yml` is on the **Ref** branch | | Conviso | Orchestrator Project ID + Ref saved; **AST scans on merge** on | -| Asset | Target project imported, enabled; merge target branch matches mapping or Ref | +| Asset | Target project imported, enabled; the merged branch matches the AST branch pattern (project level, integration level, or Ref as the legacy fallback) | | After merge | New pipeline on the orchestrator with job `run-ast-scan`; findings (or a clean result) on the asset | *Successful orchestrator pipeline: stage `scan`, job `run-ast-scan` Passed.* @@ -264,14 +312,18 @@ Manual test (optional): on the orchestrator, **Build → Pipelines → New pipel | Symptom | Cause / fix | |---------|-------------| -| Merge done, no pipeline | **AST scans on merge** off; Project ID/Ref incomplete; asset disabled or not imported; MR target branch ≠ asset branch / Ref | +| Merge done, no pipeline | **AST scans on merge** off; Project ID/Ref incomplete; asset disabled or not imported; the merged branch does not match the AST branch pattern | +| A branch you expected to scan is skipped | The pattern does not match the whole branch name. `main` does not match `main-hotfix`; use `main.*` if that is what you meant. Check the project pattern first — it overrides the integration's | +| No branch scans any more, after editing a pattern | A stored pattern that fails to compile or times out is treated as "do not dispatch". Reopen the field, save a valid expression, and confirm it is accepted | +| The pattern is refused when you save it | It does not compile, is longer than 500 characters, or is too slow to evaluate. The reason is shown under the field | +| **Run AST** is disabled on the asset | The pattern matches none of the asset's branches. Adjust it in the integration settings | | **Insufficient permissions to set pipeline variables** | Set minimum role to Developer/Maintainer (see above) and ensure the OAuth user has that role | | `unrecognized arguments: sh -c ...` | Missing `entrypoint: [""]` on the `convisoast_v2` image | | Token / clone fails (HTTP 4xx) | `repo_full_name` not an imported asset for that API key/company; wrong environment (`CONVISO_API_KEY` vs `api_url`); GitLab integration not authorized | | `CONVISO_API_KEY` empty / auth errors on unprotected branch | Variable is **Protected** but Ref is not a protected branch — uncheck Protected or protect the branch | | Unreadable / HTML response from Platform | Use the API host (`api.*`), not `app.*` / `staging.*`. The template normalizes those hosts automatically | | Scanner missing `CONVISO_COMPANY_ID` | Manual run without `company_id` and without variable `CONVISO_COMPANY_ID` | -| Wrong code scanned | Merge target / `branch` mismatch; confirm you merged into the configured target branch | +| Wrong code scanned | `branch` mismatch; confirm you merged into a branch the AST branch pattern matches | ## Related guides diff --git a/docs/integrations/gitlab-repositories.md b/docs/integrations/gitlab-repositories.md index da0455d6..c89e8120 100644 --- a/docs/integrations/gitlab-repositories.md +++ b/docs/integrations/gitlab-repositories.md @@ -178,7 +178,7 @@ For full AST after merge via a central GitLab CI project (Project ID, ref, `CONV | Login | OAuth completes; Authorization step unlocks | | Authorization | Import starts; Configuration shows assets | | MR scans | Opening an MR shows Conviso commit status / feedback | -| AST on merge | Merge into the configured branch triggers the orchestrator pipeline | +| AST on merge | Merging into a branch that matches the [AST branch pattern](./gitlab-ast-orchestrator.md#ast-branch-pattern) triggers the orchestrator pipeline | ## Troubleshooting