Configuration & CI Integration

STAR is configured through environment variables — no config file, no UI toggle. Below are the variables you are most likely to set; Running STAR in CI shows how to wire them per platform. For the complete reference, see the bright-agent-dist README.

Secrets (every run)

AI / Inference Providers

STAR works with any OpenAI-compatible API (OpenAI, GitHub Models, Ollama, self-hosted gateways). Set AI_MODEL to pick the model; a comma-separated list (e.g. gpt-4.1-mini,gpt-4.1) escalates to the next model if a phase fails.

Run Modes & Scan Scope

See Capabilities & Use Cases for how these map to pipeline triggers.

Other variables you may need

Comment steering (/bright-agent replies) passes guidance through BRIGHT_STEERING_* variables — the CI templates wire these; see Comment Steering.

Running STAR in CI

Running STAR in CI is a drop-in pipeline job: it checks out your repository, downloads the STAR binary, and runs it against the checked-out tree. STAR detects the trigger it was run from and adapts automatically — no separate "modes" to configure per pipeline.

📘

Templates live in the repo, not on this page

Every setup below copies a file from examples/ci/ in bright-agent-dist — the actual, versioned source. Copy the file from there rather than from a code block, so you always get the current template as STAR evolves.

Jump to: GitHub Actions · GitLab CI/CD · Azure Pipelines · Bitbucket Pipelines · CircleCI · Jenkins · Comment Steering

How it works, on every platform

1. Checkout — the job checks out your repository (STAR runs against that working copy; it doesn't clone).
2. Download & verify — the job downloads the pinned/latest STAR binary from bright-agent-dist releases and checks its SHA-256 checksum. Download it outside the checkout — STAR commits with git add -A, so a binary left inside the repo would get committed into the fix PR.
3. Run — the job runs the binary with your secrets/variables as environment. STAR detects the tech stack, builds and starts the app, scans it, and generates fixes.
4. React — on a pull/merge request, STAR reacts directly into it: commits verified fixes to its head branch, posts/updates a single summary comment, and sets a commit status — "Marked Safe by Bright Agent" when nothing is left open.

The core secrets every platform needs are BRIGHT_TOKEN and an inference token (OPENAI_API_KEY or INFERENCE_TOKEN + INFERENCE_URL) — see Secrets. REPO_ACCESS_TOKEN is only a separate secret on GitLab, Bitbucket, CircleCI, and Jenkins; GitHub Actions and Azure Pipelines use their built-in CI tokens automatically.

Runner prerequisites

Every runner needs Docker, Docker Compose, Git, curl, and sha256sum. See Prerequisites for platform-specific notes (CircleCI's machine executor, GitLab's Docker-on-host requirement, etc.).

Scoping & scheduling

STAR automatically narrows the scan to the pull/merge request's diff whenever a base ref is available — see Scan scope and Run Modes & Scan Scope. Force behavior with SCAN_SCOPE=full or SCAN_SCOPE=changed.

A full scan builds and runs your whole application, which can take several minutes. Run STAR on a schedule (e.g. nightly) or on demand for full baselines, and let pull/merge-request triggers handle the fast, scoped runs — not on every single push.

GitHub Actions

One workflow covers every trigger: pull requests, manual runs, nightly scans, and /bright-agent comment steering.

Setup:

1. Copy examples/ci/github-actions.yml to .github/workflows/bright-agent.yml on your repository's default branch (required for comment steering — GitHub only triggers issue_comment workflows from the default branch).
2. Add repository secrets: BRIGHT_TOKEN, INFERENCE_TOKEN.
3. Add a repository variable: INFERENCE_URL.
4. Repo access uses the built-in GITHUB_TOKEN — no PAT required. (Caveat: commits/PRs made with GITHUB_TOKEN won't trigger your other workflows. Use a personal access token as REPO_ACCESS_TOKEN instead if you need the fix PR to run your CI.)

What it does: triggers on pull_request (opened/synchronize/reopened), issue_comment (for /bright-agent steering), workflow_dispatch (manual), and schedule (nightly). It checks out the PR head branch (or the triggering ref for manual/scheduled runs), downloads and checksum-verifies the STAR binary into the runner's temp directory, runs it, then reacts into the PR: commits fixes to its head branch, posts/updates a summary comment, and sets a Bright Agent commit status.

Trigger gates: on pull_request, only same-repo PRs run (GITHUB_TOKEN is read-only on forks, so a fork PR couldn't push fixes or comment anyway). On issue_comment, only a lowercase /bright-agent comment from a repo OWNER, MEMBER, or COLLABORATOR triggers a steering re-run — the workflow resolves the PR over the API and refuses fork PRs before checkout, so untrusted code never runs with your secrets. workflow_dispatch/schedule always run a full scan. See Comment Steering for the full model.

CodeQL SARIF validation (optional)

To have STAR confirm which CodeQL findings are actually exploitable instead of running the fix loop, copy examples/ci/github-actions-codeql-validation.yml to .github/workflows/bright-agent-validation.yml. It runs CodeQL analysis to produce a SARIF file, then runs STAR with RUN_MODE=validation and SARIF_PATH pointing at it — no fix loop, just a CodeQL → DAST confirmation summary posted to a PR. Compiled languages (Java, Go, C#, C++) need a real build step in place of CodeQL's autobuild if it can't handle your project. See SAST Validation for what this flow reports.

GitLab CI/CD

Works on GitLab.com or self-managed GitLab. Merge-request-scoped scans, scheduled/manual full scans, and /bright-agent comment steering.

Setup:

1. Copy examples/ci/.gitlab-ci.yml to .gitlab-ci.yml in your repository.
2. Add CI/CD variables (Settings → CI/CD → Variables; mask & protect them): BRIGHT_TOKEN, REPO_ACCESS_TOKEN, INFERENCE_TOKEN, INFERENCE_URL.
3. REPO_ACCESS_TOKEN must be a GitLab Personal Access Token or Project/Group Access Token with api scope and Developer role or higher — CI_JOB_TOKEN can't create merge requests or notes, so it isn't sufficient.

🚧

Runner requirement

The started app must be reachable on localhost. Use a runner that runs Docker on its host (a shell executor on a Docker host, or a docker executor with docker-in-docker configured) — a plain docker executor without dind/networking cannot reach the app.

What triggers a run: a merge request (merge_request_event) runs an MR-scoped scan narrowed to the MR diff (STAR reads CI_MERGE_REQUEST_TARGET_BRANCH_NAME); a schedule (create one under CI/CD → Schedules) or web/manual run does a full scan; a trigger event carries /bright-agent comment steering (see below).

PR/MR reaction: STAR commits verified fixes to the MR's source branch, posts/updates a sticky summary note, sets a Bright Agent commit status, and — uniquely on GitLab — adds an award-emoji (👀 / 🚀) to the steering note, since GitLab notes support reactions.

Comment steering on GitLab: GitLab has no native "run pipeline on MR comment" trigger, so bridge it with a note webhook → pipeline trigger: add a webhook on note events (Settings → Webhooks) pointing at a small relay; the relay looks up the commenter's project membership (GitLab note webhooks don't carry the commenter's role, so the relay is the trust boundary — only forward comments from members with Developer role or higher); the relay then fires a pipeline trigger with the BRIGHT_STEERING_* variables populated.

Azure Pipelines

Works with Azure Repos Git. Reaches PR-scan parity with GitHub through a Build Validation branch policy, since Azure Pipelines doesn't honor the YAML pr: trigger on Azure-hosted repos.

Setup:

1. Copy examples/ci/azure-pipelines.yml to azure-pipelines.yml in your repository, then create a pipeline from it: Pipelines → New pipeline → Azure Repos Git → Existing YAML.
2. Add pipeline variables (Edit pipeline → Variables; tick "Keep secret" for tokens): BRIGHT_TOKEN, INFERENCE_TOKEN, INFERENCE_URL.
3. Repo access uses the pipeline's built-in System.AccessToken — no PAT to create. Grant the <Project> Build Service (<org>) account these permissions under Project Settings → Repositories → your repo → Security: Contribute, Contribute to pull requests, and Create/Edit (commit) status.
4. Add this pipeline as a Build Validation policy: Project Settings → Repositories → your repo → Policies → (default branch) → Build Validation → "+", then pick this pipeline. PR builds then scope the scan to the PR diff automatically (STAR reads the predefined System.PullRequest.TargetBranch).

🚧

Fix commits and other pipelines

Like GitHub's GITHUB_TOKEN, commits pushed with System.AccessToken do not trigger your other pipelines. If you need the fix push to re-run CI, create a PAT with Code (Read & Write), Pull Request Threads (Read & Write), and Code Status (Read & Write), store it as a secret pipeline variable, and set it as REPO_ACCESS_TOKEN instead. STAR auto-detects the token type (OAuth → Bearer, PAT → Basic).

What triggers a run: the Build Validation policy on every PR (scoped to the diff), the schedule declared in the template (nightly), "Run pipeline" for a manual full scan, and comment steering (below).

Comment steering on Azure DevOps: Azure has no native PR-comment trigger, so wire an Azure DevOps Service Hook on "Pull request commented on" that runs this pipeline with the steering* parameters populated. Azure has no author_association either, so the service hook is the trust boundary — only forward /bright-agent comments from authorized users, and set steeringAuthorRole to MEMBER for them. STAR reacts identically to GitHub: fix commits, a single summary comment thread, and a Bright Agent commit status.

Bitbucket Pipelines

Works with Bitbucket Cloud. PR-triggered scoped scans, scheduled/manual full scans via a custom pipeline, and /bright-agent comment steering through a webhook relay.

Setup:

1. Copy examples/ci/bitbucket-pipelines.yml to bitbucket-pipelines.yml in your repository.
2. Add repository variables (Repository Settings → Pipelines → Repository variables; tick "Secured" for secrets): BRIGHT_TOKEN, REPO_ACCESS_TOKEN, INFERENCE_TOKEN, INFERENCE_URL.
3. REPO_ACCESS_TOKEN should be a Bitbucket App Password (or Repository/Workspace Access Token) with repositories:write and pullrequests:write scopes.

What triggers a run: a pull request (declared under pipelines.pull-requests, automatically scoped to the PR diff), the bright-agent-scan custom pipeline via the "Run pipeline" button (manual) or a schedule pointed at it (Repository Settings → Pipelines → Schedules), and the bright-agent-steering custom pipeline for comment steering (below).

Comment steering on Bitbucket: Bitbucket has no native "run pipeline on PR comment" trigger, so bridge it with a webhook and a small relay: add a webhook (Repository Settings → Webhooks) on "Pull Request: Comment created"; the relay checks whether the comment contains /bright-agent and whether the commenter is authorized (Bitbucket's webhook payload carries the actor but not their role, so the relay is the trust boundary); the relay then calls the Bitbucket Pipelines API to trigger the bright-agent-steering custom pipeline on the PR's source branch, passing the BRIGHT_STEERING_* values as pipeline variables (authenticate with an App Password scoped pipelines:write).

On a successful run, STAR commits fixes to the PR's source branch, upserts a single summary comment, and sets a Bright Agent build status — the same reaction it performs on GitHub, GitLab, and Azure DevOps.

CircleCI

Scheduled/manual full scans. (Comment-based PR steering isn't wired for CircleCI out of the box — it would need the same webhook-relay pattern used for GitLab/Bitbucket/Azure.)

Setup:

1. Copy examples/ci/circleci-config.yml to .circleci/config.yml in your repository.
2. Set project environment variables (Project Settings → Environment Variables, or a Context): BRIGHT_TOKEN, REPO_ACCESS_TOKEN, INFERENCE_TOKEN.

🚧

Use the machine executor

STAR runs docker compose to build and start your application, then scans it on localhost — this needs real Docker access. The docker executor with setup_remote_docker runs Docker on a separate host and can't reach the app on localhost, so it won't work here. The template uses machine: { image: ubuntu-2404:current }, which includes Docker, Docker Compose, and Git.

REPOSITORY_URL is derived from the checkout's origin remote — you typically don't need to set it. Add a workflows entry that runs the job on pull_request-equivalent CircleCI triggers if you want PR-scoped scans; see Run Modes & Scan Scope for DIFF_BASE and SCAN_SCOPE.

Jenkins

Scheduled/manual full scans via a declarative pipeline. (Comment-based PR steering isn't wired for Jenkins out of the box — it would need the same webhook-relay pattern used for GitLab/Bitbucket/Azure.)

Setup:

1. Copy examples/ci/Jenkinsfile into your application repository (Pipeline-from-SCM, or a Multibranch job).
2. Create three Secret text credentials (Manage Jenkins → Credentials): bright-token, repo-access-token, inference-token.
3. Make sure the executing agent/node has Docker, Docker Compose, Git, and curl on PATH, and permission to run Docker.

The Jenkinsfile downloads the binary to WORKSPACE_TMP, outside the checked-out workspace, so it never gets swept into the fix commit (STAR commits with git add -A). REPOSITORY_URL is derived from the checkout's origin remote.

Comment Steering

Sometimes a run can't finish on its own — for example, the application won't boot without a value STAR can't guess (a redirect URI, a feature flag, a missing seed value). Instead of failing silently, STAR posts a pull-request comment explaining what it's missing and inviting a reply.

An authorized user replies with:

/bright-agent set AZURE_CLIENT_REDIRECT_URI=https://…

The marker is lowercase /bright-agent, and may appear at the start of the comment or after other text/newlines. STAR re-runs that pull request with the guidance routed to the relevant phase.

Who can steer a run. Only comments from an author with OWNER, MEMBER, or COLLABORATOR standing on the repository are honored. This check works differently per platform because not every SCM exposes the same trust signal:

On every non-GitHub platform, the relay you build is the trust boundary — only forward /bright-agent comments from users you've independently verified have write access. Never forward arbitrary PR comments as steering instructions.

Fork safety (GitHub). For a /bright-agent comment, GitHub's issue_comment event runs in the base repository's context — with your secrets in scope — even though the comment is on a PR. If that PR's head is a fork, checking it out and running it would leak your secrets to untrusted code. The GitHub Actions template resolves the PR over the API and refuses fork PRs before any checkout.

Platform wiring — see the relevant section above for each: GitHub Actions (native issue_comment), GitLab CI/CD (note webhook → pipeline trigger), Azure Pipelines (Service Hook), Bitbucket Pipelines (webhook → Pipelines API).

The reaction is the same everywhere. Regardless of platform, a steered (or normal) run reacts into the pull/merge request the same way: verified fixes are committed to its head/source branch, a single sticky summary comment is posted or updated, and a Bright Agent commit/build status is set — "Marked Safe by Bright Agent" once nothing is left open.

Environment variables. Steering is passed to STAR through BRIGHT_STEERING_* variables — the CI templates populate these when relaying a /bright-agent comment.