Forgejo

This role sets up and configures a Forgejo instance. It supports official binaries from https://codeberg.org/forgejo/forgejo or distribution-provided packages. Local user accounts can be created on deployment. It is also possible to configure external authentication sources.

Requirements

If TLS encryption (i.e. HTTPS) is desired, the target system needs to have a suitable X.509 certificate. This roles does not handle deploying certificates.

Forgejo needs a database server, unless it is configured to use SQLite. This role does not handle database configuration.

Forgejo's (optional) email system requires a SMTP server or a working sendmail program. This is not set up by this role either.

This role requires the community.general Ansible collection.

Role Variables

• forgejo_use_pkg
  Whether to prefer the distribution's package of Forgejo. Defaults to true but is set to false if the distribution is not known provide a package.
• forgejo_version
  What version of Forgejo to install from https://codeberg.org/forgejo/forgejo/. If left unset, the latest version (not including release candidates) is chosen. This setting is ignored when using a distribution package (cf. forgejo_use_pkg).
• forgejo_bind_address
  The IP address to bind to. Set to 0.0.0.0 to listen on all IP addresses. Defaults to 127.0.0.1.
• forgejo_port
  The TCP port to listen on. Defaults to 443 if forgejo_tls_cert is set and 80 if it is not.
• forgejo_tls_cert
  Path to a PEM-encoded X.509 certificate for Forgejo to use. The file needs to exist and be readable by the Forgejo user. Default is unset, which disables TLS support.
• forgejo_tls_cert_key
  Path to the PEM-encoded private key file for the certificate. The file needs to exist and be readable by the Forgejo user. Default is unset.
• forgejo_user, forgejo_group
  The system user account and system group to run Forgejo as. forgejo_user defaults to git; forgejo_group defaults to the user name. When using a distribution package (cf. forgejo_use_pkg), these settings are ignored.
• forgejo_data_path
  The path where repositories, user avatars and similar data is stored. Defaults to /var/lib/forgejo.
• forgejo_log_path
  The directory where Forgejo's log files are stored. Forgejo creates a number of log files for different purposes. Defaults to /var/log/forgejo.
• forgejo_loglevel
  The log level Forgejo's various loggers. Valid values are Trace, Debug, Info, Warn, Error, Critical, Fatal and None in decreasing order of verbosity. Fine tuning individual loggers is possible using forgejo_extra_options. Defaults to Info.
• forgejo_custom_path
  The path where custom files can be placed. These files allow customizing Forgejo. forgejo_custom_files can be used to deploy files to this path. Note: For security reasons, setting this to a directory within forgejo_data_path is not recommended. Defaults to /etc/forgejo/custom.
• forgejo_custom_files
  Path to a directory on the Ansible controller that contains files that should be deployed to forgejo_custom_path. Refer to the Forgejo documentation for details. Optional.
• forgejo_database_type
  The type of database that Forgejo should use to store user information, repository metadata, issues, etc. Valid values are mysql, postgres, mssql and sqlite3. Note that this role does not set up a database for Forgejo. This should be done by another role, unless using SQLite, which does not need any setup. Mandatory.
• forgejo_database_host
  The host name (and optionally port) of the database system. This can also be an absolute path to a UNIX socket, if the database runs on the same system as Forgejo. Mandatory, unless forgejo_database_type is sqlite3.
• forgejo_database_name
  The name of the database to use. When using SQLite, this is the path to the database file. If not set, Forgejo's internal default value is used.
• forgejo_database_user
  User account to use when connecting to the database. Mandatory, unless forgejo_database_type is sqlite3.
• forgejo_database_password
  The password for forgejo_database_user. Omit, if the database does not require a password.
• forgejo_enable_mailer
  Whether to enable the mailer (for password resets, etc.) and email notifications. Requires are working SMTP server, somewhere. Setting up an SMTP server is outside the scope of this role. Defaults to false unless forgejo_mailer_host is set.
• forgejo_mailer_host
  The host name (and optionally port) of a SMTP server to use for sending email. If the mailer is enabled without setting this option, the system's sendmail command is used. Optional.
• forgejo_mailer_from
  The sender address for mail generated by Forgejo in RFC 5322 format. Mandatory if the mailer is enabled.
• forgejo_mailer_user
  User account to use when connecting to the SMTP server. Optional.
• forgejo_mailer_password
  The password of forgejo_mailer_user. Optional.
• forgejo_enable_indexer
  Whether to enable the repository indexer. The indexer provides code search, but is known to use a fairly large amount of disk space. Defaults to true.
• forgejo_enable_lfs
  Whether to enable git-lfs support for storing large file more efficiently. Defaults to false.
• forgejo_enable_signing
  Whether to enable automatic singing of commits that are created via the web interface (e.g. on merges or repository initialisation). For this purpose a PGP key is generated and stored on the remote system. Note that a key is generated only once, and not regenerated, e.g. when the configured identity or other key parameters are changed. The exact conditions on when a signature is made can be fine tuned using forgejo_extra_options. Defaults to true.
• forgejo_signing_key_type
  The type of PGP key to generate. Valid values depend on the capabilities of the gpg program on the remote system. Defaults to RSA.
• forgejo_signing_key_length
  Length of the PGP key in bits. Defaults to 4096.
• forgejo_committer_name
  If forgejo_enable_signing is true, this is the name in the signing PGP key. The value may be used elsewhere as well. Defaults to Forgejo Bot.
• forgejo_committer_email
  If forgejo_enable_signing is true, this is the email address in the signing PGP key. The value may be used elsewhere as well. The email address does not need to exist. Defaults to invalid. Another generically useful value might be {{ forgejo_user }}@{{ ansible_facts['hostname'] }}.
• forgejo_users
  A list of local user account to set up within Forgejo. Note that this only allows creating users, but not modifying existing users. Each list item is in turn a dictionary with the following keys:
  • name
    The user's name. Needs to be unique within the Forgejo installation. Mandatory.
  • email
    The user's email address. Needs to be unique within the Forgejo installation. Mandatory.
  • password
    The user's password. Mandatory.
  • admin
    Whether to assign administrative privileges to the user. Defaults to false.
• forgejo_auth_providers
  A list of external authentication sources to set up within Forgejo. Each list item is in turn a dictionary with the following keys:
  • name The name of the authentication source. Needs to be unique within the Forgejo installation. Mandatory.
  • type
    The type of external authentication source to configure. Valid values are oauth, ldap and ldap-simple. Mandatory.
    If type is oauth, the following keys are used:
  • provider
    The name of the OAuth2 provider. Valid values are the names of providers supported by Forgejo, such as github, gitlab or twitter. Mandatory.
  • client_id
    The client ID for use with the OAuth2 provider. Mandatory.
  • client_secret
    The client secret for use with the OAuth2 provider. Mandatory.
  • auto_discover_url
    The OpenID auto discovery URL. Optional.
  • use_custom_urls
    Whether to use custom URLs if provider is github, gitlab or forgejo. Defaults to false.
  • custom_tenant_id
    A custom Tenant ID for OAuth2 endpoint (cf. use_custom_urls). Optional.
  • custom_auth_url
    A custom Authorization URL (cf. use_custom_urls). Optional.
  • custom_email_url
    A custom Email URL (cf. use_custom_urls). Optional.
  • custom_profile_url
    A custom Profile URL (cf. use_custom_urls). Optional.
  • custom_token_url
    A custom Token URL (cf. use_custom_urls). Optional.
    If type is ldap or ldap-simple, the following keys are used:
  • host
    The host name of the LDAP server to connect to. Mandatory.
  • port
    The TCP port the LDAP service runs on. Defaults to 389 or, if encryption is ldaps, to 636.
  • encryption
    How connections to the LDAP server should be encrypted. Valid values are disable, starttls and ldaps. Mandatory.
  • bind_dn
    If type is ldap: The DN to bind to the LDAP server with when searching for the user. Omit to perform an anonymous search. If type is ldap-simple: A template to use as the user's DN. %s is substituted with the login name given on sign-in form. Mandatory if type is ldap-simple.
  • bind_password
    The password for the user in bind_dn. Only used when type is ldap.
  • user_search_base
    The LDAP base at which user accounts will be searched for. Mandatory if type is ldap.
  • user_filter
    An LDAP filter declaring when a user should be allowed to log in. %s is substituted with login name given on sign-in form. Mandatory.
  • admin_filter
    An LDAP filter specifying if a user should be given administrator privileges. If a user account passes the filter, the user will be privileged as an administrator. Optional.
  • username_attribute
    The attribute of the user's LDAP record containing the user name. The attribute value will be used for new Forgejo accounts' user name after the first successful sign-in. Leave empty to use the login name given on sign-in form. This is useful when the supplied login name is matched against multiple attributes, but only a single specific attribute should be used for the Forgejo account name. Optional.
  • email_attribute
    The attribute of the user's LDAP record containing the user's email address. Defaults to mail.
  • firstname_attribute
    The attribute of the user's LDAP record containing the user's first name. Optional.
  • surname_attribute
    The attribute of the user's LDAP record containing the user's surname. Optional.
  • sshkey_attribute
    The attribute of the user's LDAP record containing the user's public SSH key. Optional.
  • sync_users
    This option enables a periodic task that synchronizes the Forgejo users with the LDAP server. Defaults to false.
• forgejo_runners
  A list of Forgejo runners to register for running CI/CD jobs. Note that the runners need to create a runner file in order to complete the registration. Each list item is a dictionary with the following keys:
  • name
    The name of the Forgejo runner instance. Mandatory.
  • scope
    An organization or repository name that may use this runner. If not set, all repositories may use the runner.
  • secret
    A 40-character long hexadecimal secret shared between this Forgejo instance and the Forgejo runner. Mandatory.
• forgejo_extra_options
  Additional configuration options for Forgejo. This variable is a dictionary where the keys are section names in app.ini. The values are in turn dictionaries where keys are Forgejo configuration options for the appropriate section and values are the corresponding configuration values. Refer to the Forgejo documentation for options and their meaning. Optional.
• forgejo_extra_groups
  A list of groups that the Forgejo system user is added to. This allows granting access to additional resources, such as the private key file. All groups need to exist on the target system; this role does not create them. Empty by default.
• forgejo_inaccessible_paths
  If the target system uses systemd, this option takes a list of paths, that should not be accessible at all for Forgejo. Regardless of this option, home directories are made inaccessible. Optional.

Dependencies

This role does not set up TLS certificates and therefore depends on a role that generates and deploys them, if TLS support is desired.

It also depends on a role to set up a MySQL/MariaDB, PostgreSQL or Microsoft SQL Server, respectively (possibly on a different system), if using a "full" DBMS is desired. Alternatively, SQLite can be used, which does not require any further setup.

Example Configuration

The following is a short example for some of the configuration options this role provides:

forgejo_bind_address: '0.0.0.0'
forgejo_database_type: 'mysql'
forgejo_database_host: '/run/mysqld/mysqld.sock'
forgejo_database_name: 'forgejo'
forgejo_database_user: 'git'
forgejo_inaccessible_paths:
  - '/var/lib/mysql'
forgejo_enable_mailer: true
forgejo_mailer_from: "{{ forgejo_user }}@{{ ansible_facts['fqdn'] }}"
forgejo_extra_options:
  server:
    LANDING_PAGE: 'explore'
  service:
    DISABLE_REGISTRATION: true
forgejo_users:
  - name: 'admin user'
    email: 'admin@my.domain'
    password: 'admin_password'
    admin: true
  - name: 'ordinary user'
    email: 'user@my.domain'
    password: 'user_password'
forgejo_auth_providers:
  - name: 'OpenLDAP'
    type: 'ldap'
    host: 'localhost'
    encryption: 'disable'
    bind_dn: 'cn=forgejo,ou=machines,dc=my,dc=domain'
    bind_password: 'some_password'
    user_search_base: 'ou=people,dc=my,dc=domain'
    user_filter: '(&(objectClass=posixAccount)(uid=%s))'
    admin_filter: '(memberOf=cn=Forgejo Admins,ou=groups,dc=my,dc=domain)'
    username_attribute: 'uid'
    email_attribute: 'mail'
    sshkey_attribute: 'sshPublicKey'
    sync_users: true

License

MIT