Repository templates

A template repository is a starting point: a README, a CI pipeline, a Taskfile, a Cargo.toml… A new repository generated from it gets a copy of its files, and Forgejo replaces variables such as $REPO_NAME along the way. Its README title, package name or file names then match the new repository from the first commit.

This guide sets up one template shared by every team, generates repositories from it, and restricts who may use it.

Before you beginCopy Anchor Link

• A ForgejoOrganization to hold the template, for example batlehub (see Users, OIDC and teams).
• For the generated repositories, an organization or user each team may use (see Repositories).

Set up a shared templateCopy Anchor Link

*.md
**/*.md
Cargo.toml
src/**

# $REPO_NAME

$REPO_DESCRIPTION

    git clone $REPO_HTTPS_URL

[package]
name = "${REPO_NAME_SNAKE}"

apiVersion: forgejo.weebo.io/v1alpha1
kind: ForgejoRepository
metadata:
  name: weebo-base
  namespace: platform
spec:
  organizationRef: { name: batlehub }
  name: weebo-base
  isTemplate: true
  migrate:
    cloneAddr: https://github.com/batleforc/weebo-base.git
    mirror: true
    mirrorInterval: 8h
    # authSecretRef: { name: github, tokenKey: token }   # private source

apiVersion: forgejo.weebo.io/v1alpha1
kind: ForgejoNamespacePolicy
metadata:
  name: teams
spec:
  rules:
    - namespaces: ["team-*"]
      allowedKinds: [ForgejoRepository]
      allowedOrganizations: [weebo]
      allowedTemplates: ["batlehub/*"]

apiVersion: forgejo.weebo.io/v1alpha1
kind: ForgejoRepository
metadata:
  name: my-app
  namespace: team-a
spec:
  organizationRef: { name: weebo }
  name: my-app
  description: Billing service   # becomes $REPO_DESCRIPTION
  private: true
  fromTemplate:
    repository: batlehub/weebo-base

VariablesCopy Anchor Link

Tested on Forgejo 16, for a repository weebo/my-app generated from batlehub/weebo-base:

${REPO_NAME} is the same as $REPO_NAME; use the braces when a letter, digit or _ follows the variable.

Changing the caseCopy Anchor Link

Add a suffix to any variable to change its case. For a repository named my-cool-app:

An unknown name, such as ${REPO_NAME_DOT}, is left as is.

Good to knowCopy Anchor Link

• Creation only. Variables are replaced once, when the repository is generated. Later changes to the template don't reach existing repositories, and changing fromTemplate afterwards has no effect.

• What else to copy. fromTemplate copies the files (gitContent, on by default) and can also copy topics, labels, webhooks, gitHooks and avatar. Settings (visibility, units, default branch) and team access come from the new repository's own spec.

• Copied branch protections. With protectedBranches: true, leave the new repository's branchProtections unset to keep the template's rules: the operator then doesn't touch them. Once you set branchProtections, it replaces them (a copied rule it doesn't list is deleted).

• A template of your own team. A template that is a ForgejoRepository in the same namespace can be referenced by CR name instead: fromTemplate: { repositoryRef: { name: weebo-base } }. It isn't subject to allowedTemplates.

• If it fails.

  Reason	Cause
  ReferenceNotFound	No repository owner/name in Forgejo. The repository is generated as soon as the template appears (a template CR becoming Ready triggers it right away).
  ForgejoApiError "this is not a template repo"	The repository exists but isn't marked as a template: set isTemplate: true.
  NamespaceNotAllowed	No policy rule's allowedTemplates covers the template for this namespace.
  InvalidSpec	Both repository and repositoryRef set, or repository isn't owner/name.

NextCopy Anchor Link

Credentials.