allstar

# **Allstar** > [!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](#running-allstar-as-a-github-action) or > [as a service daemon](#running-allstar-as-a-service-daemon). > > See [ossf/allstar#881](https://github.com/ossf/allstar/issues/881) for > more details. > > If your organization was relying on the hosted app, see > [Migrating off the hosted app](#migrating-off-the-hosted-app). ## Overview - [What Is Allstar?](#what-is-allstar) ## What's new with Allstar - [whats-new.md](whats-new.md) ## Disabling Unwanted Issues - [Help! I'm getting issues created by Allstar and I don't want them!](#disabling-unwanted-issues-1) ## Getting Started - [Background](#background) - [Org-Level Options](#org-level-options) - [Installation Options](#installation-options) - [Create your GitHub App](#create-your-github-app) - [Create your `.allstar` control repository](#create-your-allstar-control-repository) - [Running Allstar as a GitHub Action](#running-allstar-as-a-github-action) - [Running Allstar as a service daemon](#running-allstar-as-a-service-daemon) - [Migrating off the hosted app](#migrating-off-the-hosted-app) ## Policies and Actions - [Actions](#actions) - [Policies](#policies) ## Advanced - [Configuration Definitions](#configuration-definitions) - [Example Configurations](#example-config-repository) - [Run Your Own Instance of Allstar](operator.md) ## Contribute - [Contributing](#contributing) ________ ________ ## Overview ### What is Allstar? 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](https://github.com/ossf/scorecard) project. ## [What's new with Allstar](whats-new.md) ## Disabling Unwanted Issues If you're getting unwanted issues created by Allstar, follow [these directions](opt-out.md) to opt out. ## Getting Started ### Background Allstar is highly configurable. There are three main levels of controls: - **Org level**: Organization administrators can choose to enable Allstar on: - all repositories in the org; - most repositories, except some that are opted out; - just a few repositories that are opted in. 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). ### Org-Level Options 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.

### Installation Options 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](#create-your-github-app) and [create the control repository](#create-your-allstar-control-repository) — and then a choice of how to run it: | | [GitHub Action](#running-allstar-as-a-github-action) | [Service daemon](#running-allstar-as-a-service-daemon) | |---|---|---| | **How it runs** | Scheduled job in your `.allstar` repo | Persistent process you host | | **You provide** | Nothing beyond GitHub | A server or container orchestrator | | **Cadence** | Whatever you set the `cron` to | Continuous, with results in 5-10 minutes | | **Setup effort** | Moderate | High | | **Best when** | You want the lowest-infrastructure option | You want the most control, or already run services | The Action is the lower-overhead of the two and is where most organizations should start; you can move to a daemon later without changing any policy configuration. #### Create your GitHub App An App is a user-like identity with a set of permissions in your organization. Allstar needs read access to most settings and file contents in order to detect compliance, and write access to issues and checks in order to file issues and support the `block` action. Follow [Operator instructions - Create a GitHub App](operator.md#create-a-github-app), and record the App ID and private key. Both run modes need them. #### Create your `.allstar` control repository Allstar reads its configuration from a repository named `.allstar` in your organization. The fastest way to create one is from the sample: 1. [Open the sample repository](https://github.com/ossf/dot-allstar-quickstart) and click the "Use this template" button 1. In the field for Repository Name, type `.allstar` 1. Click "Create repository from template" This enables all current Allstar [policies](#policies) on all repositories using the Opt Out strategy, with the `issue` action. You can change any of it later. For granular control from the start — choosing the Opt In or Opt Out strategy and writing individual policy files yourself — follow the [manual installation directions](manual-install.md) instead. #### Running Allstar as a GitHub Action This option runs Allstar as a scheduled job using GitHub Actions, so there is no infrastructure to operate beyond GitHub itself. Follow the [GitHub Actions installation directions](github-action-installation.md) to set up a recurring Action in your `.allstar` repository, harden it, and monitor its results. #### Running Allstar as a service daemon This option runs Allstar as a persistent process, which detects and resolves violations continuously rather than on a schedule. See [Operator instructions](operator.md) for running the process, managing secrets, sizing, and the available environment variables. ### Migrating off the hosted app If your organization used the OpenSSF-hosted app, **your configuration carries over as-is**. The `.allstar` control repository, `allstar.yaml`, and every policy file keep working unchanged; what you are replacing is only the process that reads them. To migrate: 1. [Create your own GitHub App](#create-your-github-app) and install it on your organization with the same repository access the hosted app had. 1. Keep your existing `.allstar` repository exactly as it is. 1. Run Allstar [as an Action](#running-allstar-as-a-github-action) or [as a daemon](#running-allstar-as-a-service-daemon). 1. Uninstall `allstar-app` from your organization, if it still appears under Settings -> GitHub Apps. Issues previously filed by the hosted app remain in your repositories. Your own instance identifies its issues by the same `allstar` label (or your configured `issueLabel`), so it will adopt and close them as violations are resolved, rather than filing duplicates. ## Policies and Actions ## **Actions** Each policy can be configured with an action that Allstar will take when it detects a repository to be out of compliance. - `log`: This is the default action, and actually takes place for all actions. All policy run results and details are logged. Logs are currently only visible to the app operator, plans to expose these are under discussion. - `issue`: This action creates a GitHub issue. Only one issue is created per policy, and the text describes the details of the policy violation. If the issue is already open, it is pinged with a comment every 24 hours without updates (not currently user configurable). If the policy result changes, a new comment will be left on the issue and linked in the issue body. Once the violation is addressed, the issue will be automatically closed by Allstar within 5-10 minutes. - `fix`: This action is policy specific. The policy will make the changes to the GitHub settings to correct the policy violation. Not all policies will be able to support this (see below). Proposed, but not yet implemented actions. Definitions will be added in the future. - `block`: Allstar can set a [GitHub Status Check](https://docs.github.com/en/github/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks) and block any PR in the repository from b