How autowarefoundation/autoware works
This repository is a meta-repository for Autoware, not the autonomous-driving runtime itself. Its job is to assemble a full ROS-based workspace, provision developer machines and containers, and automate CI/release plumbing around the actual Autoware package repositories.
1. Top-level role: workspace orchestrator
The root contains almost no application code. Instead, it coordinates how Autoware is built and used by pointing to external repositories through .repos manifests and by packaging environment/setup logic.
2. Repository composition layer
The repositories/ directory contains the main workspace manifests:
- autoware.repos, autoware-nightly.repos
- simulator.repos, simulator-nightly.repos
- tools.repos, tools-nightly.repos
- extra-packages.repos
These files define which upstream repos get pulled into the ROS workspace. This is the primary dependency boundary for the project.
3. Developer environment bootstrap
setup-dev-env.sh, ansible/scripts/install-ansible.sh, and the .devcontainer/ definitions are the entry points for setting up a usable development host. They establish the local toolchain, then hand off to Ansible and/or container builds.
4. Ansible as the provisioning engine
The ansible/ tree is the main installation and configuration subsystem. It contains playbooks such as:
- install_dev_env.yaml
- install_docker.yaml
- install_nvidia.yaml
- install_rmw.yaml
- universe.yaml
- openadkit.yaml
- telegraf.yaml
These playbooks are the boundary between “host setup” and “Autoware workspace setup.”
5. Ansible roles are modular system capabilities
Roles under ansible/roles/ represent reusable infrastructure components rather than application features. Important groups include:
- ROS2/runtime setup: ros2, rmw_implementation, ros2_dev_tools
- GPU/graphics support: cuda, nvidia_container_toolkit, kisak_mesa, qt5ct_setup
- build/dev tooling: build_tools, dev_tools, docker_engine
- package/runtime helpers: gdown, geographiclib, spconv, tensorrt, acados, agnocast
- observability: telegraf
Each role encapsulates installation and configuration for one subsystem.
6. Container image layer
The docker/ directory defines the container-based development and execution environment:
- base images: base.Dockerfile, base-cuda.Dockerfile
- Autoware-specific images: core.Dockerfile, universe.Dockerfile, universe-cuda.Dockerfile
- orchestration/build metadata: docker-bake.hcl
- runtime entrypoint: docker-entrypoint.sh
This is the main runtime packaging boundary for users who develop or run Autoware inside containers.
7. Containerized examples and demos
docker/examples/ provides ready-made compose configurations for common scenarios:
- basic CPU/DRI/NVIDIA development
- demo stacks such as awsim and planning-simulator
These examples illustrate how the built images connect to ROS nodes, graphics devices, and simulator services.
8. Devcontainer support
.devcontainer/ contains multiple VS Code devcontainer variants, including core-devel, universe-devel, and universe-devel-cuda. These are thin wrappers over the Docker environment optimized for editor-based development.
9. CI, release, and repo maintenance
.github/workflows/ is extensive and focuses on repository hygiene and infrastructure automation:
- Docker build/push, manifests, and build pipelines
- health checks and pre-commit validation
- release/backport/version-bump automation
- spell checking, DCO, semantic PR checks, cache cleanup
These workflows enforce consistency across the meta-repo and publish container artifacts.
10. Automation for external sync and packaging
The repo also contains tooling for syncing files, dependency updates, and action reuse:
- reusable workflows under .github/actions/
- ansible-galaxy-requirements.yaml
- webauto-ci/ for scripted CI jobs
- repositories/*.repos for pinned source sets
This layer keeps the meta-repo aligned with upstream Autoware component repositories.
11. Documentation and governance as support infrastructure
Files like README.md, ansible/README.md, docker/README.md, and the various GitHub templates/code-of-conduct files are not runtime components, but they are part of the operational boundary: they define how the workspace is consumed, maintained, and contributed to.
12. What is not here
The src/ directory is effectively empty in this repo. The actual autonomous-driving nodes, algorithms, and launch graphs live in the repositories referenced by the .repos files, especially Autoware Core/Universe and related launch/config repos.
Overall architecture: this repo assembles source, environment, and packaging around Autoware. The main flow is:
repository manifests → workspace checkout → Ansible/container provisioning → developer/runtime environment → CI/release automation.
Main entry points: playbooks Playbooks · repositories Repo sets · docker Docker images · .github GitHub automation
Components 20
Workspace manifests
Pinned source-set manifests that define which upstream repositories are checked out into the workspace.
- Repo sets · `.repos` files that pin the upstream Autoware, simulator, tools, and extra package source sets.
repositories - Autoware set · Primary Autoware workspace composition for the core stack.
repositories/autoware.repos - Nightly core · Nightly variant of the core Autoware workspace set.
repositories/autoware-nightly.repos - Simulator set · Workspace composition for simulator-related repositories.
repositories/simulator.repos - Tools set · Workspace composition for tooling and auxiliary repositories.
repositories/tools.repos
Provisioning
Host and workspace setup via shell bootstrap and Ansible playbooks/roles.
- Dev bootstrap · Entry scripts that start local machine setup before Ansible/container provisioning takes over.
setup-dev-env.sh - Ansible install · Installs or prepares Ansible on the host so provisioning can run.
ansible/scripts/install-ansible.sh - Playbooks · Host and workspace setup entrypoints such as dev env, Docker, NVIDIA, RMW, and universe installs.
ansible/playbooks - Roles · Modular infrastructure capabilities for ROS2, GPU support, build tools, observability, and package helpers.
ansible/roles - ROS2 stack · ROS2 and developer toolchain setup for the workspace.
ansible/roles/ros2 - GPU support · NVIDIA, CUDA, Mesa, and Qt/graphics setup for accelerated development and visualization.
ansible/roles/cuda - Runtime libs · Workspace runtime helpers such as RMW, GeographicLib, Spconv, TensorRT, acados, and Agnocast.
ansible/roles/rmw_implementation
Container runtime
Docker images, compose examples, and devcontainer wrappers for containerized development and execution.
- Docker images · Base and Autoware-specific Dockerfiles plus build metadata and entrypoint for containerized use.
docker - Compose demos · Ready-made compose stacks for CPU, DRI, NVIDIA, and demo scenarios like AWSIM and planning simulator.
docker/examples - Devcontainers · VS Code devcontainer variants layered over the Docker environment for editor-based development.
.devcontainer
Automation
CI, release, maintenance, and reusable workflow plumbing around the meta-repository.
- GitHub automation · Workflows, reusable actions, templates, and repo-maintenance automation for the meta-repo.
.github - Webauto CI · Standalone scripted CI jobs for setup and build workflows.
.webauto-ci
Other components
- Autoware meta · Top-level repository that assembles the Autoware workspace, environment, and automation around external package repositories.
- Support docs · Repository-level documentation, contribution guidance, and governance files that define usage and maintenance boundaries.
README.md - Empty src · Workspace source directory placeholder; the real runtime nodes live in external repositories referenced by the manifests.
src
Connections 22
- Autoware meta → Repo sets: pins · Defines the workspace source sets to fetch.
- Autoware meta → Dev bootstrap: boots · Starts local developer-machine setup.
- Autoware meta → Playbooks: provisions · Delegates host and environment setup to Ansible playbooks.
- Autoware meta → Docker images: packages · Builds runnable development/runtime images.
- Autoware meta → GitHub automation: governs · Automates CI, release, and repo hygiene.
- Repo sets → Autoware set: includes · Primary Autoware source set.
- Repo sets → Nightly core: includes · Nightly core source set.
- Repo sets → Simulator set: includes · Simulator source set.
- Repo sets → Tools set: includes · Tooling source set.
- Dev bootstrap → Ansible install: uses · Bootstraps Ansible-based provisioning.
- Ansible install → Playbooks: enables · Provides the installer for the main provisioning engine.
- Playbooks → Roles: orchestrates · Compose reusable system capabilities into host/workspace setup.
- Playbooks → Docker images: prepares · Can install and configure the Docker runtime environment.
- Playbooks → ROS2 stack: invokes · Sets up ROS2 runtime and tooling.
- Playbooks → GPU support: invokes · Configures CUDA/NVIDIA/graphics support.
- Playbooks → Runtime libs: invokes · Installs key runtime libraries and helpers.
- Docker images → Compose demos: demonstrates · Example compose stacks show how images are assembled into scenarios.
- Docker images → Devcontainers: wraps · Devcontainer variants build on the Docker images.
- GitHub automation → Webauto CI: drives · Reusable workflows and CI jobs coordinate repo automation.
- GitHub automation → Support docs: documents · Templates and contribution guidance shape repo governance.
- Repo sets → Empty src: populates · Workspace checkout fills the source tree from external repositories.
- Support docs → Autoware meta: explains · Documentation describes how the meta-repository is used and maintained.