--- title: "GitHub Actions" slug: "github-actions-v2-1" description: "Integrate Traceable’s API security testing with GitHub Actions (v2) to automate vulnerability scans in CI/CD workflows." tags: ["GitHub Actions", "Security Scans", "Traceable Integration"] updated: 2026-09-08T07:48:15Z published: 2026-09-08T07:48:15Z canonical: "traceabledocs.document360.io/github-actions-v2-1" --- > ## Documentation Index > Fetch the complete documentation index at: https://traceabledocs.document360.io/llms.txt > Use this file to discover all available pages before exploring further. # GitHub Actions GitHub Actions is an automation and workflow tool provided by GitHub. It allows developers to automate tasks and define workflows using YAML files. Workflows are triggered by events such as code pushes or pull requests and can include a series of actions. Actions are reusable tasks that can be combined to create workflows. GitHub Actions is commonly used for continuous integration/continuous deployment (CI/CD) pipelines. Traceable integrates with GitHub Actions by running security scans. Traceable helps you identify vulnerabilities in the early stages of SDLC, giving you more time and context to prioritize vulnerability mitigation and build secure APIs. The topic explains how to configure and use Traceable xAST CI/CD integration and how to run the scan during the build step. ## What you will learn from this topic By the end of this topic, you will be able to understand: - The available Traceable AST actions, and their usage. - The inputs for the scan, queue-scan, report, and gate GitHub Actions. --- ## Before you begin Make a note of the following before integrating GitHub Actions with Traceable: - Make sure that you have an active account and repository on GitHub. - Make sure you have a basic understanding of GitHub Actions and workflows. For information, see [GitHub Actions documentation](https://docs.github.com/en/actions). - Make sure you obtain the platform access token that the CLI uses to authenticate. For more information, see [Public APIs](https://docs.traceable.ai/docs/public-apis). - Make sure you create the scan that the workflow runs, and note its name or ID. For more information, see [Creating a Scan](https://docs.traceable.ai/docs/creating-scan). - Make sure you have updated the Traceable CLI version to *2.8.0 or later* installed in your CI system (here, GitHub). For more information, see [CLI Pre-checks and Installation](/v1/docs/cli-installation). > [!NOTE] > Note > > To upgrade the Traceable CLI to the latest version, re-run the installation script. The script will upgrade the existing installation in place without removing configuration or credentials. For more information, see [CLI Pre-checks and Installation](/v1/docs/cli-installation). --- ## Integration Integrate Traceable xAST into your GitHub workflows using a GitHub Action. The integration provides inputs and outputs, along with example workflows to help you get started. For more information, see [GitHub Integration](https://docs.traceable.ai/docs/github). ### Available GitHub Actions All the GitHub Actions by Traceable are currently available in [GitHub repository](https://github.com/Traceableai/traceable-github-actions). Each Traceable `ast-action`wraps a single Traceable CLI command, so you build a workflow by adding the steps that your pipeline requires. The following table describes the available actions: | Action | CLI command | Purpose | | --- | --- | --- | | `Traceableai/ast-action/scan@v2` | `traceable ast scan initAndRun` | Runs a local scan. | | `Traceableai/ast-action/queue-scan@v2` | `traceable ast scan queue` | Queues a scan on remote runners. | | `Traceableai/ast-action/report@v2` | `traceable ast scan report` | Generates and publishes a report. | | `Traceableai/ast-action/gate@v2` | `traceable ast scan getEvaluationResult` | Passes or fails the pipeline. | > [!NOTE] > Note > > Use the `scan` action when the GitHub runner can reach the target APIs directly, and the `queue-scan` action when the target is reachable only from inside your own network (runner is deployed remotely). For more information on the commands behind these actions, see [Queue scan to a remote runner](/v1/docs/run-scan-from-cli#queue-a-scan-to-a-runner). --- ## Understand the inputs Each GitHub Action has its own set of inputs that either select a scan or a CLI version to use, or control what the action writes back to the workflow. The following sections describe the inputs for each action: - [Inputs for the scan action](/v1/docs/github-actions-v2#inputs-for-the-scan-action) — The `scan` action runs a scan on the GitHub runner. - [Inputs for the queue-scan action](/v1/docs/github-actions-v2#inputs-for-the-queuescan-action) — The `queue-scan` action dispatches a scan to a remote runner. - [Inputs for the report action](/v1/docs/github-actions-v2#inputs-for-the-report-action) — The `report` action generates and publishes a report. - [Inputs for the gate action](/v1/docs/github-actions-v2#inputs-for-the-gate-action1) — The `gate` action passes or fails a pipeline. ### Inputs for the scan action The `scan` action runs a scan on the GitHub runner. The following table describes its inputs: | Input | Description | Required | Default | | --- | --- | --- | --- | | `scan_name` | The name of the scan. | No | `''` | | `scan_id` | The scan configuration ID. | No | `''` | | `client_scan_token` | The platform access token. | Yes | — | | `traceable_server` | The platform URL. | Yes | — | | `cli_version` | The Traceable CLI version to be used. | No | `latest` | | `additional_cli_options` | Freeform CLI flags that are appended to the command. | No | `''` | | `summary` | Writes the scan output to the GitHub job summary. | No | `true` | > [!NOTE] > Note > > You must provide at least one of `scan_name` or `scan_id`. ### Inputs for the queue-scan action The `queue-scan` action dispatches the scan to remote runners. Its inputs mirror those of the `scan` action, with additional inputs for runner selection and wait behavior, as described in the following table: | Input | Description | Required | Default | | --- | --- | --- | --- | | `scan_name` | The name of the scan. | No | `''` | | `scan_id` | The scan configuration ID. | No | `''` | | `client_scan_token` | The platform access token. | Yes | — | | `traceable_server` | The platform URL. | Yes | — | | `cli_version` | The Traceable CLI version to be used. | No | `latest` | | `runner_ids` | A comma-separated list of runner IDs. | No | `''` | | `wait` | Waits for the scan to complete. | No | `true` | | `wait_timeout` | The maximum wait time in minutes. | No | `''` | | `additional_cli_options` | Extra CLI flags. | No | `''` | | `summary` | Writes the output to the job summary. This applies only when `wait` is `true`. | No | `true` | > [!NOTE] > Note > > You must provide at least one of `scan_name` or `scan_id`. ### Inputs for the report action The `report` action generates a report for a scan run, regardless of whether it was successfully completed or aborted. The following table describes its inputs: | Input | Description | Required | Default | | --- | --- | --- | --- | | `id` | The scan run ID. Traceable auto-resolves it when you omit it. | No | `''` | | `client_scan_token` | The platform access token. | Yes | — | | `traceable_server` | The platform URL. | Yes | — | | `cli_version` | The Traceable CLI version to be used. | No | `latest` | | `output_format` | The report format. | No | `md` | | `additional_cli_options` | Extra CLI flags. | No | `''` | > [!NOTE] > Note > > - `scan-id` is the configuration ID of the scan. `id` the scan run ID. > - The `output_format` input determines the report destination. Markdown reports go to `$GITHUB_STEP_SUMMARY`, where they appear on the workflow run page, while every other format goes to the action log. > - To save a non-Markdown report to a file, use `--output-file <path>` through `additional_cli_options`. ### Inputs for the gate action The `gate` action either passes or fails the pipeline. The following table describes its inputs: | Input | Description | Required | Default | | --- | --- | --- | --- | | `id` | The scan run ID. Traceable auto-resolves it when you omit it. | No | `''` | | `client_scan_token` | The platform access token. | Yes | — | | `traceable_server` | The platform URL. | Yes | — | | `cli_version` | The Traceable CLI version to be used. | No | `latest` | | `additional_cli_options` | Extra CLI flags. | No | `''` | The outcome of this step depends on the evaluation policy configured for the scan. For the codes that the action returns, see [Exit codes](/v1/docs/cli-usage#exit-codes). --- ## Additional CLI options The `additional_cli_options` input appends flags to the underlying CLI command, allowing you to apply scan overrides and other CLI options from a workflow. For more information, see [Sample GitHub Actions workflows](/v1/docs/github-actions-v2-1#sample-github-actions-workflows). You can pass scan overrides, such as the target URL, authentication hooks, and API specifications, along with runner selection, wait behavior, and output flags. For more information, see [Scan Overrides](/v1/docs/clone-scan-overrides) and [Run a Scan from CLI](/v1/docs/run-scan-from-cli). General CLI settings, such as `--loglevel`, are available for every action. For more information, see [General CLI options](/v1/docs/cli-installation#general-cli-options) for details. > [!NOTE] > Note > > File paths passed that you provide as part of these flags are relative to the repository root. --- ## Sample GitHub Actions workflows The following workflows show a Traceable pipeline that scans directly from the GitHub runner, and a second pipeline that dispatches the scan to a runner inside your own network. ### Local scan with overrides The following workflow runs a scan with a local runner as a GitHub Action: ```yaml name: API Security Scan on:  pull_request: jobs:  ast-scan:    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@v4      - name: Run AST scan        uses: Traceableai/ast-action/scan@v2        with:          scan_name: 'pr-security-scan'          client_scan_token: ${{ secrets.TRACEABLE_TOKEN }}          traceable_server: ${{ secrets.TRACEABLE_SERVER }}          summary: 'false'          additional_cli_options: |            --target-url ${{ steps.deploy.outputs.url }}            --openapi-spec-files ./api/openapi.yaml            --hook-names ci-auth-hook      - name: Publish report        uses: Traceableai/ast-action/report@v2        with:          client_scan_token: ${{ secrets.TRACEABLE_TOKEN }}          traceable_server: ${{ secrets.TRACEABLE_SERVER }}      - name: Gate pipeline        uses: Traceableai/ast-action/gate@v2        with:          client_scan_token: ${{ secrets.TRACEABLE_TOKEN }}          traceable_server: ${{ secrets.TRACEABLE_SERVER }} ``` ### Queued scan with a remote runner The following workflow queues a scan to named runners that are remote, but reachable within your project network, as a GitHub action: ```yaml name: API Security Scan (Remote Runner) on:  push:    branches: [main] jobs:  ast-scan:    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@v4      - name: Queue AST scan        uses: Traceableai/ast-action/queue-scan@v2        with:          scan_name: 'production-scan'          client_scan_token: ${{ secrets.TRACEABLE_TOKEN }}          traceable_server: ${{ secrets.TRACEABLE_SERVER }}          runner_ids: 'prod-runner-1,prod-runner-2'          wait: 'true'          wait_timeout: '30'          additional_cli_options: |            --target-url https://api.production.example.com      - name: Publish report        uses: Traceableai/ast-action/report@v2        with:          client_scan_token: ${{ secrets.TRACEABLE_TOKEN }}          traceable_server: ${{ secrets.TRACEABLE_SERVER }}          output_format: sarif          additional_cli_options: --output-file results.sarif      - name: Gate pipeline        uses: Traceableai/ast-action/gate@v2        with:          client_scan_token: ${{ secrets.TRACEABLE_TOKEN }}          traceable_server: ${{ secrets.TRACEABLE_SERVER }} ``` ### Triggers A trigger is the event that starts your workflow, such as a push, a pull request, or a manual run. GitHub workflows support a wide range of triggers. For more information, see [Events that trigger workflows](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows). --- ## Reports The following is a sample AST report once the scan is executed. The report shows various details about the scan, vulnerabilities and the scan evaluation status. ![Sample scan report](https://cdn.document360.io/24f14f07-13d1-4684-8fae-6d8f811768ee/Images/Documentation/report.png) Scan report You can view the report under the **Actions** tab in your GitHub repository: ![View your scan report in GitHub repository](https://cdn.document360.io/24f14f07-13d1-4684-8fae-6d8f811768ee/Images/Documentation/find your report.png) View scan report in GitHub repository