Features from any forge

Table of contents

Introduction

A product can mix features from GitHub, GitLab, Gitea, Forgejo or any other git host. Each reference names the host it comes from, the way a Go module path or a Terraform module address does.

[tool.splent]
features = [
    "splent-io/splent_feature_accounts@v1.2.0",
    "github.com/drorganvidez/splent_feature_notes@v0.2.0",
    "gitlab.com/acme/splent_feature_billing@v1.0.0",
    "git.lab.example/lab/splent_feature_wiki",
]

The CLI clones, upgrades and releases each feature on its own host. Inside the product nothing changes. The cache, the symlinks, the Python package and the application know a feature by namespace/repository, wherever it comes from.


Writing a reference

Reference Comes from
github.com/acme/splent_feature_x@v1.0.0 github.com
git.example.org:3000/acme/splent_feature_x git.example.org, port 3000
acme/splent_feature_x@v1.0.0 The product’s default forge
splent_feature_x@v1.0.0 The default forge, namespace splent-io

Three parts mean the first one is the host. A host has a dot or a port, or is localhost, the same rule Docker applies to image names. The @version part works as always, and a reference without it is editable.

Every command that takes a feature takes the long form too, and writes it to pyproject.toml as you typed it.

splent feature:add github.com/drorganvidez/splent_feature_notes@v0.2.0

Upgrading or pinning a feature keeps its host.

GitLab subgroups (gitlab.com/group/subgroup/repo) are not supported. A namespace is one level, as on GitHub and Gitea.


The default forge

A reference without a host comes from git.splent.io, unless you say otherwise. A product changes it for all its short references.

[tool.splent]
forge = "github.com"
features = ["acme/splent_feature_x@v1.0.0"]

A workspace changes it with SPLENT_FORGE_HOST and the other variables in tokens:setup. The product setting wins, because it travels with the product.


Hosts that need more detail

The host name is enough for github.com, gitlab.com, and for a Gitea or Forgejo server with SSH on port 22. When a server needs more, describe it under [tool.splent.forges], keyed by host. This holds connection details only, never which feature comes from where.

[tool.splent.forges."git.lab.example"]
kind = "gitea"
ssh_port = 2222
Key Default
kind github for github.com, gitlab for gitlab.com and hosts starting with gitlab., otherwise forgejo. gitea means the same as forgejo
ssh_host The host
ssh_port 22
api https://api.github.com, https://<host>/api/v4 for GitLab, https://<host>/api/v1 for Gitea and Forgejo
token_env SPLENT_TOKEN_<host>
user_env SPLENT_USER_<host>

check:features reports a table it cannot use, a reference it cannot read, and a feature declared from two different hosts.


Tokens for each host

Public repositories need no token. For private ones, and to release, give each host its own token in the workspace .env. The variable carries the host, as Terraform’s TF_TOKEN_<host> does. Dots and colons become _ and dashes become __, so git.lab-x.org reads SPLENT_TOKEN_git_lab__x_org.

SPLENT_TOKEN_github_com=ghp_xxxxxxxxxxxxxxxxxxxxxxxx
SPLENT_TOKEN_gitlab_com=glpat-xxxxxxxxxxxxxxxxxxxx
SPLENT_TOKEN_git_lab_example=xxxxxxxxxxxxxxxxxxxxxxxx

The usual vendor variables work too. They are GITHUB_TOKEN or GH_TOKEN for github.com and GITLAB_TOKEN for gitlab.com. The default forge keeps reading SPLENT_FORGE_TOKEN.

Each token goes to its own host and nowhere else. git receives it as a header scoped to that host, and API calls for a feature on GitHub never carry the token of another forge. A host without a token falls back to your SSH key or to git’s own credential helper.


See also


Back to top

splent. Distributed by an LGPL license v3. Contact us: drorganvidez@us.es