# Run Atlas Headless in CI for Apache Spark Workflows in 2026 > Run `atlas run --format json` in your Apache Spark CI pipelines to get machine-readable output for automated PySpark code analysis and optimization. To run an Atlas session non-interactively in an Apache Spark CI pipeline and retrieve machine-readable output, invoke `atlas run` with the `--format json` flag. This approach allows your pipeline to parse Atlas's event stream, enabling automated actions based on its analysis of PySpark jobs, integration with `pytest (local SparkSession)` for validation, and dependency management via `uv`. ## Key takeaways - Atlas's `atlas run` command enables non-interactive execution for Apache Spark CI pipelines. - The `--format json` flag provides machine-readable output for automated PySpark analysis. - Pre-approve Atlas tools like `bash`, `read`, `edit` for headless PySpark code modifications. - Atlas integrates with `pytest (local SparkSession)` and `ruff format` for PySpark testing and formatting. - Atlas helps optimize PySpark jobs by identifying and replacing inefficient `collect()` or `toPandas()` calls. - Session resumption with `--continue` or `--fork` supports iterative PySpark development in CI. ## How to run Atlas headless for Apache Spark CI? Running Atlas headless in your Apache Spark CI pipeline in 2026 is straightforward using the `atlas run` command. This command's default mode is non-interactive, designed to send a single prompt, stream events to stdout, and exit when the session goes idle, making it ideal for automated environments. The `atlas run` command is specifically engineered for non-interactive execution within CI/CD pipelines. When invoked, Atlas processes a single prompt and streams all session events directly to standard output. This behavior ensures that your CI system can capture the full interaction log. For Apache Spark developers, this means Atlas can analyze PySpark code, suggest optimizations for DataFrames, or even generate `pytest` cases without requiring human intervention. The session concludes and Atlas exits once it determines the task is complete and the session becomes idle, providing a clean termination for pipeline steps. You can also pass `--command` to execute specific slash commands directly. ## Configuring Atlas permissions for PySpark jobs in CI For headless Atlas runs in 2026, pre-approving the necessary tools through a permission configuration is critical, as there is no interactive user to answer 'ask' prompts. Atlas requires explicit permission to interact with your Apache Spark codebase and environment. Atlas operates with a permission-gated tool system, where every tool call is checked against `allow`, `ask`, and `deny` rules. In a headless CI environment, interactive 'ask' prompts are impossible, so all required tools must be pre-approved. For Apache Spark development, Atlas commonly uses tools like `bash` for executing shell commands (e.g., running `ruff format` or `pytest`), `read` for analyzing PySpark files and `pyproject.toml`, `edit` for modifying DataFrame transformations or adding `pytest` fixtures, and `todowrite` for creating task lists. Ensure your Atlas configuration explicitly `allow`s these tools to enable Atlas to perform its tasks effectively on your PySpark codebase without interruption. ## Integrating Atlas with Apache Spark's pytest and ruff format Atlas direct integrates with Apache Spark's testing and formatting toolchain, including `pytest (local SparkSession)` and `ruff format`, by 2026. It can add new `pytest` cases using a local `SparkSession` fixture, then automatically apply `ruff format` to ensure code consistency. A key strength of Atlas in an Apache Spark context is its ability to interact directly with the developer's toolchain. When Atlas suggests changes to PySpark code, such as refactoring a `collect()` call or optimizing a join, it can also generate corresponding `pytest` cases. These tests leverage a local `SparkSession` fixture, ensuring that new code paths are validated within a controlled environment. After making code modifications or adding tests, Atlas can then invoke `ruff format` on the unified diff it computes, ensuring that all changes adhere to the project's formatting standards. This integration means that Atlas not only improves code quality but also maintains code style and test coverage, all within your existing `uv`-managed PySpark project structure. ## Getting machine-readable output from Atlas in Apache Spark pipelines To obtain structured, machine-readable output from Atlas in your Apache Spark CI pipelines, use the `--format json` flag with `atlas run`. This provides a raw event stream that downstream pipeline steps can easily parse, enabling automated analysis and decision-making based on Atlas's insights by 2026. While Atlas's default output is human-readable prose, the `--format json` option transforms the event stream into a structured JSON format. This is invaluable for CI pipelines where automated tools need to consume and act upon Atlas's findings. For instance, if Atlas identifies an inefficient `collect()` or `toPandas()` call in a PySpark job, this information will be present in the JSON output. A subsequent pipeline step can parse this JSON to flag the issue, create a JIRA ticket, or even trigger a follow-up Atlas session to address the problem. This machine-readable output ensures that Atlas's intelligence can be fully leveraged for automated code quality gates and continuous optimization of Apache Spark applications. ## Optimizing PySpark performance with Atlas in CI Atlas excels at identifying and addressing common performance bottlenecks in PySpark jobs, such as inefficient `collect()` or `toPandas()` calls, by 2026. It can analyze DataFrame transformations, join keys, and partitioning strategies to suggest targeted optimizations directly within your CI pipeline. Apache Spark performance is often dictated by data movement and transformation efficiency. Atlas is designed to understand these nuances. It can read your PySpark DataFrame transformations, analyze join keys, evaluate partitioning strategies, and identify every action that triggers a Spark job. Crucially, Atlas can pinpoint problematic `collect()` or `toPandas()` calls that pull full datasets onto the driver, suggesting replacements that keep data distributed. It can also recommend broadcasting the smaller side of a skewed join to improve performance and explain the resulting physical plan from `.explain()`. By integrating Atlas into your CI, these optimizations can be automatically detected and proposed, ensuring your PySpark jobs run efficiently before they reach production. ## Resuming or forking Atlas sessions in Apache Spark CI Atlas supports resuming or forking prior sessions using `--continue`, `--session`, or `--fork`, a crucial capability for iterative development or debugging in Apache Spark CI pipelines by 2026. This allows a pipeline step to build upon or re-evaluate an earlier Atlas run. In complex Apache Spark development workflows, it's often necessary to iterate on solutions or re-evaluate a problem. Atlas provides robust session management for this purpose. The `--continue` flag allows you to pick up an existing session where it left off, useful if a CI job was interrupted or needs further refinement. `--session` lets you specify a particular session ID to resume, while `--fork` creates a new session based on an existing one, allowing for parallel exploration of different solutions. This means that if an Atlas run in CI identifies a PySpark optimization but requires further context or a different approach, a subsequent pipeline step can easily resume or fork that session, building on the previous work without starting from scratch. ## Steps 1. Ensure your Apache Spark project includes a `pyproject.toml` file pinning `pyspark` and uses `uv` for dependency management. 2. Configure Atlas's permissions to `allow` tools like `bash`, `read`, `edit`, and `todowrite` in your CI environment's Atlas configuration, as headless runs cannot prompt for approval. 3. Invoke `atlas run` in your CI pipeline with a specific prompt targeting your PySpark job, including the `--format json` flag for machine-readable output, for example: `atlas run --format json 'Optimize the collect() call in src/pyspark_job.py'`. 4. Explicitly set the active model and provider using the `provider/model` format, such as `--model github/copilot-gpt4`, to ensure the correct AI model is used for PySpark analysis. 5. Parse the JSON output stream from `atlas run` in a subsequent CI step to programmatically identify Atlas's findings, such as suggested PySpark DataFrame optimizations or new `pytest` cases. 6. If Atlas suggests code changes, apply them and then run `ruff format` on the modified PySpark files to maintain code style consistency. 7. Execute `pytest (local SparkSession)` to validate any PySpark code changes or newly generated test cases, ensuring functional correctness within your CI pipeline. 8. Optionally, use `atlas run --continue ` or `--fork ` in a later CI step to resume or build upon a previous Atlas session if further iteration on PySpark code is required. ## FAQ ### How does Atlas handle `collect()` calls in PySpark CI? Atlas reads your PySpark DataFrame transformations and can identify `collect()` or `toPandas()` calls that pull full datasets onto the driver. In a headless CI run, it can suggest replacements or optimizations within the JSON output, allowing your pipeline to flag or act on these performance bottlenecks. ### Can Atlas integrate with `pytest` for PySpark unit tests? Yes, Atlas can add `pytest` cases using a local `SparkSession` fixture. After suggesting PySpark code changes, it can generate corresponding tests, which your CI pipeline can then execute using `pytest (local SparkSession)` to validate the modifications. ### What output format does `atlas run` provide for CI pipelines? When invoked with the `--format json` flag, `atlas run` streams a raw, structured JSON event log to stdout. This machine-readable output is ideal for automated parsing by subsequent steps in your Apache Spark CI pipeline. ### How do I ensure Atlas has permissions to modify PySpark code in CI? For headless CI runs, you must pre-approve the necessary tools in Atlas's permission configuration. Explicitly `allow` tools like `read`, `edit`, and `bash` so Atlas can analyze, modify, and format your PySpark files without requiring interactive prompts. ### Can Atlas explain PySpark physical plans in a CI environment? Yes, Atlas can analyze your PySpark code and, when prompted, explain the resulting physical plan from `.explain()`. This insight can be delivered in the machine-readable JSON output, helping to diagnose and optimize query execution within your CI pipeline. ### How does Atlas manage dependencies like `pyspark` in a CI context? Atlas operates within your existing project structure. It expects your Apache Spark repository to have a `pyproject.toml` file pinning `pyspark` and relies on your CI environment to use `uv` or a similar package manager to install these dependencies before Atlas runs. ### Can Atlas help with skewed joins in PySpark CI? Atlas can analyze your PySpark join operations and identify potential data skew. It can then suggest optimizations, such as broadcasting the smaller side of a skewed join, and provide explanations for these recommendations within its output stream in CI. --- Canonical HTML: https://runatlas.sh/resources/stacks/run-atlas-headless-in-ci-in-spark Source of truth: aeo_pages row `/resources/stacks/run-atlas-headless-in-ci-in-spark` (segment: Stacks) (this file is generated from it, never hand-edited). Licence: Atlas is proprietary with a free core. It is not open source and there is no public source repository.