Frequently Asked Questions
Welcome to the FAQ page. Here you'll find answers to some of the most common questions about Kargo.
General Questions
What is Kargo?
Kargo is an unopinionated continuous promotion platform that helps developers orchestrate the movement of new code and configuration through the various "stages" of their applications' lifecycles using GitOps principles.
What exactly is "continuous promotion," anyway?
If you have some familiarity with GitOps, you know that GitOps agents like Argo CD excel at making the actual state of a Kubernetes cluster reflect desired state that is expressed declaratively and stored in a Git repository.
GitOps provides no specific guidance, however, on how desirable changes can be propagated from the desired state of one stage in an application's lifecycle to the desired state of the next. Any means by which such a thing might be accomplished, we would consider to be a "promotion process." When that process is codified into a pipeline and either partly or fully automated, we consider it "continuous promotion."
Follow up question: Why is this not "continuous deployment?"
Because the processes we're focused on do not perform deployments. They focus on propagating changes to desired state so that a GitOps agent like Argo CD can then perform the heavy lifting.
So “stage” is just another word for “environment?”
Not exactly, but you could think of it that way if it suits your use case.
Technically, a stage is a promotion target. It represents a certain set of desired state that needs to be altered by a promotion process. The underlying resources that a GitOps agent will reconcile against that desired state can be varied according to your needs. It could be a particular instance of your entire application or just a few microservices that are part of a larger whole. It could even be an entire Kubernetes cluster if that's what fits your use case.
Is Kargo open source?
Yes it is! You can find the project on GitHub.
If you like what we're doing, please give us a 🌟!
How do I get started?
These very docs are a great place to start. In particular, we recommend checking out the Core Concepts section or, if you're ready to get your hands dirty, our Quickstart.
Where can I get support?
Project maintainers as well as the broader Kargo community are usually quite responsive to issues and discussions in the GitHub repository.
Our community Discord channel is also quite active and you're invited to join us there!
If you're interested in a commercial distribution of Kargo or professional support, check out akuity.io.
How can I contribute to the project?
Find us on GitHub. Open issues. Ask questions... or even answer questions!
If you're interested in contributing code, our Contributor Guide will help you get started. You'll also find a lot of open issues labeled as good first issue or help wanted. If you want to work on any of these, comment on the issue to let us know, so we can assign it to you to help prevent duplicated efforts. If work or life gets in the way and you can't complete the issue -- no problem. Just let us know.
If you're interested in contributing an entire, new feature, please propose the feature first and discuss with maintainers before putting a lot of effort into the implementation.
Technical Questions
Does Kargo force me to work with a separate branch per stage?
No, it doesn't, although it's a common misconception that it does.
Fundamentally, Kargo needs a place to store the output of your promotion processes so that it can be picked up and applied by a GitOps agent like Argo CD. For all intents and purposes, this may as well be an S3 bucket, but as the term "GitOps agent" implies, the output of those processes will be most accessible to those agents if it is stored in a Git repository.
Storing the output of your promotion processes in stage-specific branches is a practice that's been unfairly maligned through misunderstanding of a certain infamous blog post, which was actually asserting that GitFlow has no place in GitOps.
Leveraging stage-specific branches is a practice that we do in fact encourage,
but it is by no means a requirement. It is equally tenable to store the output
of promotion processes within a well-thought-out directory structure within a
single branch -- even your main branch.
Does Kargo support monorepos?
We get this question a lot. In fact, it would seem the majority of our users are working with monorepos. The short answer yes.
The longer answer is that Kargo is unopinionated about whether you use one repository or many. It's also mostly unopinionated about how you structure those repositories, but it is important that you segregate the configurations for individual applications or services such that commits to your repository can easily be selected or ignored on the basis of what paths they affect.
Our Patterns section will provide suggestions for how to structure monorepos to enable various scenarios.
Does Kargo support microservices?
Yes it does. And there are a lot of different ways Kargo can support you, depending on your specific needs.
What if I need to promote several microservices as a unit?
In an ideal world, the lifecycles of all microservice are completely independent of one another. But we don't live in an ideal world. Sometimes you need to ensure that state changes for a number of related microservices are promoted together as a unit. There are a number of different ways to achieve this with Kargo, depending on your specific needs.
Our Patterns section provides additional guidance on this topic.
Follow up question: What if I need to promote several microservices in a specific order?
Kargo can accommodate this as well, and once again there are a number of ways to approach it depending on your needs and our Patterns section should help.
How do I integrate with multiple Argo CD control planes?
To get an overview of how this can be achieved, head on over to our Architecture section to learn about the topology of a large-scale Kargo deployment.
How do I integrate Kargo into my CI pipelines?
Truthfully, we hope you don't find the need to do this -- at least not directly.
The main impetus for developing Kargo was the lack of tools to comprehensively effect continuous promotion. In this vacuum, the tendency we'd observed was for teams to cobble together bespoke workflows using a variety of scripts and tools. Chief among these tended to be CI platforms like Jenkins and GitHub Actions, which are excellent at what they do (testing code and building artifacts quickly and synchronously), but tend to be poor at managing the asynchronous, distributed, and complex workflows that are necessary for continuous promotion. These cobbled together workflows tended to be difficult to understand, maintain, and scale, and seldom provided the observability that comes with a single, comprehensive tool.
In short, we built Kargo to be a better alternative. We believe your CI system remains as important as ever, but that its role is to test code and build artifacts. Kargo's role is to notice new artifacts and move them through the stages of your application's lifecycle. This means the (indirect) integration between your CI system and Kargo are your artifact repositories.
Follow up question: What if I really need to?
It's possible, of course. Please reach out to the maintainers or the community to share your use case and learn about your options. Understanding your needs will help us to identify possible gaps in Kargo's capabilities.
How do I implement SSO?
Kargo can be configured to authenticate users with any identity provider that supports OpenID Connect with PKCE. This includes most major identity management platforms like Okta, Auth0, and Microsoft Entra ID (formerly Azure Active Directory).
Through optional and seamless integration with Dex, Kargo can also integrate with a variety of identity providers that either don't support PKCE or don't support OpenID Connect at all (GitHub, for example).
Refer to our OpenID Connect integration docs for comprehensive coverage of this topic.