ossf/allstarGitHub App to set and enforce security policies
[!IMPORTANT] The OpenSSF-hosted Allstar GitHub App has been retired. Allstar, the OpenSSF Scorecard subproject, itself continues to be maintained — you must now run it yourself, either as a GitHub Action or as a service daemon.
See ossf/allstar#881 for more details.
If your organization was relying on the hosted app, see Migrating off the hosted app.
Allstar is a GitHub App that continuously monitors GitHub organizations or repositories for adherence to security best practices. If Allstar detects a security policy violation, it creates an issue to alert the repository or organization owner. For some security policies, Allstar can also automatically change the project setting that caused the violation, reverting it to the expected state.
Allstar’s goal is to give you finely tuned control over the files and settings that affect the security of your projects. You can choose which security policies to monitor at both the organization and repository level, and how to handle policy violations. You can also develop or contribute new policies.
Allstar is developed as a part of the OpenSSF Scorecard project.
If you're getting unwanted issues created by Allstar, follow these directions to opt out.
Allstar is highly configurable. There are three main levels of controls:
These configurations are done in the organization's .allstar repository.
Repo level: Repository maintainers in an organization that uses
Allstar can choose to opt their repository in or out of organization-level
enforcements. Note: these repo-level controls are only functional when "repo
override" is allowed in the org-level settings. These configurations are
done in the repository's .allstar directory.
Policy level: Administrators or maintainers can choose which policies
are enabled on specific repos and which actions Allstar takes when a policy
is violated. These configurations are done in a policy yaml file in either
the organization's .allstar repository (admins), or the repository's
.allstar directory (maintainers).
Before installing Allstar at the org level, you should decide approximately how many repositories you want Allstar to run on. This will help you choose between the Opt-In and Opt-Out strategies.
The Opt In strategy allows you to manually add the repositories you'd like Allstar to run on. If you do not specify any repositories, Allstar will not run despite being installed. Choose the Opt In strategy if you want to enforce policies on only a small number of your total repositories, or want to try out Allstar on a single repository before enabling it on more. Since the v4.3 release, globs are supported to easily add multiple repositories with a similar name.
The Opt Out strategy (recommended) enables Allstar on all repositories and allows you to manually select the repositories to opt out of Allstar enforcements. You can also choose to opt out all public repos, or all private repos. Choose this option if you want to run Allstar on all repositories in an organization, or want to opt out only a small number of repositories or specific type (i.e., public vs. private) of repository. Since the v4.3 release, globs are supported to easily add multiple repositories with a similar name.
| Opt Out (Recommended) optOutStrategy = true |
Opt In optOutStrategy = false |
|
|---|---|---|
| Default behavior | All repos are enabled | No repos are enabled |
| Manually adding repositories | Manually adding repos disables Allstar on those repos | Manually adding repos enables Allstar on those repos |
| Additional configurations | optOutRepos: Allstar will be disabled on the listed repos optOutPrivateRepos: if true, Allstar will be disabled on all private repos optOutPublicRepos: if true, Allstar will be disabled on all public repos (optInRepos: this setting will be ignored) |
optInRepos: Allstar will be enabled on the listed repos (optOutRepos: this setting will be ignored) |
| Repo Override | If true: Repos can opt out of their organization's Allstar enforcements
using the settings in their own repo file. Org level opt-in settings that
apply to that repository are ignored. If false: repos cannot opt out of Allstar enforcements as configured at the org level. |
If true: Repos can opt in to their organization's Allstar enforcements even
if they are not configured for the repo at the org level. Org level opt-out
settings that apply to that repository are ignored. If false: Repos cannot opt into Allstar enforcements if they are not configured at the org level. |
Allstar acts on your organization as a GitHub App: you create the app, and you run the process that authenticates as it. Setup is therefore two steps that are common to every deployment — create the app and create the control repository — and then a choice of how to run it:
