Contributing Guide

June 23, 2026 · View on GitHub

Welcome! We're so glad you're here and interested in contributing to Flatcar! 💖

Contributing Guide

As a newcomer, you're actually in the best position to help us improve! We'd really love your feedback on:

Confusing steps when setting up your developer environment
Missing information in our guides or documentation
Bugs or rough edges in our automation scripts

If something doesn't make sense or doesn't work, please let us know by opening a bug report — we genuinely appreciate it and every bit of feedback helps make Flatcar better!

Ways to Contribute

There are so many ways to get involved! We welcome all kinds of contributions:

Category	Examples
Code	New features, bug fixes, builds, CI/CD
Documentation	Guides, tutorials, API docs
Community	Issue triage, answering questions on Discord/Slack
Flatcar Apps	Create reference implementations for running services on Flatcar (e.g., Minecraft, Jitsi) — great for learning!
Outreach	Blog posts, talks, presentations, workshops
Coordination	Release management, upstream project coordination (e.g., Flatcar CAPI, sysext initiative)
Events	Bug fixing days, doc writing days, devrooms, meetups, conferences
Design	Web design, maintaining the Flatcar website

Not everything happens through a GitHub pull request. Please come to our meetings or contact us to discuss how we can work together — we'd love to meet you!

Thinking of contributing? Awesome! The best way to start is to engage with the project early — drop a comment on an existing issue or open a new one. Let us know what you're interested in working on. This helps us help you, and it's often the key to getting your contribution accepted smoothly.

To report bugs or request features, just file an issue — we're always happy to help point you in the right direction!

Finding Issues

Not sure where to start? No worries — we've got you covered!

Label	Description
`good first issue`	Extra guidance to help you make your first contribution
`help wanted`	Issues suitable for non-core maintainers

💡 Tip: Don't see any issues with these labels? No problem! There's always something exciting to work on. Hop on Discord or join one of our Office Hours — we'll find something that fits your interests and skill level.

🌟 Great for newcomers: Consider contributing a Flatcar App! A Flatcar App is a reference implementation showing how to run a specific service on Flatcar (e.g., Minecraft Server, Jitsi). It's a fantastic way to learn Flatcar hands-on while creating something awesome that helps other newcomers learn too!

Found something you'd like to work on? Excellent! Just leave a comment like "I'd like to work on this" — that's all it takes to claim it.

Proposing New Features

Got an idea for a new feature or a big architectural change? We'd love to hear it! Don't be shy — the best approach is to open an issue first so we can discuss it together before you invest time in implementation.

For package requests, use the "New Package Request" issue type and check out Adding New Packages for guidelines.

Repository Overview

The Flatcar project is spread across multiple repositories in the flatcar GitHub organisation. Here is a map of the key repos, grouped by function, to help you find where to contribute.

OS Image Build System

These repos are the beating heart of the OS image build system.

Repository	Description
scripts	Image build, SDK, and package management — the main entry point for OS development
init	systemd boot files and early OS initialisation
bootengine	Early-boot initrd (dracut) modules
baselayout	Base filesystem layout
flatcar-build-scripts	Extra build helper scripts independent of the main `scripts` repo

Update and Reboot Infrastructure

Flatcar ships atomic, automatic updates. These repos implement the full update and reboot-coordination stack.

Repository	Description
update_engine	Update daemon — the Omaha protocol client running on each node
nebraska	Web-based Omaha update server, dashboard, and release manager
ue-rs	Experimental Rust implementation of the Omaha update client
locksmith	Reboot coordinator using etcd locks to prevent cluster-wide simultaneous reboots
flatcar-linux-update-operator	Kubernetes operator that integrates the update engine with the Kubernetes node lifecycle
fleetlock	Go client for the FleetLock reboot-coordination protocol

Node Configuration and Provisioning

Tools for bootstrapping and configuring nodes at first boot.

Repository	Description
ignition	Flatcar's fork of Ignition — used for CAPI builds and development
coreos-cloudinit	Legacy cloud-init configuration tool for Flatcar
container-linux-config-transpiler	Converts human-friendly Container Linux Config YAML into Ignition JSON

System Extensions

Flatcar is minimal by design; system extensions let you layer software on top without modifying the read-only OS image.

Repository	Description
sysext-bakery	Recipes for building systemd-sysext images (Docker, containerd, Kubernetes, and more)

Testing and Tooling

Repository	Description
mantle	Test framework (kola), image upload tools, and general glue utilities
toolbox	Interactive debugging container that provides a mutable shell on a Flatcar node
update-ssh-keys	Manages authorized SSH keys from multiple sources
mayday	Gathers diagnostic support information from a running node
seismograph	Disk partition management tools
nss-altfiles	NSS module that allows relocating `/etc/passwd` and related files

Deployment and Cloud

Templates, examples, and tooling for getting Flatcar running on cloud and on-prem infrastructure.

Repository	Description
flatcar-terraform	Terraform examples for AWS, Azure, GCP, Equinix Metal, and more
flatcar-packer-qemu	Packer templates for building QEMU and Vagrant images
flatcar-cloud-image-uploader	Tooling for uploading Flatcar images to cloud providers

Cluster API Integration

Repository	Description
cluster-api-bootstrap-provider-kubeadm-ignition	CAPI bootstrap provider that provisions Flatcar nodes using Ignition configs generated by kubeadm

Flatcar Apps

Reference implementations showing how to run real-world services on Flatcar — great for learning and as starting points for your own deployments.

Repository	Description
flatcar-app-minecraft	Containerised PaperMC Minecraft server deployable on Azure and other clouds
flatcar-app-jitsi	Jitsi video-conferencing server automation
flatcar-mastodon	Automation for deploying a Mastodon node on Flatcar

Project and Community

Repository	Description
Flatcar	Central issue tracker, project documentation, governance, and release planning
flatcar-website	Source for flatcar.org
flatcar-demos	Demo scripts and artefacts from conferences and meetups
flatcar-tutorial	Hands-on tutorial material for newcomers

💡 Starting out? scripts is where most OS-level contributions happen. sysext-bakery is a great low-barrier entry point for adding or updating software extensions.

Communication Channels

For all communication channels, community meetings, and social media links, see the Communication Channels section in the README. Come hang out with us on Discord!

Development

Development Environment Setup

Ready to dive into the code? Let's go! Our Developer Guides will walk you through the Flatcar SDK and common tasks like adding or upgrading packages. Start here:

Building Custom Images from Source

These guides will give you a solid foundation for working with the SDK and help you submit PRs that sail through review!

Pull Request Lifecycle

Pull requests can be issued from repository branches (maintainers only) or from forks. The project treats all PRs equally for review and merge, regardless of origin.

Requirements:

Successful CI (including any required status checks the repository defines — see Branch Protection and Merge Requirements)
At least one approving review from someone other than the PR author
CODEOWNERS review is required when owned paths are touched
All review threads must be resolved before merge
The most recent push must be approved by someone other than the author of that push (no self-approval of your own latest change)
Approvers may be co-authors (allowing reviewers to suggest changes)

Stages:

Stage	Description
1. Filed	PR is created. Draft PRs only undergo build+test when explicitly requested.
2. Ready for Review	Maintainers can begin reviewing and approve CI runs. Authors may file directly in this stage if the PR is ready.
3. Under Review	Maintainers add comments, request changes, and vet against Flatcar's mission and core principles.
4. Merged or Closed	PR is merged upon approval or closed without merge.

💡 Tip: PR feeling stuck? Don't be shy — reach out on Discord or bring it up in a community meeting. We're here to help and we want to see your contribution succeed!

Branch Protection and Merge Requirements

The rules below apply to every repository under the flatcar organisation. Individual repositories may add further requirements (for example, extra required CI checks) on top of these.

Review and merge rules

Applied to each repository's default branch:

Rule	Behaviour
Pull request required	Direct pushes to the default branch are blocked; changes must land via PR.
Approving reviews	At least 1 approving review is required.
CODEOWNERS review	Required when changes touch a path owned in `CODEOWNERS`.
Stale review dismissal	Approvals are not automatically dismissed when new commits are pushed, but the latest push must still be approved (see Last-push approval).
Last-push approval	The most recent push must be approved by someone other than its author.
Review thread resolution	All review conversations must be resolved before merge.
Branch deletion	The default branch cannot be deleted.

GitHub Copilot code review is also enabled on PRs targeting the default branch, including draft PRs, and re-runs on each new push.

Repository defaults

Merge strategy: merge commits only — squash and rebase merges are disabled.
Auto-merge: disabled.
Update branch: PR authors may update their branch from the base branch via the GitHub UI.
Delete branch on merge: enabled — head branches are removed automatically after merge.
Commit signoff: required — commits must include a sign-off (use git commit -s, including for commits made via the GitHub web UI).

Authoring PRs

Here are some tips to make your PRs shine and get merged quickly:

Commit Best Practices

Atomic commits: Each commit should be self-contained and address a single logical change. See the Linux Kernel guide on separating changes.
Meaningful messages: Commit messages should explain why something is done, not just what. See describing changes.
Clean history: Use git rebase to squash and order commits logically. Don't retain messy development history.
No throwaway commits: Don't add code you'll change in a later commit. Squash related changes together.
Self-review: Give your own code a critical look before submitting — you'll often spot things you missed, and reviewers will thank you!

PR Description

Think of your PR description as a cover letter. Help reviewers understand:

Explain why you're proposing the change
Provide an overview of the changes
List any unresolved questions or TODO items
Give reviewers the context they need

Commit Guidelines

Great commit messages make everyone's life easier (and make you look like a pro!). Here's the format we use:

<area>: <description of changes>

Detailed information about the commit message goes here.

The Rules

Rule	Details
Line length	Title ≤ 72 characters; body wrapped at 72 characters
Blank line	Separate title and body with one empty line
Title mood	Use imperative mood (e.g., "Add feature" not "Added feature")
Title punctuation	No period at the end
Body punctuation	End sentences with periods

Examples

✅ Good:

app-shells/bash: update ebuild to 5.3

Gentoo upstream has unmasked bash 5.3 and declared it stable.
This change updates the component to use the latest upstream ebuild.

❌ Bad:

Update bash

Updated bash to the latest one.

Thanks for reading, and thank you so much for contributing! 🙏 We're thrilled to have you as part of the Flatcar community. If you have any questions at all, don't hesitate to reach out — we're always happy to help and can't wait to see what you build! 🎉