GitHub Action Reference

Section: ReferenceOrder: 4

Complete reference for the noxtara/run GitHub Action used to run security scans in GitHub Actions workflows.

Action Overview

uses: noxtara/run@v1

This action installs the Noxtara CLI and runs security scans on your repository code or mobile application files.

Requirements:

• Linux runner (ubuntu-24.04 or later)
• Node.js 24 (automatically installed)

Action Inputs

Input	Required	Default	Description
api-key	Yes	—	Noxtara API key for authentication
base-url	No	https://app.noxtara.com/api/main/client	Noxtara API base URL
working-directory	No	.	Directory to scan (relative to repository root)
cli-version	No	latest	Version of @noxtara/cli to install
auto-pr	No	true	Create PRs to update config with new entry IDs
github-token	No	github.token	GitHub token for creating PRs

Input Details

api-key

Your Noxtara API key for authenticating scan requests.

• Required: Yes
• Type: String
• Recommendation: Store as repository secret (use secrets.NOXTARA_API_KEY syntax)

Example:

with:
  api-key: YOUR_API_KEY_HERE

Note: Replace YOUR_API_KEY_HERE with your actual secret reference.

base-url

The base URL for your Noxtara API endpoint.

• Required: No
• Default: https://app.noxtara.com/api/main/client
• Type: String

For self-hosted or regional deployments, specify your custom URL:

with:
  base-url: https://your-instance.noxtara.com/api/main/client

working-directory

The directory to scan, relative to the repository root.

• Required: No
• Default: . (repository root)
• Type: String

Use this when your code is in a subdirectory:

with:
  working-directory: ./packages/backend

cli-version

Specific version of the Noxtara CLI to install.

• Required: No
• Default: latest
• Type: String

Pin to a specific version for reproducible builds:

with:
  cli-version: "1.2.3"

auto-pr

Automatically create pull requests to update your noxtara.yaml with new entry IDs.

• Required: No
• Default: true
• Type: Boolean (as string: "true" or "false")

When enabled, after the first scan creates a new entry, the action creates a PR adding the entryId to your config file. This links future scans to the same dashboard entry.

Disable if you manage entry IDs manually:

with:
  auto-pr: "false"

github-token

GitHub token for creating pull requests when auto-pr is enabled.

• Required: No
• Default: github.token
• Type: String

The default token is usually sufficient. Use a custom token if you need to trigger workflows from the created PR:

with:
  github-token: YOUR_PAT_HERE

Note: Replace YOUR_PAT_HERE with your actual GitHub token reference.

Required Permissions

The workflow job needs these permissions when using auto-pr: true:

permissions:
  contents: write # Required to create PRs
  pull-requests: write # Required to create PRs

Workflow Examples

Scheduled Daily Scan

Run a security scan every day at midnight:

name: Daily Security Scan

on:
  schedule:
    - cron: "0 0 * * *"
  workflow_dispatch:

jobs:
  scan:
    runs-on: ubuntu-24.04
    permissions:
      contents: write
      pull-requests: write

    steps:
      - uses: actions/checkout@v6
      - uses: noxtara/run@v1
        with:
          api-key: YOUR_API_KEY_HERE

Scan on Pull Request

Analyze code when pull requests are opened or updated:

name: PR Security Scan

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  scan:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v6
      - uses: noxtara/run@v1
        with:
          api-key: YOUR_API_KEY_HERE
          auto-pr: "false" # Don't create PRs on PR scans

Scan Specific Directory

Analyze only a subdirectory of your repository:

name: Backend Scan

on:
  push:
    branches: [main]
    paths:
      - "backend/**"

jobs:
  scan:
    runs-on: ubuntu-24.04
    permissions:
      contents: write
      pull-requests: write

    steps:
      - uses: actions/checkout@v6
      - uses: noxtara/run@v1
        with:
          api-key: YOUR_API_KEY_HERE
          working-directory: ./backend

Self-Hosted Noxtara Instance

Connect to a custom Noxtara deployment:

name: Security Scan

on:
  schedule:
    - cron: "0 0 * * *"

jobs:
  scan:
    runs-on: ubuntu-24.04
    permissions:
      contents: write
      pull-requests: write

    steps:
      - uses: actions/checkout@v6
      - uses: noxtara/run@v1
        with:
          api-key: YOUR_API_KEY_HERE
          base-url: YOUR_BASE_URL_HERE

Note: Replace YOUR_API_KEY_HERE and YOUR_BASE_URL_HERE with your actual configuration values.

Pinned CLI Version

Use a specific CLI version for reproducibility:

name: Security Scan

on:
  schedule:
    - cron: "0 0 * * *"

jobs:
  scan:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v6
      - uses: noxtara/run@v1
        with:
          api-key: YOUR_API_KEY_HERE
          cli-version: "1.0.0"

Configuration File Integration

The action reads scan settings from noxtara.yaml in your repository. A typical configuration:

baseUrl: "https://app.noxtara.com/api/main/client"
scan:
  scaSast:
    from: .
    ignore:
      - "node_modules/**"
      - "dist/**"

The action uses these settings unless overridden by inputs (only base-url and working-directory can be overridden via inputs).

Error Handling

The action fails if:

• The runner OS is not Linux
• The API key is invalid or missing
• The configuration file has errors
• No scan configuration is found in noxtara.yaml

Check the Actions logs for detailed error messages.

Action Source

The action is defined in the noxtara/run repository. It performs these steps:

1. Validates the runner is Linux
2. Sets up Node.js 24
3. Installs @noxtara/cli globally
4. Runs noxtara scan in the working directory
5. Creates a PR with the new entry ID if auto-pr is enabled