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.