Mastering Fluent Bit: Beginners Guide for Contributing to our CNCF Project Website

This series is a general purpose getting started guide for those of us wanting to learn about the Cloud Native Computing Foundation (CNCF) project Fluent Bit.

Each article in this series addresses a single topic by providing insights into what the topic is, why we are interested in exploring that topic, where to get started with the topic, and how to get hands-on with learning about the topic as it relates to the Fluent Bit project.

The idea is that each article can stand on its own, but that they also lead down a path that slowly increases our abilities to implement solutions with Fluent Bit telemetry pipelines.

Let's take a look at the topic of this article, contributing to the Fluent Bit project website. This article will be a hands-on exploration of how to get started contributing blog articles to the Fluent Bit project website, something that is very accessible to newcomers and a great way to become part of the community.

All examples in this article have been done on OSX and are assuming the reader is able to convert the actions shown here to their own local machines.

Contributing to the Fluent Bit website?

Before diving into the hands-on steps, let's understand why contributing to the Fluent Bit website matters and why it's a great starting point for those of us new to contributing to a CNCF project.

The Fluent Bit project website is where the community shares knowledge, tutorials, and updates with the world. Contributing a blog article means you are directly adding value to the project — helping other developers learn, discover use cases, and get hands-on experience with Fluent Bit telemetry pipelines. No deep knowledge of C is required, no need to wrestle with complex build pipelines. Just ideas, a bit of Hugo familiarity, and a willingness to follow the contribution process.

As a CNCF graduated project, Fluent Bit has an active and welcoming community. Getting your name into the contributor history by writing a blog article is a genuinely meaningful step into open source participation.

Where to get started

The Fluent Bit website lives at fluent/fluent-bit-website on GitHub. Before we touch a single line, there are two repositories we need to understand and keep straight in our heads throughout this process.

The first is fluent/fluent-bit-website, the upstream canonical repository owned by the Fluent community. We never push directly to this one.

The second is your-username/fluent-bit-website-fork, a personal fork of the repository where all our work happens before it goes upstream via a pull request. Note it's been renamed to add the -fork to the repository name, a standard practice to easily identify forked projects.

Forking the repository on GitHub, then we clone our fork locally, and finally, we add the upstream remote so we can always sync our local copy with what the community is doing directly from our command line. 

# Fork the original website using GitHub.

#

# Check out the fork locally, here using my fork as an example.

$ git clone git@github.com:eschabell/fluent-bit-website-fork.git

# Add the upstream website repo.

$ git remote add upstream https://github.com/fluent/fluent-bit-website.git

It's a habit worth building from day one — always sync from upstream before starting any new contribution, This prevents the diverged branch headache that will slow down our pull request later, see below for my example:

# Fetch any upstream work done by others.

$ git fetch upstream

# Sync local fork with the upstream changes.

$ git rebase upstream/main

# Last step, push to your fork's repository.

$ git push

With our fork cloned, verify the site builds locally. The Fluent Bit website uses Hugo, so install it (an exercise left to the reader), then run the Hugo server and open a browser to confirm the site renders before making any changes.

# Start your local copy of the website on http://localhost:9999

$ hugo server -D -p 9999

...

Watching for config changes in .../fluent-bit-website-fork/config.toml
Start building sites …
hugo v0.161.1
                  │ EN
──────────────────┼─────
 Pages            │ 337
 Paginator pages  │   0
 Non-page files   │   0
 Static files     │ 315
 Processed images │   0
 Aliases          │   1
 Cleaned          │   0

Built in 319 ms
Environment: "development"
Serving pages from disk
Running in Fast Render Mode.
Web Server is available at //localhost:9999/ (bind address 127.0.0.1)
Press Ctrl+C to stop

...

If all goes well we should see this on http://localhost:9999 on your local machine:

Now we are ready to get started with our first change to the Fluent Bit website, maybe submitting an article?

How to contribute our first article

The Fluent Bit website is a Hugo site, which means every blog article is a Markdown file with a YAML front matter block at the top. This header is not optional — Hugo uses it to generate the page metadata, listing views, author information, dates, and tags. Getting the front matter right is the first practical task. It covers fields like title, date, author, tags, and any project-specific fields the site uses.

This is a sample from the Fluent Bit latest release announcement blog, found under content/announcements/v5.0/:

---

title: 'v5.0.6'
description: 'Next generation Telemetry Agent for Logs, Metrics and Traces.'
url: "/announcements/v5.0.6/"
release_date: 2026-05-21
publishdate: 2026-05-21
ver: v5.0.6
herobg: "/images/hero@2x.jpg"
latestVer: true
---

The fastest way to get this right is not to try and write it from memory. Instead, we open the blog content directory (content/posts/) in our local fork checkout and find a recently merged article to use as your reference. Mirror its file naming convention, the directory placement, and the front matter fields. Read a few existing articles to understand the tone and content that fits the Fluent Bit blog — tutorials, integration guides, project updates, and community spotlights are all examples of what works well there.

Writing our article

With front matter understood, we need to write our article in a Markdown file locally and use the Hugo server to preview it as we work. The audience is the Fluent Bit community — developers, operators, and platform engineers — so assume technical literacy but do not assume deep Fluent Bit expertise, especially for introductory topics.

Submitting our changes

Once the article is written and previewed correctly, here is the process to follow to submit your changes to the website project for maintainer review. Create a new branch off the synced fork — we never want to work directly on our main branch. Commit your new file with a clear, descriptive commit message. Push to your fork as shown below.

# Work on a branch.

$ git checkout -b erics_my_new_article

# When ready to submit our changes.

$ git add content/posts/my-new-fb-article.md

# Commit the changes using a signed commit (assumes GPG set up).

$ git commit -S

# Push the changes to our repository

# git push --set-upstream origin erics_my_new_article  

Now we open a pull request against fluent/fluent-bit-website from the GitHub UI. In the pull request description, explain what the article covers and why it is a good fit for the blog. Then explicitly request a review — do not assume the PR will be picked up automatically, and make sure to tag a reviewer. If for some reason it's not possible to request a review through the UI, then feel free to post a comment after submitting the PR and ask me (@eschabell) to review as I'm always happy to help.

AI good habits for contributors

This section is worth paying close attention to, because AI tooling is now part of many developers' daily workflow and if used carelessly in an open source context it can create real problems and broken trust with core project maintainers.

Here are my personal ground rules for working with AI assistance on open source projects and how I work with Fluent Bit projects.

Use your local fork filesystem

Configure your AI tool to work against your local fork checkouts — not a downloaded copy to /tmp or any other ephemeral scratch directory. This is important because your working directory is already version-controlled. Every change the AI proposes is immediately visible via git diff, which means you always know exactly what changed before you decide to commit anything. It also saves on token usage and bandwidth speeding up the AI results to your queries.

Never let AI modify without your approval

I always set a personal rule: no line of code or documentation changes without your explicit review and approval, line by line. AI tools should propose changes and you accept, reject, or modify them. This is not just good open source hygiene — it is how you learn the codebase and the project's conventions. The Fluent Bit docs and website have a specific voice and structure. Furthermore, you are putting your name (signing the commits) on any changes you are pushing, so you might want to make real sure you agree with each line that is being modified in your name.

Never let AI touch git

This one is non-negotiable for me in git interactions with my upstream repositories. AI does not commit, does not push, does not fork, and does not open pull requests in my inner developer loop. I do all of that manually. Commits are attribution. When you sign a commit with your name and email, you are asserting that you wrote or have the right to submit that content. In a CNCF project operating under a DCO (Developer Certificate of Origin), this is a legal and community trust matter, not a formality. Keep your hands on the wheel for all git operations and you will also understand the processes and retain your skills.

Check for tests when adding new code

This one is more for code based repositories, but good to know as background information here. If your contribution goes beyond a blog article and into actual code — a plugin, a configuration example, a script — check whether the Fluent Bit fork has existing test patterns for that area. Follow them. If you are adding testable behavior, add tests. Ask in the PR or issue if you are unsure what test coverage is expected. Maintainers would rather answer that question up front than request changes after review.

Always provide a proper commit message

Every commit should have a clear, structured message. At minimum: a short subject line describing what changed, followed by a list in the body describing why and what specifically was modified. It must be signed or it will fail on DCO sign-off  in the CI/CD process. Check the contributing guide for the expected standard. A good commit message is also your own paper trail — if a maintainer asks why you changed something, your commit history should answer the question. Remember, you are signing this, not your AI tooling.

Nice to have: open an issue before a PR

This is more for code repositories than for the website project, but good background information. For anything beyond a trivially obvious contribution, the best practice is to open a GitHub issue first. Describe what you want to write or fix, get a signal from the maintainers that it is welcome, then do the work and open the PR referencing that you are fixing that issue.

More in the series

In this article we explored step-by-step what it takes to make our first article contribution to the Fluent Bit project website — from setting up our fork and getting Hugo running locally, to configuring a blog article and submitting a pull request. Finally we tried to help with establishing good habits around AI tooling along the way.

There will be more in this series as you continue to learn how to configure, run, manage, and master the use of Fluent Bit in the wild. Get started with Fluent Bit today using this online free workshop.