# legitify: a policy scanner for GitHub and GitLab configuration

> legitify is an open source command line tool that checks the configuration of a GitHub or GitLab organisation against a set of policies and reports which ones fail, in a form that is meant to be consumed by a pipeline. It is written in Go, licensed Apache-2.0, and its most recent tagged release is v1.0.11 from 2024, so its current state has to be judged from the repository rather than from the release history.

**Legit-Labs/legitify** — Detect and remediate misconfigurations and security risks across all your GitHub and GitLab assets

- Repository: https://github.com/Legit-Labs/legitify
- Website: https://legitify.dev
- Stars: 889 · Forks: 81
- Language: Go
- License: Apache-2.0
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/legit-labs-legitify

## It checks configuration, not code

legitify is described as a tool to detect and remediate misconfigurations and security risks across all your GitHub and GitLab assets, and the strengthening of the security posture of your source-code management is the stated goal.

The scope matters, because source code management platforms have a configuration surface of their own, separate from the code they hold. Who can create a repository, who can install a GitHub Action, whether a branch is protected, whether two-factor authentication is required, whether status checks are enforced, what a webhook is allowed to reach. Each of those is a setting, and each setting can be wrong in a way that no code review would ever notice.

The tool works by checking a set of policies against the resources of a platform and reporting which ones fail. The default behaviour of the analyze command is to check the policies against all of your resources, which the documentation names as organizations, repositories, members and actions. Archived repositories are skipped.

The comparison table the README links to makes the position explicit: Legit Security is an application security posture management and software supply chain security solution, and legitify is the open source piece of that picture. The distinction matters for anyone choosing between the two, and it is stated in the project documentation rather than left to inference.

The topics attached to the repository name the intended framing too: devsecops, sdlc-security, security-scanner, supply-chain-security and ci. This is a configuration and posture tool that happens to live in the pipeline, not a static analysis tool that happens to have a policy file.

## The analyze command and the flags that scope it

Running it needs a token, and the token is the whole of the authentication story.

```bash
SCM_TOKEN=<your_token> legitify analyze
```

The flags exist so you can narrow the scope, and each of them maps to a type of resource:

The --namespace flag, with the short form -n, analyzes policies that relate to the specified resources. The --org flag limits the analysis to the specified GitHub organizations or GitLab group, excluding archived repositories. The --repo flag limits the analysis to the specified GitHub repositories or GitLab projects. The --scm flag specifies the source code management platform, with possible values of github or gitlab, and it defaults to github, with the note that when running on GitLab, --scm gitlab is required. The --enterprise flag specifies which enterprises should be analyzed, and an enterprise slug must be provided.

A scoped run looks like this:

```bash
SCM_TOKEN=<your_token> legitify analyze --org org1,org2 --namespace organization,member
```

and the documentation says that the above command will test organization and member policies against org1 and org2.

The --scm default is the detail to get right. A team running the tool against GitLab who forgets the flag will find the tool talking to GitHub with a GitLab token, and the failure will look like an authentication problem rather than a missing flag. The same applies to the --enterprise requirement: an enterprise slug is mandatory, so an enterprise level scan is not something the tool will discover for itself.

## The policy engine is Open Policy Agent

The Go module file shows what the tool is built from, and one dependency dominates the design.

The module is github.com/Legit-Labs/legitify and it requires Go 1.19. The direct dependencies include the Open Policy Agent at version 0.52.0, which is the policy evaluation engine, and the OpenSSF scorecard at version 4.10.5. There is also google/go-github at v53, xanzy/go-gitlab, the owenrumney go-sarif library for producing SARIF output, sashabaranov/go-openai for the GPT analysis path, spf13/cobra and viper for the command line and configuration, olekukonko/tablewriter for the terminal tables, and vbauerster/mpb for progress bars.

The presence of OPA is the key architectural fact. It means the policies are not hardcoded conditionals in the scanner but Rego policies evaluated by a real policy engine, and it means the policy set is data, which is why the repository has a policies directory at the top level and a .legitignore file. The ignore file is per policy name, which is exactly the granularity you want when a particular check does not apply to a particular organisation, and the CI action example shows it being used with the ignore-policies input listing non_admins_can_create_public_repositories and requires_status_checks.

The SARIF dependency is the other one worth naming. SARIF is the standard format for static analysis results, and producing it means the findings can be uploaded to a code scanning dashboard rather than only read in a terminal. That is what makes the tool a pipeline citizen rather than a script you run by hand.

The scorecard dependency is a third policy source, and it means the scanner can bring OpenSSF's supply chain checks alongside the configuration policies, which is where the supply-chain-security topic in the repository metadata comes from.

## Dropping it into a scheduled workflow

The action is the intended way to run this continuously, and the documentation gives a complete workflow file.

```yaml
name: Legitify Analyze
on:
    workflow_dispatch:
    schedule:
      - cron: '0 11 * * 1-5'

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - name: Legitify Action
        uses: Legit-Labs/legitify@main
```

The action file in the repository holds additional parameters and configuration, and the README points at the action_examples directory for concrete examples. The trigger pattern is worth reading as a design suggestion: workflow_dispatch for a manual run, and a schedule on the hour 11 on weekdays. Weekdays only, because a scan that pages somebody at the weekend is a scan people turn off.

The action takes a github_token, and the example passes it from a secret, and it takes an ignore-policies input with a list of policy names to skip.

The other two installation paths are worth mentioning because they tell you what kind of tool this is. There is a GitHub CLI extension, gh-legitify, installed with gh extension install and then invoked as gh legitify. And there is a from-source path where you clone the repository and run go run main.go analyze, which is the fastest way to try a change against a policy before you propose it.

For a plain local run there is a Homebrew formula, and the release archives contain both the binary for the desired platform and the built-in policies provided by Legit Security. That last detail is a real deployment consideration: the policies are shipped with the binary, so the tool does not fetch policy content from a remote source at run time.

## Requirements are a GitHub personal access token with organisation admin scopes

The requirements section is where this tool's practical limits are stated, and it is worth reading closely.

To get the most out of legitify, you need to be an owner of at least one GitHub organization. Otherwise you can still use the tool if you are an admin of at least one repository inside an organisation, in which case you will see only repository-related policy results. So the tool degrades rather than fails, and the scope of what it can check depends on your position in the organisation hierarchy.

legitify requires a GitHub personal access token to analyze your resources successfully, which can be provided as an argument with -t or as the SCM_TOKEN environment variable. The PAT needs specific scopes for full analysis, and the documentation lists them:

```
admin:org, read:enterprise, admin:org_hook, read:org, rep
```

admin:org is a broad scope, and read:enterprise is needed for the enterprise level that the --enterprise flag targets. That combination is a real request, and the tool's value is proportional to it, so the decision of whether to run it is really a decision about whether you are willing to hold organisation admin rights in a token.

There is a second requirement, in the GitLab case, that the documentation treats separately, and it is worth noting that the GitLab support is not described in the same level of detail. The requirements section is headed GitHub (Cloud and Enterprise Server), while the command flags cover both platforms.

The project also ships a second, quite different mode, gpt-analysis, which is GPT-3 based analysis of the security posture of the provided repository or organization. It takes both an SCM token and an OpenAI token, and it carries a note that should be read before anyone puts it in a pipeline:

The documentation carries a note in capitals: the repository and organization metadata is sent to openai servers.

The metadata, not the code, is what is sent, but metadata is names, descriptions, structure and ownership, and that is a meaningful disclosure for a private repository.

## Releases carry SLSA Level 3 provenance

One part of the project deserves attention that is easy to skip, and it is the opposite of a usual open source project habit.

To enhance the software supply chain security of legitify's users, as of v0.1.6, every legitify release contains a SLSA Level 3 Provenance document. The provenance document refers to all artifacts in the release, as well as the generated docker image. The SLSA framework's official verifier can be used to verify it, and the documentation gives the invocation for the darwin_arm64 architecture:

```bash
VERSION=0.1.6
ARCH=darwin_arm64
./slsa-verifier verify-artifact --source-branch main --builder-id 'https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@refs/tags/v1.2.2' --source-uri "git+https://github.com/Legit-Labs/legitify" --provenance-path multiple.intoto.jsonl ./legitify_${VERSION}_${ARCH}.tar.gz
```

This is a tool for checking supply chain risk publishing its own supply chain evidence, which is a reasonable thing for a security project to do.

The Dockerfile shows the same minimalism. The image is built FROM scratch, with only the CA certificate bundle copied in from an Alpine stage, the binary copied next, and the entrypoint set to it. There is no shell and no package manager in the final image, and the certificate file is the only thing the build had to add for TLS to work.

The release history is the thing to weigh. The recent releases are v1.0.11 from 2024-07-09, v1.0.10 from 2024-06-13 and v1.0.9 from 2024-06-11. The last push to the repository was on 2026-08-31 and the repository is not archived, so work is continuing, but the tagged history is more than two years old. There is a CHANGELOG.md in the repository, and that is where you would look for what has changed since the last tag.

## Where the policy scanner is the wrong tool

Three boundaries rule it out, and they are about the scope of the check rather than the quality of the implementation.

The first is code-level risk. legitify reads configuration. It does not scan your source, look for hardcoded secrets, or model your dependency graph, so if your concern is a vulnerable dependency or a leaked key in a commit, this is the wrong tool and OSSF scorecard integration does not change that.

The second is the commercial platform boundary. The README states plainly that Legit Security is the application security posture management and software supply chain security solution, and that there is a comparison table between the two. If you need a platform with dashboards, findings tracked over time, a policy editor and coverage beyond source code management platforms, then this is the component to build on, not the product to adopt, and the organisation maintaining it is the same one that sells the platform.

The third is the token. A tool that needs admin:org on a GitHub PAT and read:enterprise for enterprise coverage is asking for standing administrative authority over every organisation you own, delivered in a token that a scheduled workflow will use unattended. Where you cannot issue such a token, or where the read-only variants do not cover the policies you need to check, the tool is usable but its coverage is exactly the repository-level subset the documentation describes.

The reasonable way to evaluate it is to look at the policies directory in the repository, read the checks rather than the marketing, and decide whether they match your risk model. That is also the reason the tool is a good candidate for CI use, since a policy set you have read is a policy set you can trust in a pipeline.

## Conclusion

legitify fits a security team that already owns GitHub or GitLab organisations and wants configuration drift checked automatically on a schedule, because the policies are declarative, the ignore list is per policy name, and the action drops into an existing workflow. It is the wrong choice if you need a general application security posture management platform, since the project is the open source component of a commercial product rather than a replacement for one, and it is the wrong choice if you cannot issue a personal access token with organisation admin scopes. Before adopting it, read the policies directory in the repository to see exactly what is checked, confirm the PAT scopes you are willing to grant, and note that the gpt-analysis command sends repository and organisation metadata to OpenAI servers unless you leave it out of your pipeline.

## FAQ

### What is legitify and what does it check?

legitify is an open source Go tool that detects and remediates misconfigurations, security and compliance issues across GitHub and GitLab assets. The analyze command checks policies against all your resources, which the documentation names as organizations, repositories, members and actions, and archived repositories are skipped.

### How do I install and run legitify?

You can install it with brew install legitify, download a release archive containing the binary and the built-in policies, run it from source with go run main.go analyze, or install the gh-legitify GitHub CLI extension. A normal run is SCM_TOKEN=<your_token> legitify analyze.

### Which token scopes does legitify need?

It needs a GitHub personal access token, passed as -t or as SCM_TOKEN, and for full analysis the documented scopes are admin:org, read:enterprise, admin:org_hook, read:org and rep. To get the most out of the tool you need to be an owner of at least one GitHub organization.

### Can I run legitify on a schedule?

Yes. The project provides a Custom GitHub Action, and the example workflow uses a schedule trigger alongside workflow_dispatch, taking a github_token and an ignore-policies input listing policy names to skip.

### What licence is legitify released under and how current is it?

The repository is licensed under Apache-2.0. The recent releases are v1.0.11 from 2024-07-09, v1.0.10 from 2024-06-13 and v1.0.9 from 2024-06-11, and the last push to the repository was on 2026-08-31 with the repository not archived.

## Sources

- [Legit-Labs/legitify on GitHub](https://github.com/Legit-Labs/legitify)
- [License: Apache-2.0](https://github.com/Legit-Labs/legitify/blob/main/LICENSE)
- [Project website](https://legitify.dev)
- [README](https://github.com/Legit-Labs/legitify/blob/main/README.md)
- [Releases](https://github.com/Legit-Labs/legitify/releases)

---

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