Blueprints

Blueprints are a mechanism to help project to ensure that certain settings / files are present. They can be defined on global or organization level. Any configured blueprint is also displayed in the dashboard.

Blueprints are defined in an additive manner (contrary to policies), i.e. multiple blueprints of the same type might be active for a single organization. To distinguish blueprints of the same type, an additional id setting must be defined. If multiple blueprints use the same id value, only the first encountered blueprint will be taken into account.

If a blueprint is defined for an organization, otterdog will check if the matching repositories of the organization comply to the configuration of that blueprint. If this is not the case, a PR will be created to remediate the situation, e.g. by adding a file or updating its contents. The committers of an organization still need to manually merge the PR but are able to edit it prior to merging.

If such a remediation PR gets closed without being merged, the associated blueprint for that repository is put into state DISMISSED, and not further checks will be performed for that pair of blueprint / repository. In order to reinstate the checks, the PR needs to be reopened. Before remediating, otterdog also checks the latest PR of the blueprint branch (otterdog/blueprint/<id>) on GitHub: if it was closed without being merged, the blueprint is put into state DISMISSED again, so a dismissed remediation PR is never recreated, even if the stored status got lost.

Check frequency

Blueprints are evaluated when /internal/check is called, every 5 minutes by default (policies.schedule in the Helm chart). A blueprint is evaluated at most once per BLUEPRINT_CHECK_INTERVAL seconds for a given organization, one hour by default (config.blueprintCheckInterval in the Helm chart). Calls within that interval skip the blueprint, which is logged at debug level:

skipping blueprint with id '<id>' for org '<org>', last checked at '<date>'

A change to a blueprint definition is therefore picked up at the next evaluation, at most BLUEPRINT_CHECK_INTERVAL seconds later.

Configuration

Blueprints are defined using a yaml syntax and placed in the otterdog/blueprints folder of the config repository using either a .yml or .yaml extension.

Example

id: default-security-policy
name: Adds a default SECURITY.md file
description: |-
  This blueprint will create a PR that will add a default SECURITY.md file to the `.github` repo of your GitHub organization if it does not yet exist.
  You can adjust the PR as needed to fit it to your needs. If a repo defines a more specific SECURITY.md file it will take precedence of the one present in the `.github` repo.
type: required_file
config:
  repo_selector:
    name_pattern: .github
  files:
    - path: SECURITY.md
      content: |
        # Security Policy
        This Eclipse Foundation Project adheres to the [Eclipse Foundation Vulnerability Reporting Policy](https://www.eclipse.org/security/policy/).
        ...

Settings

Setting	Necessity	Description
id	mandatory	unique identification of the blueprint
name	optional	Name of the blueprint as displayed in the dashboard
description	optional	Description of the blueprint as displayed in the dashboard
type	mandatory	Type of the blueprint
config	mandatory	Custom configuration dependent on the type of blueprint