Integrating CI/CD tools with Astra ensures that your security vulnerabilities are automatically scanned during your development pipeline, helping keep your projects secure with minimal effort.

Available CI/CD Integrations

GitHub
GitLab
Jenkins
Bitbucket
Azure
CircleCI

If you use a a different CI/CD tool, you can refer to the generic steps for starting audits via a simple API call via curl

You can configure your CI/CD pipeline to fail if high severity vulnerabilities are found

Step-by-Step Guide to CI/CD Integration

To get started with an integration:

Login to your Astra Dashboard
Navigate to the Pentest menu item, and open the project you want to audit from your CI/CD
Go to the Integrations, and click on the icon of the CI/CD tool you use
Activate the Integration, and follow the steps on the screen (or below)

GitHub

Select GitHub app
Choose the mode for the audit - Automated or Manual
Sign in to your GitHub account and open the repository for the chosen project
Go to Settings, select secrets and click on New repository secret
Set name as ASTRA_ACCESS_TOKEN = <can be copied from dashboard> and set the value as the token you copied from the dashboard
Add a new step in your YAML file. We recommend to add this after the deploy step:

- shell: bash
  name: Run an Astra Pentest
  env:
    ASTRA_ACCESS_TOKEN: ${{ secrets.ASTRA_ACCESS_TOKEN }}
    ASTRA_PROJECT_ID: COPY-FROM-DASHBOARD
    ASTRA_AUDIT_MODE: automated
  run: |
    wget -O - https://git.io/JSHtC | bash

Gitlab

Select the GitLab app
Choose the mode for the audit - Automated or Manual
Sign in to your GitLab account and open the repository for the chosen Astra project
Go to Settings & choose CI/CD from the left navigation bar
Go to Variables, click on Expand and click on Add variable
Set ASTRA_ACCESS_TOKEN = <can be copied from dashboard> and ASTRA_PROJECT_ID = <can be copied from dashboard> variables, uncheck Mask Variable & Protect variable both
Add the following step in your YAML file

pentest-job:
  stage: .post
  variables:
    ASTRA_AUDIT_MODE: automated
  script:
    - wget -O - https://git.io/JSHtC | bash

Jenkins

Select the Jenkins app
Choose the mode for the audit - Automated or Manual
Add the following variables and stages to the Jenkins file of your repository (replace the values in ASTRA_PROJECT_ID and ASTRA_ACCESS_TOKEN as seen in the dashboard):

pipeline {
  agent any
  environment {
    ASTRA_PROJECT_ID = 'redacted'
    ASTRA_ACCESS_TOKEN = 'redacted'
    ASTRA_AUDIT_MODE = 'automated'
  }
  stages {
    stage('build') {
      steps {
        sh 'wget -O - https://git.io/JSHtC | bash'
      }
    }
}
}

BitBucket

Select the BitBucket app
Choose the mode for the audit - Automated or Manual
Sign in to your Bitbucket account
Click on Repositories and open the repository for the chosen project
Click on Repository settings. Then, scroll down in the left navbar till Pipelines & click on Repository variables
Add ASTRA_ACCESS_TOKEN = <can be copied from dashboard> and ASTRA_PROJECT_ID = <can be copied from dashboard> variables, uncheck Secured for both
Add a new step in the pipeline YAML file. We recommend to add this after the deploy stage.

- step:
    name: 'Astra Pentest Job'
    script:
      - export ASTRA_AUDIT_MODE="automated"
      - wget -O - https://git.io/JSHtC | bash

Azure

Select the Azure app
Choose the mode for the audit - Automated or Manual
Go to https://dev.azure.com and sign in to your account
Choose your organization and choose your project from the Projects tab
Click on Pipelines in the left navbar, and click on the pipeline for which you want to set up the pentest. Then Click on Edit
In the pipeline YAML page, click on Variables
Add ASTRA_ACCESS_TOKEN = <can be copied from dashboard> and ASTRA_PROJECT_ID = <can be copied from dashboard> variables, do not select Keep this value secret
Add a new step in the pipeline YAML file. We recommend to add this after the deploy stage.

variables:
  ASTRA_AUDIT_MODE: "automated"
steps:
  - script: |
      wget -O - https://git.io/JSHtC | bash
    displayName: 'Run an Astra Pentest'

CircleCI

Select the CircleCI app
Choose the mode for the audit - Automated or Manual
Sign in to your CircleCI account and open the repository for the chosen Astra project
Add the environment variables to the CircleCI project, as provided in the Astra dashboard.

Click on Mechanical Wheel Icon

Navigate to Environment Variables and click on Add Variable
Ensure the variable names are named as follows : `ASTRA`95ACCESS_TOKEN*, ASTRA_PROJECT_ID (values can be copied from the dashboard)
Configure your config.yml in .circleci folder as follows:

Add the following snippet to jobs: section

astra-pentest-trigger:
    machine:
      image: ubuntu-2004:202008-01
    environment:
      ASTRA_AUDIT_MODE: automated
    steps:
        - run:
            command: wget -O - https://git.io/JSHtC | bash

Add the `astra`45pentest-trigger* line to jobs: of workflow: section

Example:

workflows:
    version: x
    workflow-name:
        jobs:
            - job 1
            - job 2
            - astra-pentest-trigger

How to configure the pipeline

By setting specific environment variables, you can configure your pipeline to either fail when vulnerabilities are detected, or simply trigger a scan without waiting for results.

Setting the ASTRA_JOB_EXIT_STRATEGY

Define how your CI/CD pipeline should behave based on scan results:

Trigger a scan without waiting for results:

This will trigger the scan but return success immediately without waiting for vulnerabilities to be found.

ASTRA_JOB_EXIT_STRATEGY='always_pass'

Fail the pipeline if vulnerabilities are detected:

This ensures the pipeline fails when vulnerabilities are found. You can configure the exit criterion by setting ASTRA_JOB_EXIT_CRITERION as described in the section below.

The scan runs for a maximum duration determined by ASTRA_JOB_EXIT_REFETCH_INTERVAL and ASTRA_JOB_EXIT_REFETCH_MAX_RETRIES.

ASTRA_JOB_EXIT_STRATEGY='fail_when_vulnerable'

Wait until the scan finishes:

The pipeline waits until the scan completes before proceeding. This will not fail the pipeline even if vulnerabilities are found.

ASTRA_JOB_EXIT_STRATEGY='wait_for_completion'

For the fail_when_vulnerable and wait_for_completion modes, Astra enforces a soft limit to prevent CI/CD jobs from being held indefinitely. The default timeout is 10 minutes. If the scan does not complete in this timeframe, Astra stops checking for status updates and logs a message.

Configuring the Refetch Interval and Maximum Retries

For fail_when_vulnerable and wait_for_completion modes, Astra periodically checks the scan status before deciding on the next action in the pipeline. You can adjust the following environment variables:

# How often the CI/CD job should check for a status update
ASTRA_JOB_EXIT_REFETCH_INTERVAL=30

#How many times should we check for the status
ASTRA_JOB_EXIT_REFETCH_MAX_RETRIES=50

Example Calculation

If ASTRA_JOB_EXIT_REFETCH_INTERVAL=30 and ASTRA_JOB_EXIT_REFETCH_MAX_RETRIES=50, the pipeline will check for status 50 times with a 30-second interval, totaling 1500 seconds (25 minutes).

You can modify these values as needed to fit your pipeline execution time.

Defining the Exit Criterion

You can specify a condition for when the pipeline should fail, based on vulnerability severity:

ASTRA_JOB_EXIT_CRITERION="severityCount[\\\"high\\\"] > 0 or severityCount[\\\"critical\\\"] > 0"

This ensures the pipeline fails if any high or critical severity vulnerabilities are found.

Full Example Configuration

By following these steps, your CI/CD pipeline will automatically fail if vulnerabilities meeting the defined severity criteria are detected during the Astra scan.

ASTRA_JOB_EXIT_STRATEGY='fail_when_vulnerable'

ASTRA_JOB_EXIT_REFETCH_INTERVAL=10

ASTRA_JOB_EXIT_REFETCH_MAX_RETRIES=10

ASTRA_JOB_EXIT_CRITERION="severityCount[\\\"high\\\"] > 0 or severityCount[\\\"critical\\\"] > 0"

For further assistance or troubleshooting, please contact our support team.

Updated on: 20/03/2025