Repository¶

Definition of a Repository for a GitHub organization, the following properties are supported:

Key	Value	Description	Notes
name	string	Name of the repository
aliases	list[string]	List of repository alias names, need to add previous name when renaming a repository
description	string or null	Project description
homepage	string or null	Link to the homepage
topics	list[string]	The list of topics of this repository
private	boolean	If the project is private
archived	boolean	If the repo is archived
allow_auto_merge	boolean	If auto merges are permitted
allow_forking	boolean	If the repo allows private forking
allow_merge_commit	boolean	If merge commits are permitted
allow_rebase_merge	boolean	If rebase merges are permitted
allow_squash_merge	boolean	If squash merges are permitted
allow_update_branch	boolean	If pull requests should suggest updates
auto_init	boolean	If the repository shall be auto-initialized during creation	only considered during creation
code_scanning_default_setup_enabled	boolean	If the repo has default code scanning enabled
code_scanning_default_query_suite	string	The query suite to use for default code scanning	`default` or `extended`, only taken into account when `code_scanning_default_setup_enabled` is set to true
code_scanning_default_languages	list[string]	The languages to analyze with code scanning default setup	`actions`, `c-cpp`, `csharp`, `go`, `java-kotlin`, `javascript`, `python`, `ruby`, `swift`, `rust` or `typescript`, only taken into account when `code_scanning_default_setup_enabled` is set to true. The deprecated value `javascript-typescript` is translated to `javascript` and `typescript`
custom_properties	dict[string, string \| list[string]]	The custom properties to set for this repository
default_branch	string	Name of the default branch
delete_branch_on_merge	boolean	If branches shall automatically be deleted after a merge
dependabot_alerts_enabled	boolean	If the repo has dependabot alerts enabled
dependabot_security_updates_enabled	boolean	If the repo has dependabot security updates enabled
gh_pages_build_type	string	If the repo has GitHub Pages enabled	`disabled`, `legacy` or `workflow`. Build-type `legacy` refers to building from a branch
gh_pages_cname	string or null	The custom domain of the GitHub Pages site	`null` to use the default `github.io` domain. The DNS records for the domain have to be configured separately
gh_pages_https_enforced	boolean	If HTTPS is enforced for the GitHub Pages site	only taken into account when `gh_pages_cname` is set, HTTPS is always enforced for the default `github.io` domain
gh_pages_source_branch	string or null	The branch from which GitHub Pages should be built	only taken into account when `gh_pages_build_type` is set to `legacy`
gh_pages_source_path	string or null	The folder from which GitHub Pages should be built	only taken into account when `gh_pages_build_type` is set to `legacy`
gh_pages_visibility	string	The visibility of the GitHub Pages site	`public` or `private`. Only available for private repositories in enterprise organizations with `members_can_create_private_pages` enabled
has_discussions	boolean	If the repo has discussions enabled
has_issues	boolean	If the repo can have issues
has_projects	boolean	If the repo can have projects
has_wiki	boolean	If the repo has a wiki
is_template	boolean	If the repo is can be used as a template repository
merge_commit_message	string	Can be PR_BODY, PR_TITLE, or BLANK for a default merge commit message
merge_commit_title	string	Can be PR_TITLE or MERGE_MESSAGE for a default merge commit title
post_process_template_content	list[string]	A list of content paths in a template repository that shall be processed after creation	only considered during creation
private_vulnerability_reporting_enabled	boolean	If the repo has private vulnerability reporting enabled
secret_scanning	string	If secret scanning is "enabled" or "disabled"
secret_scanning_push_protection	string	If secret scanning push protection is "enabled" or "disabled"
squash_merge_commit_message	string	Can be PR_BODY, COMMIT_MESSAGES, or BLANK for a default squash merge commit message
squash_merge_commit_title	string	Can be PR_TITLE or COMMIT_OR_PR_TITLE for a default squash merge commit title
team_permissions	dict[string, string]	Permissions granted to organization teams on this repository	see Team Permissions for details
code_security_configuration	string or null	The name of the code security configuration attached to this repository	see Code Security Configuration, `null` keeps the configuration attached on GitHub, the security settings it sets are not managed on the repository
template_repository	string or null	The template repository to use when creating the repo	read-only, only considered during creation
forked_repository	string or null	The repository to fork when creating the repo	only considered during creation
fork_default_branch_only	boolean	When creating a fork, whether only the default branch will be included in the fork	only considered during creation
immutable_releases_enabled	boolean	If immutable releases are enabled for this repository	Can be overridden by organization-level immutable release settings
web_commit_signoff_required	boolean	If the repo requires web commit signoff
workflows	Workflow Settings	Workflow settings on organizational level
webhooks	list[Webhook]	webhooks defined for this repo, see section above for details
secrets	list[RepositorySecret]	secrets defined for this repo, see section below for details
dependabot_secrets	list[RepositoryDependabotSecret]	Dependabot secrets defined for this repo
codespaces_secrets	list[RepositoryCodespacesSecret]	Codespaces secrets defined for this repo
variables	list[RepositoryVariable]	variables defined for this repo, see section below for details
environments	list[Environment]	environments defined for this repo, see section below for details
branch_protection_rules	list[BranchProtectionRule]	branch protection rules of the repo, see section below for details
rulesets	list[RepositoryRuleset]	rulesets of the repo, see section below for details

Embedded Models¶

Workflow Settings¶

Key	Value	Description	Notes
enabled	boolean	If GitHub actions are enabled for this repository
max_cache_size_gb	integer	Maximum total size of all GitHub Actions caches, in GB
allowed_actions	string	Defines which type of GitHub Actions are permitted to run	`all`, `local_only` or `selected`
allow_github_owned_actions	boolean	If GitHub owned actions are permitted to run	Only taken into account when `allowed_actions` is set to `selected`
allow_verified_creator_actions	boolean	If GitHub Actions from verified creators are permitted to run	Only taken into account when `allowed_actions` is set to `selected`
allow_action_patterns	list[string]	A list of action patterns permitted to run	Only taken into account when `allowed_actions` is set to `selected`
default_workflow_permissions	string	The default workflow permissions granted to the GITHUB_TOKEN	`read` or `write`
actions_can_approve_pull_request_reviews	boolean	If actions can approve and merge pull requests
fork_pr_approval_policy	string	Controls when fork PR workflows require approval from a maintainer	`first_time_contributors_new_to_github`, `first_time_contributors` or `all_external_contributors`

Increasing the cache size limit may incur costs. Changes to the limit are flagged for designated review and are not eligible for automatic merging.

Team Permissions¶

The team_permissions property maps the slug of an organization team to the permission this team has on the repository:

team_permissions: {
  'committers': 'push',
  'project-leads': 'maintain',
},

Permission	GitHub role	Description
`pull`	Read	Can read and clone the repository, open and comment on issues and pull requests
`triage`	Triage	Can manage issues and pull requests without write access
`push`	Write	Can read, clone and push to the repository
`maintain`	Maintain	Can manage the repository without access to sensitive or destructive actions
`admin`	Admin	Full access to the repository, including sensitive and destructive actions

Teams are referenced by their slug (e.g. a team named Project Leads has the slug project-leads), not by their display name. The team must exist in the organization, e.g. defined via orgs.newTeam.

Note

Team permissions are only managed when the default repository configuration of the template defines team_permissions, e.g. team_permissions: {}. Otherwise, otterdog does not retrieve the current team permissions from GitHub and any team_permissions set on a repository are ignored.

Warning

Once managed, team_permissions is authoritative: any team that has access to the repository on GitHub but is not listed will have its access removed. With team_permissions: {} as default value, this applies to every repository that does not explicitly declare its teams. Run otterdog plan to review such removals before applying. Permissions of individual collaborators are not affected, nor are permissions of teams excluded with exclude_teams unless the repository lists them, see Teams managed by another tool.

Jsonnet Function¶

newextend

orgs.newRepo('<name>') {
  <key>: <value>
}

orgs.extendRepo('<name>') {
  <key>: <value>
}

Note

In general, you will only ever use orgs.newRepo as this function will define a new repository with default values. However, in some cases it might be needed to change properties for a repo that has already been defined in the default configuration. In such situation, you should use orgs.extendRepo.

Validation rules¶

specifying a description of more than 350 characters triggers an error (maximum supported length by GitHub)
specifying more than 20 topics triggers an error (maximum number of supported topics by GitHub)
disabling has_discussions while this repository is configured as source repository for discussion of this organization triggers an error
specifying a template_repository and forked_repository at the same time triggers an error
specifying a non-empty list of allow_action_patterns while allowed_actions is not set to selected, triggers a warning
specifying a permission in team_permissions other than pull, triage, push, maintain or admin triggers an error
specifying a code_security_configuration that is not defined in the code_security_configurations of the organization triggers an error
specifying a gh_pages_cname that is not a valid domain name or that is a github.io domain triggers an error
disabling secret_scanning while secret_scanning_push_protection is enabled triggers an error
specifying code_scanning_default_languages for a repository that does not exist yet, or with a language that is not detected in the repository, triggers an error

Tip

Changing the default branch of a repository has the same behavior as doing it via the Web UI. If the new branch already exists, the default branch will be switched, otherwise, the current default branch will be renamed to the newly specified name.

Note

When enabling GitHub Pages by setting gh_pages_build_type to either legacy or workflow, you should also define a github-pages environment, as it will be created automatically by GitHub.

Note

Setting gh_pages_cname only configures the custom domain on GitHub, the DNS records of the domain need to be configured separately, see configuring a custom domain. It is recommended to also verify the domain for the organization to prevent domain takeovers.

The HTTPS enforcement can only be changed once GitHub has issued a certificate for the custom domain, which can take some time after the domain has been configured. Until then, GitHub rejects any change to gh_pages_https_enforced, otterdog only logs a warning in that case and the change will be retried on the next apply.

When building GitHub Pages from a branch (legacy build type), GitHub stores the custom domain in a CNAME file at the root of the publishing source. If that file gets removed, e.g. by a workflow overwriting the branch, the custom domain will be removed as well.

Warning

Specifying a code scanning language that is not detected by GitHub in the repo itself will lead to an error during applying. In general, default setup for code scanning should be used with care as it has some weird behavior, using a custom workflow is the preferred way to use CodeQL. For the custom workflow to succeed, you need to disable the default setup though.

Example usage¶

jsonnet

orgs.newOrg('adoptium') {
  ...
  _repositories+:: [
    ...
    orgs.newRepo('.github') {
      allow_auto_merge: true,
      allow_merge_commit: false,
      allow_update_branch: false,
      dependabot_alerts_enabled: false,
      web_commit_signoff_required: false,
      workflows+: {
        enabled: false,
        max_cache_size_gb: 50,
      },
      branch_protection_rules: [
        orgs.newBranchProtectionRule('main'),
      ],
      team_permissions: {
        'committers': 'push',
      },
    },
}