Repository features and metadata¶

Repositories come with features that a project may or may not use, e.g. issues, a wiki, projects or discussions, and with metadata that help to find them, e.g. a description and topics. This guide shows how to enable the features that a project uses, how to set up discussions for the whole organization and how to describe repositories.

Enable only the features that are used¶

A feature that nobody looks at, e.g. a wiki that is not maintained or issues that are tracked elsewhere, misleads users. The following repository tracks its issues and discussions on GitHub, but keeps its documentation in the repository itself:

orgs.newOrg('my-project', 'my-org') {
  _repositories+:: [
    orgs.newRepo('my-repo') {
      has_issues: true,
      has_discussions: true,
      has_wiki: false,
      has_projects: false,
    },
  ],
}

Open in the Playground

Disabling a feature hides it but does not delete its content: issues, wiki pages and discussions come back when the feature is enabled again.

Discussions for the whole organization¶

Organization discussions are hosted in a repository of the organization, usually the .github repository, see Enabling GitHub Discussions for your organization:

orgs.newOrg('my-project', 'my-org') {
  settings+: {
    has_discussions: true,
    discussion_source_repository: "my-org/.github", // (1)!
  },
  _repositories+:: [
    orgs.newRepo('.github') {
      has_discussions: true, // (2)!
    },
  ],
}

1. The repository in the format <organization>/<repository>. Enabling has_discussions without it is reported as error by validate.
2. The source repository must keep discussions enabled, disabling them is reported as error.

Open in the Playground

readers_can_create_discussions controls whether users with read access can start discussions in the repositories of the organization, otherwise only users with at least triage permission can. Users with read access can comment on discussions in both cases.

Describe repositories¶

A description, a homepage and topics help users to find a repository and to understand its purpose. Topics are also used by the search of GitHub:

orgs.newOrg('my-project', 'my-org') {
  _repositories+:: [
    orgs.newRepo('my-library') {
      description: "A library to parse configuration files",
      homepage: "https://my-library.example.org",
      topics+: [
        "configuration",
        "parser",
        "java",
      ],
    },
  ],
}

Open in the Playground

GitHub limits these metadata, validate reports the following as error:

• a description longer than 350 characters
• more than 20 topics
• a topic with other characters than lower-case letters, numbers and -, e.g. GitHub Actions instead of github-actions

Templates, mirrors, forks and websites are covered in Common repository patterns.