Skip to main content

Source control

A source control integration is how Application Exposure learns what code you have. Connect one and your repositories appear, ready to be associated with applications and handed to the built-in SAST and SCA scanners.

Every source control integration is read-only on your code. The platform clones to scan and posts a status on the commit it scanned; it never pushes, merges or changes a repository.

What each contributes​

VendorConnect withContributes
GitHubApp installation on your organizationRepositories and branches, Dependabot alerts, code scanning alerts, secret scanning alerts, SAST and SCA
GitLabOAuth authorization for one group, or a group access token; GitLab.com or self-managedProjects and branches, SAST and SCA
Azure DevOpsService principalRepositories and branches, pipeline activity, SAST and SCA

Connecting​

Integrations → Available Integrations → Source control, choose the vendor.

GitHub​

Connect opens GitHub's App installation page for your organization. Choose which repositories the App may see; the integration is created when the installation completes. Access is managed on GitHub's side afterwards, under the organization's installed Apps, which is also where it is revoked.

GitLab​

Connect opens a short dialog, then GitLab's authorization page.

Where GitLab is hosted. GitLab.com needs nothing more. For a self-managed instance, register an application on the instance (confidential, with the platform's callback URL as its redirect URI and the scopes below) and enter the instance URL, application ID and secret. The instance must be reachable over https on a public address: an instance on a private network, behind a VPN, or with a self-signed certificate is not supported. GitLab 16.0 or later is supported; on 19.1 or later, webhook deliveries are signed, and on earlier versions they carry a secret token instead.

What to ask for.

AccessScopesWhat you get
Full (recommended)api, read_repositoryInventory, a scan on every push and merge request, and the verdict posted on the commit
Read-onlyread_api, read_repositoryInventory, and scans on demand and whenever a branch has moved between syncs. No project hooks and no commit statuses

api is asked for because creating a project hook and posting a commit status are writes, and GitLab has no narrower permission for either. The platform never pushes.

Authorize as an account that is a Maintainer or Owner of the group you want to connect. An integration is one group; if the account maintains several, you are asked which one after authorizing. Projects in subgroups are included.

Or use a group access token. Instead of authorizing, choose Use a group access token and enter the group and a token with the Maintainer or Owner role and the scopes above. The token is checked before it is stored. GitLab requires these tokens to expire within a year; the integration shows when, and the token is replaced under Edit.

What each role allows. The platform works with the role the authorizing account or token holds on each project, and says so on the project's page:

RoleAllows
ReporterReading the code: the project is inventoried and can be scanned
DeveloperPosting the verdict as a commit status on merge requests
MaintainerCreating the project hook that makes a push trigger a scan

A project the account only Develops still scans, on demand and whenever a branch has moved between syncs; what it cannot have is a hook, and the sync report says so.

The grant GitLab issues expires and is renewed by the platform on its own. If it is revoked on GitLab's side, Re-authorize on the integration grants it again without losing the projects, branches or findings already collected. The renewing account must still be a Maintainer or Owner of the connected group; a grant from one that is not is refused rather than stored.

Projects that leave the group, are deleted, or stop being visible to the authorizing account are retired on the next discovery, with their findings kept. A branch deleted on GitLab is retired when the push that deletes it arrives.

Azure DevOps​

Connect asks for a service principal with read access to the organization. See the connect dialog for the fields and the permissions each needs.

Repositories and branches​

Discovery runs on connect and then on the integration's sync interval. Each repository is listed under Application Exposure → Repositories with its branches, default branch, language and visibility, and can be associated with an application from there.

Archived repositories are kept, marked archived, and hidden by default.

Selecting projects​

For GitLab, discovery lists every project in the group the account can read, and does nothing more with any of them until you select it. The Monitored switch on the Repositories list is that selection: a selected project has its branches listed, can be scanned, and gets a hook. Deselecting a project turns scanning off on every branch and removes its hook. The selection is enforced by the platform, not only shown: an unselected project cannot be scanned by any route.

GitHub and Azure DevOps make this selection on the vendor's side, when the App is installed or the service principal is scoped, so every repository they list is selected.

Turning scanning on​

Scanning is per branch. On a repository's Branches tab, enable SAST on a branch and both SAST and SCA run on every push to it, and on every pull or merge request that targets it (see Pull request checks). The result is posted back as a status on the commit, so a failing scan is visible where the change is reviewed.

For GitLab, enabling the first branch of a selected project creates a project hook on it. The hook signs every delivery with a key the platform mints for the integration, and the platform checks that signature, and that the delivery is recent, before it reads anything. Every sync brings the hooks back into step: one GitLab removed or disabled is remade, one that drifted is rewritten, one no longer needed is removed. Disabling the last branch removes the hook, and deleting the integration removes every hook it created and revokes the grant on GitLab's side.

A push GitLab does not deliver (it sends none for a push touching more than three branches, and stops delivering to a hook that keeps failing) is not lost: a branch that has moved since the last sync is scanned when the sync sees it.

Each enabled branch counts toward the repository scanning capacity in your plan.

Pull request checks​

A pull request (a merge request on GitLab) into a branch with SAST enabled is checked by the CyberOptix CTEM Platform. The check is the same on GitHub, GitLab and Azure DevOps: one status on the pull request's head commit, and a report behind it.

What starts a check. Opening a pull request, pushing new commits to it, and reopening it. Each starts one scan of the new head; a pull request whose head has already been scanned is not scanned again, so editing the title or the reviewers costs nothing. Closing or merging the pull request ends its runs. The check gates on the branch the pull request targets: it is that branch's scanning that is on or off, not the source branch's.

What is scanned. Only the files the pull request changed. SAST reads those files, and SCA reads the dependency manifests among them, so a pull request that touches one file is judged on that file and a pull request that touches no code passes. When the vendor cannot list the changes (a pull request over GitHub's 3000-file limit, say) the whole head is scanned instead, and the report says which it was.

How the verdict is reached. The scan is compared against what is already active on the target branch. A vulnerability the target branch already carries is reported as pre-existing and never fails the check; one that is not is introduced by the pull request. The check fails when an introduced vulnerability is High or Critical, and passes otherwise, however many pre-existing ones the files carry. If the target branch has never been scanned there is nothing to compare against, every vulnerability counts as introduced, and the status says so.

What you see on the pull request. The status is pending while the scan runs and names how many changed files it covers, then reports one of:

StatusMeaning
SuccessNo introduced vulnerability at High or Critical
FailureAt least one, with the counts in the description
ErrorThe scan could not run, with the reason

The status description carries the counts of introduced, blocking and pre-existing vulnerabilities, and its Details link opens the report in the CyberOptix CTEM Platform. Whether a failed check blocks the merge is up to you: make the check required in the branch protection or branch policy on the vendor's side.

The report. Application Exposure → Pull Requests lists every run with its repository, source and target branch, scope, verdict and counts, and can be narrowed by verdict and by whether the pull request is open, merged or closed. A run's report shows the verdict and what it rests on, and every vulnerability the scan observed with whether the pull request introduced it and whether it blocks; each opens the vulnerability's own page.

What each vendor needs. GitHub and Azure DevOps post the status with the integration's credential. On GitLab, posting a commit status needs the Developer role on the project (see What each role allows above); a read-only credential scans the merge request and records the run, and the report is in the platform, but no status appears on GitLab.

Pull requests from forks. The source branch of a fork pull request is not a branch of the repository, so there is nothing to attach its vulnerabilities to. The run ends in error and the status says so; the pull request is not passed unscanned.

When it stops working​

  • Repositories stopped updating. The grant was revoked or the App uninstalled. For GitLab, Re-authorize the integration; for GitHub, reinstall the App; for Azure DevOps, replace the service principal secret.
  • Pushes no longer trigger scans. The webhook was removed on the vendor side. See Webhooks.
  • A GitLab project is missing. The authorizing account must reach it at Maintainer or above; projects it can only report on are not listed.
  • Pull requests show no check. Scanning is enabled on the branch being merged, not the branch being merged into. Enable SAST on the target branch. On GitLab, a read-only credential scans but cannot post the status; the run is still under Application Exposure → Pull Requests.

Next​

  • Application Exposure - associating repositories with applications and reading scan results
  • Webhooks - the inbound endpoints vendors post to