GitHub triggers to block pull requests with vulnerabilities
You can create GitHub event triggers to support a variety of STO workflows and use cases. This topic describes how to do the following:
- Trigger an STO pipeline that detects vulnerabilities and blocks merging when a pull request targets a protected branch and/or updates specific files in the repo.
- Include a keyword in a review comment to trigger a new scan if a previous pipeline execution failed.
- Set branch protection rules that block pull requests if the STO pipeline fails.
The following steps outline the basic workflow.
-
Create a trigger for your Harness pipeline.
This should automatically register an outbound webhook in your Git repo.
-
Set up the failure criteria for your STO pipeline.
-
Create a pull request to test the webhook and trigger.
-
Add a branch protection rule to ensure that the pull request cannot be merged if the Harness pipeline fails.
Before you begin
These workflows require the following:
- A Harness connector to your GitHub account
- A Harness pipeline with a code-repository scan step such as Semgrep
- The Codebase in your pipeline should point to the Git repo that you want to scan
Create the Harness trigger
The following sections describe two triggers that can be very useful in the context of STO scanning:
Trigger on a changed file
You can specify a trigger that says: If a pull request updates any of these files, run the pipeline and scan the repo.
This type of trigger supports uses cases such as:
-
If the pull request updates any file that matches the trigger filter, run a SAST scan and block the PR if the scan results meet the failure criteria.
-
If the pull request updates a specific file of interest, such as a
pom.xml
workspace file, run an SCA scan and block the PR if the scan results meet the failure criteria.
Trigger setup
-
Go to your STO pipeline, select Triggers (top right), and add a new trigger.
-
Set up the trigger as follows.
Configuration
-
Connector to your GitHub account
-
Repository name
-
Event = Pull Request
-
Actions to trigger the pipeline
Condition
The following conditions are the most relevant to this workflow. You can add other conditions as needed. Triggers are complex filters in which all conditions are AND-ed together.
-
Target Branch This should match your target baseline, such as
main
. -
Changed Files The files that trigger the STO pipeline if they have updates in the PR. You can specify multiple files using the operators In, Not In, and Regex.
Here's a simple example: trigger a build if a PR seeks to update a specific pom.xml
in the main
branch.
![Trigger a pipeline execution when a PR updates a specific file in the main branch](/assets/images/changed-file-condition-example-simple-cf4d728ced44a29ea4ab24b59b7c73d8.png)
Pipeline input
The pipeline input should be configured correctly, with Build Type set to Git Pull Request.
Test the trigger
After you create the trigger, proceed to Set up the failure criteria.
YAML trigger example
trigger:
name: sast-test-trigger
identifier: sasttesttrigger
enabled: true
encryptedWebhookSecretIdentifier: ""
description: ""
tags: {}
orgIdentifier: default
stagesToExecute: []
projectIdentifier: default
pipelineIdentifier: triggertestupdatepom
source:
type: Webhook
spec:
type: Github
spec:
type: PullRequest
spec:
connectorRef: my_github_connector
autoAbortPreviousExecutions: false
payloadConditions:
- key: changedFiles
operator: Equals
value: /full/path/to/pom.xml
- key: targetBranch
operator: Equals
value: main
headerConditions: []
repoName: dvpwa-djb
actions:
- Open
- Reopen
inputYaml: |
pipeline:
identifier: triggertestupdatepom
properties:
ci:
codebase:
build:
type: PR
spec:
number: <+trigger.prNumber>
Trigger on a PR review comment
You can specify a trigger that says: If a reviewer includes a specific keyword in a pull-request review comment, run the pipeline and scan the repo.
This type of trigger is useful when a pipeline execution fails for reasons other than the failure criteria you specified for the pipeline. If the STO scan doesn't finish in the original execution, a reviewer can add a review comment with a keyword such as RERUN_STO_PIPELINE
.
Trigger setup
-
Go to your STO pipeline, select Triggers (top right), and add a new trigger.
-
Set up the trigger as follows.
Configuration
-
Connector to your GitHub account
-
Repository name
-
Event = Issue Comment
-
Actions, such as Create and Edit, to trigger the scan. You can also select All actions to allow reviewers to trigger a scan at any time.
Condition
The following conditions are the most relevant to this workflow. You can add other conditions as needed. Triggers are complex filters in which all conditions are AND-ed together.
-
Target Branch This should match your target baseline.
-
Enter the following JEXL condition with the keyword to trigger a new scan:
<+trigger.payload.comment.body>.contains("RERUN_STO_SCAN")
Pipeline input
The pipeline input should be configured correctly, with Build Type set to Git Pull Request.
Test the trigger
After you create the trigger, proceed to Set up the failure criteria.
YAML trigger example
trigger:
name: dvpwa-issue-comment-KEYWORD
identifier: dvpwaissuecommentKEYWORD
enabled: false
encryptedWebhookSecretIdentifier: ""
description: ""
tags: {}
orgIdentifier: default
stagesToExecute: []
projectIdentifier: sto_tutorials
pipelineIdentifier: prtest
source:
type: Webhook
spec:
type: Github
spec:
type: IssueComment
spec:
connectorRef: my_github_connector
autoAbortPreviousExecutions: false
payloadConditions:
- key: targetBranch
operator: In
value: master, develop
headerConditions: []
jexlCondition: <+trigger.payload.comment.body>.contains("RERUN_STO_SCAN")
repoName: dvpwa
actions: []
inputYaml: |
pipeline:
identifier: prtest
properties:
ci:
codebase:
build:
type: PR
spec:
number: <+trigger.prNumber>
Set up the failure criteria
You can configure your Harness pipeline to fail if the scan finds vulnerabilities that match a specified set of criteria. You can use one of two methods:
-
Every STO scan step has a
fail_on_severity
setting that fails the step if a scan detects issues with the specified severity or higher. You can also create exemptions ("Ignore rules") for specific issues to override this behavior. -
You can use Harness Policy as Code to write and enforce policies against your security tests, and to block your pipelines if a security test has any issues that violate those policies. STO includes a set of predefined templates for blocking pipelines based on issue severity, reference ID, CVE age, title, and number of occurrences.
Test the outbound webhook and trigger
Verify the webhook in GitHub
Once you add a trigger to your pipeline, your Git service provider should create a webhook for the trigger automatically. This is true for all non-custom webhooks and all Git providers supported by Harness.
-
Go to your GitHub account, and then select Settings > Webhooks.
-
If you don't see a webhook, you can add one manually.
For more information, go to Register the webhook in the Git provider.
Test the webhook and trigger
To test your trigger, update your GitHub repo to verify that the trigger works as intended.
-
To verify the changed-file trigger described above:
- Go to the root branch you specified in the trigger.
- Update the file you specified in the trigger. Then create a pull request in a new branch.
-
To verify the review-comment trigger described above, create a pull request and then add a review comment with the keyword you specified.
- Go to the root branch you specified in the trigger.
- Create a pull request in a new branch.
- Add a review comment with the keyword you specified in the trigger.
You should now see the following:
-
In the GitHub repo, the request and response were successful.
-
In the Pipeline Executions page of your Harness pipeline, the trigger starts a new execution.
-
In the GitHub pull request, the pipeline execution appears as an automated check.
If the trigger doesn't work as intended, go to Troubleshoot Git event triggers.
Add a branch protection rule for the Git repo
The final step is to ensure that a PR cannot be merged if the STO pipeline fails. To do this, you create a protection rule for your root branch.
The following steps describe a simple setup in GitHub. For more information, go to Managing a branch protection rule in the GitHub documentation.
If you're using a different SCM, go to the SCM documentation and search for branch protection
.
Add the protection rule
-
Go to your GitHub repo and select Settings > Branches > Add Rule.
-
In Branch name pattern, add a string or regular expression for the branch or branches you want to protect. This should match your target baseline.
-
Select Require a pull request before merging and Require Approvals. This isn't required, but it's good practice.
-
Select Require status checks to pass before merging.
-
In the search field below, enter the first characters of the check name and then select the check.
-
Configure any other settings as appropriate.
-
Scroll to the bottom of the page and save your rule.
Test the protection rule
Now that you've set up the rule, trigger another Harness pipeline execution and fail it to verify that the rule stops the pull request.
To verify the branch protection rule, you must ensure that your STO pipeline fails. To configure your pipeline to fail temporarily, you can do one of the following:
- Set Fail on Severity to Low in the scan step of your pipeline. Then scan a repo with known vulnerabilities.
- Add a temporary Run step to your pipeline with the command
exit(1)
.
-
Trigger another pipeline execution.
-
For the changed-file trigger described above, make and push a change. Then create a pull request.
-
For the review-comment trigger described above, add a review comment with the keyword you specified.
-
-
Now, merging is blocked if the Harness pipeline fails.
For more information
-
The Harness platform docs include extensive information about triggers. The following topics are highly relevant to STO use cases:
-
For detailed information about outbound webhooks and branch protection rules, go to the docs for your source code management (SCM) provider. This topic describes a few simple GitHub workflows, but these topics are outside the scope of Harness documentation.