Organization settings and member privileges¶

The organization settings define what members can do in the organization and the policies that apply to all repositories. This guide covers the settings related to the security and the governance of the organization. The base permission of members is covered in Teams and access, the security managers in Repository security features.

Require two-factor authentication¶

Requiring two-factor authentication protects the organization against compromised passwords: members and outside collaborators without two-factor authentication are removed from the organization when it is enabled, see Requiring two-factor authentication in your organization.

two_factor_requirement is a read-only setting in otterdog: GitHub does not allow changing it through its API, it is enabled in the GitHub web interface by an owner of the organization. The configuration shows its current value after an import.

Restrict what members can do¶

The following settings define which actions are reserved to the owners of the organization:

The example default configuration disables all of them, so that repositories are only created, deleted or made public through the configuration. An organization that lets its members create teams and delete spam issues enables these settings:

orgs.newOrg('my-project', 'my-org') {
  settings+: {
    members_can_create_teams: true,
    members_can_delete_issues: true,
  },
}

Open in the Playground

Require a sign-off for commits made in the web interface¶

Some projects require contributors to sign off their commits, e.g. to confirm a developer certificate of origin. web_commit_signoff_required makes GitHub add the sign-off to the commits that are made in its web interface, e.g. when editing a file or applying a suggestion, see Managing the commit signoff policy for your organization.

orgs.newOrg('my-project', 'my-org') {
  settings+: {
    web_commit_signoff_required: true, // (1)!
  },
  _repositories+:: [
    orgs.newRepo('my-repo'),
  ],
}

1. When enabled on the organization, it applies to all repositories: a repository that disables it is reported as warning by validate, and its setting is ignored.

Open in the Playground

The sign-off of commits pushed from a local clone is added by the contributor, e.g. with git commit -s. It is not checked by this setting, but by a status check of a service or a workflow, which can be required with a ruleset, see Require status checks.

Classify repositories with custom properties¶

Custom properties add structured metadata to repositories, e.g. their category or their maturity. The organization defines the properties and their allowed values, each repository sets its values:

orgs.newOrg('my-project', 'my-org') {
  settings+: {
    custom_properties+: [
      orgs.newCustomProperty('category') {
        description: "Category used to group repositories",
        value_type: "single_select",
        allowed_values: [
          "library",
          "tool",
          "website",
          "other",
        ],
        required: true,
        default_value: "other", // (1)!
      },
    ],
  },
  _repositories+:: [
    orgs.newRepo('my-library') {
      custom_properties: {
        category: "library",
      },
    },
  ],
}

1. A required property needs a default value, which GitHub assigns to the repositories that do not set the property.

Open in the Playground

Custom properties can be used to filter the repositories of the organization on GitHub, and by tools that read them through the GitHub API, e.g. to generate an overview of the repositories, see Managing custom properties for repositories in your organization.

Organization rulesets can target repositories by custom properties on GitHub, but otterdog only supports targeting them by name, see Organization-wide rulesets.