This article explains how to run a security scan automatically whenever a branch gets a new commit. After reading it, you can ask a system admin to connect AngusSecurity, then have a repository admin turn on Auto security scanning for this repo, and tell apart whether git push, a commit from the web page, and merging a pull request send a scan, and where to read the result.
Configuration has two layers. A system admin connects AngusSecurity for the whole instance first. A repository admin then turns on Auto security scanning for this repo for one repository. The examples below use the repository xlliu/e2e-license-gate. On this instance the system integration is already provisioned, and Auto security scanning for this repo is already on for that repository.
A gate, in the pages below, is a rule that refuses the merge when its condition is met.
1. System admin: connect AngusSecurity
The whole instance needs this step once. The entry is Management → Security settings, at https://git.anguskit.com/management?tab=security. The page title is AngusSecurity integration.
On this instance the page shows:
-
Config enabled: On. It follows
angus.git.external-security.enabledin the deployment config. - Platform reachable: OK. AngusGit can reach AngusSecurity.
- Last callback: 12 minutes ago. That is the last time AngusSecurity sent a scan result back.
- The page also has Provision and Rotate secret. Provision registers a client that sends scan jobs and stores the secret. Rotate secret invalidates the old secret. When the integration is already on, you do not need to click them.
If the deployment config is still off, the page asks you to set angus.git.external-security.enabled=true. The matching environment variable is ANGUS_GIT_EXTERNAL_SECURITY_ENABLED. When the service address has not been changed, the note on the page uses the default http://127.0.0.1:1811. Restart AngusGit after you change the config.
Lower on the same page is Tenant security policy defaults. New repositories inherit these settings. This instance currently uses:
- New repositories turn on all five checks by default: Code security, Dependency and artifact vulnerabilities, Secret scanning, License compliance, and Code quality.
- Block merge when the gate fails is off.
- Vulnerability gate is Low. License gate is Block when incompatible. How to configure those gates is in the two gate articles at the end.
- Scheduled scans is off. While it is off, the page hides the cron box. After you turn it on, the box shows this note: “Quartz cron, e.g. daily 02:00: 0 0 2 * * ?”. Cron is a short field format for a run time. A Quartz cron expression has six fields, and the first field is seconds. If you do not plan to use a schedule, do not turn the switch on just to see the box, and do not save it that way.
A repository can override these defaults. e2e-license-gate, for example, sets the vulnerability threshold to high and turns on blocking the merge.
2. Repository admin: turn on auto-scan for this repo
Each repository turns auto-scan on by itself. Open Settings → Security (the address includes ?tab=settings§ion=security). The section title is Security. Repo security details on the right opens the repository security page.
The switches on xlliu/e2e-license-gate are:
| Switch | State | What it does |
|---|---|---|
| Auto security scanning for this repo | On | Master switch. See the note after the table |
| Code security | On | On push, checks source code for security issues. Counts toward the vulnerability gate |
| Dependency and artifact vulnerabilities | Off | On push, checks dependencies for known vulnerabilities. Counts toward the vulnerability gate |
| Secret scanning | On | On push, checks the code for secrets and credentials. Counts toward the vulnerability gate |
| License compliance | On | Identifies dependency licenses. Counts toward the license gate |
| Code quality | Off | Checks code quality. Does not take part in the merge gate |
| Block merge when the gate fails | On | Waits while the check is unfinished, and refuses the merge when a gate fails |
Auto security scanning for this repo is the master switch. The page says: “Off by default. Push does not start a scan while this is off. Manual scans and an enabled schedule still run.”
When auto-scan is on, keep at least one check. Otherwise save is blocked with “With auto scanning on, select at least one capability.” A successful save says “Security settings saved”. Changing these settings requires the SecurityScans:EXECUTE permission. If the page already shows the values you want, you do not need to click Save Changes.
The capability marks at the top of the repository security page light up only Secret scanning and License compliance, while the Code security switch on the settings page is on. The two places read different fields, so the display can disagree.
3. Which actions send a scan
Auto-scan listens for “this branch has a new commit”. A command-line git push is one way that happens. Editing a file on the web and committing, or clicking merge on the pull request page, also puts a new commit on a branch and sends a scan job to AngusSecurity.
| Action | Scan? | What happens |
|---|---|---|
git push of a branch |
Yes | Scans the latest commit in that push |
| Edit a file on the web and commit | Yes | Handled the same way as a command-line push |
| Merge on the pull request page | Yes | Scans the new commit on the target branch |
| Only create a pull request | No extra scan for that action | An existing result is attached as it is |
| The same commit appears again within the default 10 minutes | Not sent again | A skip is recorded |
| The repository is archived | No | An archived repository is read-only, so a push does not go in |
A few rows need a longer note:
- When you merge on the pull request page, the new commit on the target branch is sent to AngusSecurity. A rebase merge that also puts a new commit on the source branch sends another scan.
- Creating a pull request does not scan again for that action. If the source branch already has a finished scan, Status checks on the pull request (the area that gathers each automatic check) attaches that result.
- The same commit, the same checks, and the same gate settings, inside the default 10 minutes, do not send another scan job. History records a skip. That is the dedupe. After you change a gate threshold, that dedupe does not hold the same commit back.
The scan runs asynchronously on AngusSecurity. The push itself does not wait for the scan to finish. If you want a new pull request to already show a scan result, either scan the source branch first, or turn on Block merge when the gate fails. With that switch on, a pull request that has no result yet shows “Waiting for the security check of commit …”.
4. Manual scans and scheduled scans
Scan now does not follow the Auto security scanning for this repo switch. On the repository security page, Scan now opens a dialog titled Trigger security scan. The note says: “Choose capabilities and scan level, then dispatch to AngusSecurity.”
The dialog pre-selects checks from the repository’s current security profile. For this repository the pre-selected checks are Secret scanning and License compliance. Code security, Dependency and artifact vulnerabilities, and Code quality are not selected. Scan level is Standard. You can also choose Quick or Deep. Branch is main. Force rescan (ignore dedupe) is off by default. Click Cancel if you only want to look at the options. Click Start scan when you want to run a catch-up scan.
If this scan matches a recent one, the page says “Skipped as duplicate of a recent scan (use force rescan)”. When you really need to scan again, select Force rescan (ignore dedupe).
Scheduled scans is configured in the tenant policy. It also ignores the repository auto-scan switch. At the scheduled time the system scans the default branch of repositories that already have a security profile, and it starts at most 20 repositories each time. Scheduled scans is off on this instance, so the cron box is not on the page.
5. Where to read the result
The trigger and status of each scan are on Scan history on the repository security page. Recent rows for e2e-license-gate are:
| Status | Trigger | Gate result | Branch |
|---|---|---|---|
| Completed | Push | Fail | e2e-git07@591d671 |
| Completed | Manual | Pass | main@d3ebc5a |
| Completed | Push | Fail | e2e-x03@d3ebc5a |
| Incomplete | Push | Skipped | e2e-x03@cb1dc56 |
| Completed | Push | Pass | e2e-git08@1f78310 |
The status column shows Completed or Incomplete. The gate result column shows Fail, Pass, or Skipped. Older rows note: “A newer scan of this branch exists. Earlier results may have been removed.” Every row has Open scan job. Open it to see the details of that job.
The AngusSecurity row on a pull request uses the latest scan of that commit that took part in the decision. Against the table above: the push scan of e2e-git08@1f78310 has gate result Pass, which matches the success note on #1. The push scan of e2e-x03@d3ebc5a is Fail, and a later manual scan of the same commit is Pass, so the check row on #4 says the vulnerability gate passed.
Scan history under Security in the sidebar is the same kind of list across repositories. Triggers there also include Schedule. This repository’s history has no scheduled scan yet.
6. What to check when a scan never starts
| What you see | Cause | What to do |
|---|---|---|
| “AngusSecurity is not connected” | The integration is not provisioned | A system admin provisions it as in section 1 |
| Config enabled is Off | The deployment config is off | Set angus.git.external-security.enabled=true and restart |
| Platform reachable is Unreachable | AngusGit cannot reach AngusSecurity | Check that AngusSecurity is running, and that the address and network work |
| A new commit appears, and history has no new row | Auto security scanning for this repo is off, or no check is on | Turn on the master switch and keep at least one check |
| History shows a skip | Within the default 10 minutes, the same commit and the same settings were already scanned | Run a manual scan and select force rescan |
| History status is Failed | AngusSecurity failed while fetching the code or running the scan | Click Open scan job and read the cause on AngusSecurity |
| History shows Incomplete | This scan did not get a full result | Scan once more |
When a scan result is incomplete, the note on the matching pull request is “Security check of commit … is incomplete. Run the check again”.
Common questions
Will a scan on every push make the push slow?
The push stays the same speed, because the scan runs asynchronously and does not hold the push. The same commit is not scanned again inside the default 10 minutes when the checks and the gates are unchanged.
Can I scan only main and skip feature branches?
That option is not available. Auto-scan follows whichever branch received the new commit. There is no switch to exclude a branch. The scan of a feature branch is what the AngusSecurity row on the pull request uses.
If auto-scan is on, will the merge be blocked?
Auto-scan only starts the scan and records the result. Blocking the merge also needs Block merge when the gate fails. The example repository has both switches on. The tenant default leaves block-merge off, so a new repository starts with it off.
Summary
An automatic scan after a new commit needs both the instance and the repository configured. On this instance, Management → Security settings already shows config enabled and the platform reachable. Auto security scanning for this repo is on for xlliu/e2e-license-gate, with Code security, Secret scanning, and License compliance on, and Dependency and artifact vulnerabilities and Code quality off. After that, git push, a commit from the web page, and a pull request merge each send a scan job to AngusSecurity when a branch gets a new commit. Creating a pull request does not add another scan. Scheduled scans are off. To catch up, open the manual scan dialog, confirm the checks and the branch, and click Start scan.
Security scanning is available on Team, Enterprise, and Cloud Service. Community has no Security menu.
Conclusion: After the instance is connected to AngusSecurity and the repository has Auto security scanning for this repo turned on, each new commit on a branch is sent to AngusSecurity. Whether the merge is blocked depends on Block merge when the gate fails.
Top comments (0)