# kodiak: a GitHub App that updates and merges pull requests on your behalf

> Kodiak is a GitHub App that keeps pull requests up to date with the base branch and merges them once CI and approvals pass, and it can be installed from the Marketplace or self-hosted. It trades some of the judgment of a human reviewer for a rule set you configure in TOML.

**chdsbd/kodiak** — 🔮 A bot to automatically update and merge GitHub PRs

- Repository: https://github.com/chdsbd/kodiak
- Website: https://kodiakhq.com
- Stars: 1,115 · Forks: 74
- Language: Python
- License: AGPL-3.0
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/chdsbd-kodiak

## What Kodiak actually automates, and where it stops

Kodiak is described in the README as a GitHub bot to automatically update and merge GitHub PRs, and it is delivered as a GitHub App, not as a script you run in CI. The scope has three named parts.

Auto Update keeps your pull requests up to date with master automatically, which means rebasing or merging the base branch into an open branch so the diff reflects current code rather than a stale snapshot. Auto Merge works through a label: add the automerge label to a pull request and Kodiak merges it once CI and approvals pass. Bot Collaboration means running Kodiak alongside a dependency bot, with dependabot, snyk and greenkeeper.io named in the README, so that dependency pull requests are opened by one tool and merged by another without a human touching them.

The third part is where the design shows its intent, and it is also where the risk sits. The label-driven merge means the decision to merge is expressed in the label and in the configuration, not in a person reading the diff. That is exactly right for a dependabot bump with a passing test suite, and exactly wrong for a change to authentication code where the tests pass and the change is still wrong.

So the honest framing is that Kodiak automates the mechanical tail of the review process. The questions it answers are: is this branch still current, did CI pass, did the required reviewers approve, and is the label present. The question it does not answer is whether the change should have been made. A configuration that says merge on green CI will happily merge a bad change, and the label is a decision you are delegating.

## Installation from the Marketplace, and the self-hosted path

Kodiak is available through the GitHub Marketplace, and the README links an install app button to the marketplace listing at github.com/marketplace/kodiakhq. Installing it as a GitHub App is the normal route: the app is granted access to the repositories you select, and it receives webhook events from GitHub rather than polling.

If you would rather run it yourself, the README points at a self-hosting page in the documentation. The repository layout tells you what that involves, and it is more than a single process. There is a bot/ directory holding the GitHub App that receives webhook events from GitHub and operates on pull requests, a web_api/ directory for the web API that powers the Kodiak dashboard, and a web_ui/ directory for the dashboard frontend that talks to that API. The README marks both the API and the frontend as WIP, so the dashboard is the part of the product that is least settled.

The other top-level directories describe the rest of the system. infrastructure/ holds deployment material, s/ is a directory whose purpose the README does not explain, docs/ holds documentation sources, assets/ holds the logo and other media, and there is a .kodiak.toml file at the root, which is the example or default configuration. A kodiak.code-workspace file and a codecov.yml round out the developer tooling, and CHANGELOG.md sits next to the README.

For a team that wants the bot without sending webhook data to a third party, self-hosting is the meaningful option. The operational question is what the bot/ service needs, and the README does not enumerate its dependencies, so the self-hosting documentation at kodiakhq.com/docs/self-hosting is where that is answered. The repository topics list redis and typescript alongside python, which suggests the bot is Python with a TypeScript component and a Redis-backed queue, but the README does not confirm the role of redis.

## Configuration lives in a .kodiak.toml in the repository

The presence of a .kodiak.toml file at the top level of the repository is the most important structural fact about how Kodiak is configured, and it implies the configuration travels with the code.

The reason this matters is that a bot configured through a hosted dashboard and a bot configured through a file in the repository behave very differently in a team. A file is versioned, reviewable in a pull request, and applies to everyone who clones the repository. A dashboard setting is invisible to the people writing the code and lives in someone else's account. Kodiak supports the file, and the README links a configuration guide at kodiakhq.com/docs/config-reference, which is where the individual keys are documented.

The file lives in the repository, so its scope is a repository. The README also links a Why and How page, a troubleshooting page, a help page, and a Prior Art and Alternatives page, which tells you the project expects you to compare it with other merge automation before committing to it.

The configuration reference is where the decision surface actually is. A Kodiak setup expresses a merge policy: which base branch a pull request targets, when an update should happen, which status checks must pass, how many approvals are required, and which labels trigger a merge. The README's description of the automerge label is the simplest illustration, but the config reference is where the full set of knobs and their defaults live, and it is the document to read before enabling auto merge on a repository that matters.

## Release history shows the cost side of the GraphQL API

The three most recent releases all landed on the same day, 2026-03-13, and their titles are more informative than a changelog would be.

v0.59.0 reduced the GitHub GraphQL API cost from 4 units to 2 units. v0.58.1 handles bots as requested reviewers, which is a specific and common annoyance: a dependency bot that requests a review cannot satisfy a requirement that a human approve, so the pull request would sit forever waiting for a reviewer that the policy says must be a person. v0.59.1 suppressed an internal warning.

Read together, these tell you something real about the project. A bot that runs on every pull request event consumes GitHub API quota, and the GraphQL cost reduction is a direct response to that pressure. Handling bots as requested reviewers is the kind of fix that only appears once you run the thing in production, against a real repository with a real dependency bot.

The repository is not archived and the last push was on 2026-09-11, so work continues after the v0.59.1 tag from 2026-03-13. The version numbers are still in the 0.x range, which under semantic versioning means the public API is not treated as stable, and a config-driven product is only as good as its compatibility promises. The CHANGELOG.md at the root is the file to read before upgrading, since a change in how approvals or status checks are counted would change what your repository merges.

The project also asks for sponsorship, with a GitHub Sponsors link for commercial use to help cover server costs and support development.

## The licence question, stated plainly

Kodiak is licensed AGPL-3.0, with the LICENSE file at the root of the repository. That is the single fact most likely to affect an adoption decision, and it needs to be understood rather than glanced at.

The AGPL is a copyleft licence with a network clause. The part that matters here is what that means for a hosted service. If you run Kodiak unmodified yourself and it talks to GitHub over the network, the network clause is the one that gets attention, and the answer depends on whether you expose a modified version of the program to users over the network. If you do not modify it, the situation is different from the case where you patch the bot to add your own behaviour.

This is not legal advice and the point of mentioning it is not to frighten anyone away. It is that the licence choice in a bot is different from the licence choice in a library. Kodiak is a service that sits between your team and GitHub and acts with your credentials. A company that forbids AGPL components in its stack, or that requires a licence review before a bot can merge code into a repository, needs to run that review before installing from the Marketplace, not after.

The practical mitigation, if the review comes back positive, is to self-host rather than use the hosted dashboard, and, if you modify the bot/ service, to offer that modified source to your users as the AGPL requires. Whether that is sufficient is a question for whoever owns the policy.

## Kodiak against the other way of doing this

The README links a Prior Art and Alternatives page, so the project is aware that other tools solve adjacent problems. The comparison worth drawing is not between Kodiak and another bot, but between a bot and the manual habit it replaces.

The manual habit is a reviewer pressing the update branch button, or a dependency bot opening a pull request and a human merging it after reading a changelog. The cost of that habit is attention: someone has to look at each open pull request, and the queue is only ever as short as the team's discipline.

Kodiak's approach moves the decision into configuration. A rule set says which checks and approvals must be satisfied, and the label says the merge is authorised. The difference in approach from a CI job that merges on green is that Kodiak knows about pull request semantics that a plain CI job does not: approvals, review requests, bot reviewers, labels, and the base branch relationship. That domain knowledge is the actual product.

The trade is the same one the label makes explicit. A manual merge is a human accepting responsibility for a specific diff. An automatic merge is a policy accepting responsibility for a class of diffs. For the class where the diff is a dependency bump and the tests cover it, the policy is more reliable than a distracted human, because it is applied every time. For a class where the tests are thin, the policy removes the last checkpoint without adding anything.

So the deciding question is not whether Kodiak works. It is whether you can write down, precisely, the conditions under which a change should merge without a person reading it. Teams that have that written down get value from it. Teams that do not are automating an undefined decision, and the label is where the missing definition hides.

## Conclusion

Adopt Kodiak if your pull request queue is large, mostly dependency bumps, and your review rules can be expressed as a configuration file rather than as a person reading each diff. Do not adopt it as a replacement for review on changes where a human needs to read the diff, and do not adopt it inside an organisation whose policy treats the AGPL-3.0 licence as a blocker for a hosted service without review. Verify first that your .kodiak.toml is committed to the repository, that the base branch and update method match how your team actually branches, and that the required status checks and approvals are configured before you let a bot merge without a human.

## FAQ

### How do I install Kodiak?

Kodiak is available through the GitHub Marketplace as a GitHub App, and the README links an install button to the marketplace listing. If you would rather run it yourself, the README points at the self-hosting page in the documentation.

### How does the automerge label work?

The README states that adding the automerge label causes Kodiak to merge the pull request once CI and approvals pass. The merge policy itself is configured in a .kodiak.toml file, with the details in the configuration guide the README links.

### Can Kodiak work with dependabot?

Yes. The README lists Bot Collaboration as combining Kodiak with a dependency bot, naming dependabot, snyk and greenkeeper.io, so that dependency pull requests are opened by the bot and merged by Kodiak.

### What licence is Kodiak released under?

The project is licensed AGPL-3.0, with the LICENSE file at the root of the repository. The README also asks commercial users to support the project through GitHub Sponsors to cover server costs.

## Sources

- [chdsbd/kodiak on GitHub](https://github.com/chdsbd/kodiak)
- [License: AGPL-3.0](https://github.com/chdsbd/kodiak/blob/master/LICENSE)
- [Project website](https://kodiakhq.com)
- [README](https://github.com/chdsbd/kodiak/blob/master/README.md)
- [Releases](https://github.com/chdsbd/kodiak/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/chdsbd-kodiak