A new open-source project on GitHub, called Octosmith, aims to give organizations a structured way to manage how their code repositories are set up. The toolkit lets teams describe the repositories they manage, assign each one to a template, review the changes needed to reach that target state, and then apply those changes from a command-line interface or through GitHub Actions. The project is published under the account Kralizek and is described in its repository as a toolkit for defining, validating and reconciling GitHub repository configuration as code.
What Octosmith does
Many organizations end up with dozens or hundreds of repositories, each carrying its own settings for access rules, branch protection, environments, team permissions and standard files. Over time these settings drift apart, often because they were changed by hand in the web interface and never recorded anywhere. Octosmith approaches the problem with a declarative model. Instead of clicking through settings for each repository, a team writes down the state it wants and lets the tool work out the difference.
According to the project README, the workflow starts with a configuration directory. A central file defines which repositories are in scope, and a set of template files under a templates folder describes the desired state for each group of repositories. The README also points to an example configuration that covers repository selectors, repository settings, rulesets, environments, teams and managed files, which gives a sense of how far the model reaches.
How the pipeline works
Octosmith follows the same sequence whether it runs on a laptop or inside a continuous integration job. The README lists five steps:
- Load and validate the configuration directory.
- Discover the repositories that fall inside the defined scope.
- Resolve each repository to exactly one matching template.
- Build a plan that compares the current state with the desired state.
- Report that plan or apply its operations.
The requirement that each repository match exactly one template is a deliberate safeguard. Ambiguous assignments, where a repository could fall under two sets of rules, would make the outcome unpredictable. By forcing a single match, the tool makes it clear which rules govern each repository before any change is made.
Two collection-management modes
The project offers two ways to treat groups of resources. The default mode, called explicit, manages only the members that the configuration names directly. Anything not declared is left alone. The second mode, called strict, makes supported named collections authoritative, meaning that members not declared in the configuration can be removed. The strict mode suits teams that want the configuration to be the single source of truth, but it carries more risk, which is why the explicit mode is the default.
The scaffolding command accepts a flag to choose between these modes when a new repository is generated. The README notes that non-interactive setup is possible by passing the option after a separator in the Deno command line.
Running Octosmith locally and in CI
The project supports two main routes for running the tool. The first is the command-line interface, which groups its functions into inspection commands and two operational commands, plan and apply. The README explains that some commands work without any connection to GitHub. The template validation and permission review commands run offline, and the template list command reports each template's identity, optional display name and source file path relative to the configuration root. Commands that read live repository data, such as resource listing, planning and applying, need authentication. They can use an injected token, a GITHUB_TOKEN variable, or the local GitHub command-line tool.
Operators can also target a run narrowly. Passing a template name to plan or apply covers every repository classified by that template, while passing a single repository name limits the run to that repository. For teams with large organizations, this makes it possible to test a change on a small set before rolling it out more widely.
The GitHub Action and secrets
The repository also ships a GitHub Action that supports three modes: validate, plan and apply. The README says the Action runs the exact published version of the Octosmith command-line package tied to its release commit, so the behavior of a given workflow stays fixed. A moving tag named v0 follows the latest compatible release in the 0.x series, which lets users receive fixes without changing their workflow file.
The generated repository includes two workflows. A pull-request workflow validates the configuration without needing organization credentials, which means proposed changes can be checked by reviewers before anything is applied. A default-branch workflow performs the actual apply step and uses a secret named OCTOSMITH_TOKEN. This separation is a sensible pattern: the riskiest step runs only after a change has been merged.
Event streaming and optional integrations
The command-line interface can write one NDJSON resource event per repository while it plans or applies changes. The output can go to a regular file, a named pipe or another writable destination. This format is convenient for log processing and for dashboards that need to react as work happens.
The scaffolder can also generate an example that uses Hooksmith, a separate tool, to stream resource.applied events live while Octosmith runs. The README is clear that Hooksmith is optional. The core library does not depend on it for apply behavior, so teams that do not need live notifications can ignore it entirely.
Stability and what comes next
The README states that Octosmith is on the 0.x release line. According to the project, its public surface is usable today, but configuration formats and programming interfaces may still change before a 1.0 release. Readers adopting the tool should expect some churn and should pin versions in their workflows, which the Action's release-commit design already supports.
Detailed documentation is organized under a docs folder in the repository, and separate README files cover the library package, the command-line package and the configuration model. For organizations that already manage infrastructure as code, Octosmith extends that discipline to GitHub itself. Whether it becomes a common part of platform engineering will depend on how the configuration model matures and how many teams are willing to trust a tool that can remove undeclared members in its strict mode.
Related: Open-Source n8n Bot Calculates Czech Tax on Broker Investments · Software License Renewal Tracker Sends Timely Reminders
Comments (0)