Using Git

By default, WEISS allows users to clone public repositories and modify files locally. If you want to push to upstream or access private repositories, you need to configure a git service account token. This section guides you through it and how to manage repositories from WEISS.

Importing a repository

An user with the developer role can import a repository from the Browse projects sidebar:

  1. In Edit mode, open the right sidebar in the “Navigate” tab.

  2. Click the Import new repository button and provide:

    • Alias - a short local name for the repository.

    • Git URL - the HTTPS clone URL (e.g. https://github.com/org/opi-repo.git).

  3. WEISS clones the repository as a bare clone in the server storage volume and creates a working tree for the default branch.

Important

The Git URL must be accessible from the server running weiss-api. Private repositories require a properly configured technical account token (see Enabling commits section).

File visibility in the browser

Not all files in a cloned repository are shown in the file browser. Only the following types are displayed:

  • OPI files - files with the .opi.json extension.

  • Image files - files with the .svg, .png, .jpg, or .jpeg extension.

All other file types (scripts, configuration files, etc.) are ignored by the interface.

Additionally, files and folders whose name starts with _ (underscore) follow special visibility rules:

  • They are visible and selectable in Edit mode, allowing developers to organise internal or non-navigable assets inside a repository.

  • They are hidden and not selectable in Runtime mode, so operators never see them.

This convention lets you keep support files (e.g. shared symbol libraries, templates) alongside your OPIs without exposing them to end users.

Enabling commits

To be able to push commits to the upstream repositories, you should setup a technical account. The account must have a personal access token (PAT) with repository write permissions for the repositories you want to manage from WEISS. See setting up a technical account.

Why a technical account?

A technical account is a service identity - a regular git account created specifically for an application rather than a person - that WEISS uses to authenticate against the git hosting service when pushing commits. Some important keys to consider:

  • Operation is NOT anonymous. On top of the bot’s identity set in TECHNICAL_ACCOUNT_USERNAME and TECHNICAL_ACCOUNT_EMAIL, the LDAP identity of each user is also added to each commit, leaving a clear and auditable trail in the repository history. See example.

  • Access is minimal and revocable. The personal access token (PAT) can scoped to only the specific repositories and permissions it needs (write to contents). It can be revoked or rotated at any time without affecting any person’s account.

  • It does not share credentials. The alternative - using a developer’s personal token - would mean that person’s full account access is embedded in a shared server, and all commits would appear under their name even when triggered by others. A dedicated account avoids both risks.

  • It is auditable by IT. Because the account is explicitly requested and named, IT and security teams can monitor its activity, apply policies, and track it separately from human accounts.

Setting up a technical account

You may request one from your IT or git administrator, or create a bot account yourself if permitted. After that, logged in as the service user, generate a PAT that will be fed to WEISS app. The token must have repository write permission for every repository you want to manage from WEISS. Some useful links:

Note

Fine-grained tokens expire. It’s recommmended to rotate the token and redeploy when applicable.

For these settings, only the following variables in your .env file are relevant:

TECHNICAL_ACCOUNT_TOKEN="<personal-access-token>"
TECHNICAL_ACCOUNT_USERNAME="<technical-account-username>"   # used for git identity only
TECHNICAL_ACCOUNT_EMAIL="<technical-account-email>"         # used for git identity only

Warning

Treat the token like a password. Store it only in the .env file on the server, never commit it to a repository.