The Problem

Tracking aircraft with ADS-B receivers generates raw data that needs decoding, visualization, and sharing with aggregators. Anyone setting up an ADS-B ground station faces a fragmented ecosystem: dozens of software packages, hardware options, and aggregator services, with no single trusted index of what works together.

What This Does

awesome-adsb is a curated resource list for ADS-B enthusiasts and integrators. It organizes links to documentation, software, hardware, and aggregator services into a single navigable reference. The repo is a Jekyll static site that renders the readme.md content into a browsable web page at adsb.cool (via the CNAME file).

The content is organized into categories: docs and quickstarts, books, aggregators (open-source, community, commercial), software (feeding, visualization, apps), derived data, and hardware (SBCs, receivers, antennas). The _config.yml file configures the Jekyll build, and assets/css/styles.css handles presentation.

How It Is Wired

This is a static documentation site, not an application. There is no runtime entry point, no database, and no network calls beyond the Jekyll build process.

Entry point: readme.md is the primary content source. The Jekyll build (jekyll-gh-pages.yml workflow) processes it into HTML.

Build flow: GitHub Actions runs Jekyll to generate the static site, then deploys it to GitHub Pages. The release.yml workflow handles versioning via haya14busa/action-bumpr. The lint.yaml workflow runs markdown linting.

File responsibilities:

  • readme.md - all curated content
  • _config.yml - Jekyll site configuration
  • .github/workflows/jekyll-gh-pages.yml - build and deploy pipeline
  • .github/workflows/lint.yaml - markdown linting
  • .github/workflows/release.yml - version management
  • _includes/head-custom.html - custom head elements for the Jekyll theme
  • assets/ - CSS and favicon images only

How To Use It

Setup: Clone and run Jekyll locally:

git clone https://github.com/moses-y/awesome-adsb
cd awesome-adsb
bundle install
bundle exec jekyll serve

The .tool-versions file indicates Ruby is managed via asdf. The Gemfile is absent from the file listing, so bundle install may need a Gemfile added first.

Configuration: No environment variables or secrets required. The _config.yml controls site metadata. The CNAME file sets the custom domain.

Running it: For local preview, visit http://localhost:4000 after starting Jekyll. For production, push to GitHub and the Actions workflow deploys to Pages automatically.

Real-World Use

An ADS-B hobbyist setting up a Raspberry Pi feeder would use this list to find: a receiver (e.g., RTL-SDR), feeding software (PiAware, dump1090), and an aggregator to contribute data to (e.g., FlightAware, ADS-B Exchange). The list's "Hardware" and "Feeding" sections provide the exact links needed to assemble a working station in under an hour.

Code Health & Issues

Static analysis of this repository found three workflow hygiene issues:

  • High - Unpinned GitHub Actions - .github/workflows/ uses version tags (asdf-vm/actions/install@v4, ruby/setup-ruby@v1, haya14busa/action-bumpr@v1). Tags can be moved, so CI runs could execute modified action code with your token and secrets. Fix: pin to commit SHAs and let Dependabot bump them.
  • Medium - Missing least-privilege permissions - .github/workflows/lint.yaml references secrets without declaring permissions: contents: read. Fix: add explicit read-only permissions at workflow level.
  • Low - No job timeouts - .github/workflows/jekyll-gh-pages.yml jobs have no timeout-minutes. A hung job runs to the platform default. Fix: add realistic bounds.

No test files exist, which is expected for a static content site. The license is present. No committed secrets detected.

The Bottom Line

This is a clean, well-organized reference site for the ADS-B community. The content quality is good and the Jekyll setup is standard. The CI workflows need hardening (pinned actions, permissions, timeouts) before this should be used as a template for anything production-critical. Anyone building an ADS-B ground station will find this list genuinely useful.