mirror of
https://github.com/runkids/skillshare.git
synced 2026-11-18 18:04:17 +00:00
These headings mix prose with technical terms (e.g. '.skillignore (Optional)', 'Git Authentication', 'Target include/exclude filters') and are referenced by anchor fragment from other pages. Translating the prose changes the auto-generated slug and breaks the link, so pin the current slug explicitly before the next translation batch.
468 lines
14 KiB
Markdown
468 lines
14 KiB
Markdown
---
|
|
sidebar_position: 2
|
|
---
|
|
|
|
# Environment Variables
|
|
|
|
All environment variables recognized by skillshare.
|
|
|
|
## Configuration
|
|
|
|
### SKILLSHARE_CONFIG
|
|
|
|
Override the config file path.
|
|
|
|
```bash
|
|
SKILLSHARE_CONFIG=~/custom-config.yaml skillshare status
|
|
```
|
|
|
|
**Default:** `~/.config/skillshare/config.yaml`
|
|
|
|
---
|
|
|
|
### XDG_CONFIG_HOME
|
|
|
|
Override the base configuration directory per the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir/latest/).
|
|
|
|
```bash
|
|
export XDG_CONFIG_HOME=~/my-config
|
|
# skillshare will use ~/my-config/skillshare/
|
|
```
|
|
|
|
**Default behavior:**
|
|
|
|
| Platform | Default |
|
|
|----------|---------|
|
|
| Linux | `~/.config/skillshare/` |
|
|
| macOS | `~/.config/skillshare/` |
|
|
| Windows | `%AppData%\skillshare\` |
|
|
|
|
**Priority:** `SKILLSHARE_CONFIG` > `XDG_CONFIG_HOME` > platform default.
|
|
|
|
:::note
|
|
If you set `XDG_CONFIG_HOME` after initial setup, move your existing `~/.config/skillshare/` directory to the new location manually.
|
|
:::
|
|
|
|
---
|
|
|
|
### XDG_DATA_HOME
|
|
|
|
Override the data directory (backups, trash).
|
|
|
|
```bash
|
|
export XDG_DATA_HOME=~/my-data
|
|
# skillshare will use ~/my-data/skillshare/backups/ and ~/my-data/skillshare/trash/
|
|
```
|
|
|
|
**Default:** `~/.local/share/skillshare/`
|
|
|
|
---
|
|
|
|
### XDG_STATE_HOME
|
|
|
|
Override the state directory (operation logs).
|
|
|
|
```bash
|
|
export XDG_STATE_HOME=~/my-state
|
|
# skillshare will use ~/my-state/skillshare/logs/
|
|
```
|
|
|
|
**Default:** `~/.local/state/skillshare/`
|
|
|
|
---
|
|
|
|
### XDG_CACHE_HOME
|
|
|
|
Override the cache directory (version check cache, UI dist cache).
|
|
|
|
```bash
|
|
export XDG_CACHE_HOME=~/my-cache
|
|
# skillshare will use ~/my-cache/skillshare/
|
|
```
|
|
|
|
**Default:** `~/.cache/skillshare/`
|
|
|
|
:::tip Automatic migration
|
|
Starting from v0.13.0, skillshare follows the XDG Base Directory Specification for backups, trash, and logs. If you're upgrading from an older version, these directories are automatically migrated from `~/.config/skillshare/` to their proper XDG locations on first run.
|
|
:::
|
|
|
|
---
|
|
|
|
### SKILLSHARE_GITLAB_HOSTS
|
|
|
|
Comma-separated list of self-managed GitLab hostnames to treat with nested subgroup support. Useful in CI/CD where you may not have a config file.
|
|
|
|
```bash
|
|
SKILLSHARE_GITLAB_HOSTS=git.company.com,code.internal.io skillshare install git.company.com/team/frontend/ui
|
|
```
|
|
|
|
When both the env var and config file [`gitlab_hosts`](/docs/reference/targets/configuration#gitlab_hosts) are set, their values are **merged** (deduplicated). Invalid entries (containing scheme, path, port, or empty) are silently skipped.
|
|
|
|
**Default:** None (only config file values are used)
|
|
|
|
---
|
|
|
|
### SKILLSHARE_AZURE_HOSTS
|
|
|
|
Comma-separated list of self-hosted Azure DevOps Server hostnames.
|
|
|
|
```bash
|
|
SKILLSHARE_AZURE_HOSTS=azuredevops.mycompany.com,tfs.internal.io
|
|
```
|
|
|
|
When both the env var and config file [`azure_hosts`](/docs/reference/targets/configuration#azure_hosts) are set, their values are **merged** (deduplicated). Invalid entries in the env var are silently skipped.
|
|
|
|
**Default:** _(none)_
|
|
|
|
### SKILLSHARE_GITEA_HOSTS
|
|
|
|
Comma-separated list of self-hosted Gitea hostnames. Hosts containing `gitea` in the name are detected without it.
|
|
|
|
```bash
|
|
SKILLSHARE_GITEA_HOSTS=git.company.com,code.internal.io
|
|
```
|
|
|
|
Merged with the config file's [`gitea_hosts`](/docs/reference/targets/configuration#gitea_hosts).
|
|
|
|
**Default:** _(none)_
|
|
|
|
### SKILLSHARE_CNB_HOSTS
|
|
|
|
Comma-separated list of self-hosted CNB hostnames. `cnb.cool` is detected without it.
|
|
|
|
```bash
|
|
SKILLSHARE_CNB_HOSTS=cnb.company.com
|
|
```
|
|
|
|
Merged with the config file's [`cnb_hosts`](/docs/reference/targets/configuration#cnb_hosts).
|
|
|
|
**Default:** _(none)_
|
|
|
|
---
|
|
|
|
## Web UI
|
|
|
|
### SKILLSHARE_UI_BASE_PATH
|
|
|
|
Set the URL sub-path for serving the web dashboard behind a reverse proxy.
|
|
|
|
```bash
|
|
SKILLSHARE_UI_BASE_PATH=/skillshare skillshare ui --host 0.0.0.0 --no-open
|
|
```
|
|
|
|
Equivalent to `--base-path /skillshare`. The flag takes precedence if both are set.
|
|
|
|
**Default:** None (dashboard served at root `/`)
|
|
|
|
See [Reverse Proxy](/docs/reference/commands/ui#reverse-proxy) for Nginx and Caddy examples.
|
|
|
|
---
|
|
|
|
## GitHub API
|
|
|
|
### GITHUB_TOKEN
|
|
|
|
GitHub personal access token.
|
|
|
|
**Used for:**
|
|
- GitHub API requests (`skillshare search`, `skillshare upgrade`, version check)
|
|
- **Git clone authentication** — automatically injected when installing private repos via HTTPS
|
|
|
|
**Creating a token:**
|
|
1. Go to https://github.com/settings/tokens
|
|
2. Generate new token (classic)
|
|
3. Scope: `repo` for private repos, none for public repos
|
|
4. Copy the token
|
|
|
|
Official docs: [Managing your personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)
|
|
|
|
**Usage:**
|
|
```bash
|
|
export GITHUB_TOKEN=ghp_your_token_here
|
|
skillshare install https://github.com/org/private-skills.git --track
|
|
```
|
|
|
|
**Windows:**
|
|
```powershell
|
|
# Current session
|
|
$env:GITHUB_TOKEN = "ghp_your_token"
|
|
|
|
# Permanent
|
|
[Environment]::SetEnvironmentVariable("GITHUB_TOKEN", "ghp_your_token", "User")
|
|
```
|
|
|
|
---
|
|
|
|
### GH_TOKEN
|
|
|
|
Alternative GitHub token variable. Used by the [GitHub CLI (`gh`)](https://cli.github.com/) and recognized by skillshare as a fallback.
|
|
|
|
**Token resolution order:** `GITHUB_TOKEN` → `GH_TOKEN` → `gh auth token`
|
|
|
|
If you already use `gh` and have authenticated via `gh auth login`, skillshare picks up the token automatically — no extra env vars needed.
|
|
|
|
```bash
|
|
export GH_TOKEN=ghp_your_token_here
|
|
skillshare search "react patterns"
|
|
```
|
|
|
|
---
|
|
|
|
## Git Authentication {#git-authentication}
|
|
|
|
These variables enable HTTPS authentication for private repositories. When set, skillshare automatically injects the token during `install` and `update` — no URL modification needed.
|
|
|
|
See [Private Repositories](/docs/reference/commands/install#private-repositories) for details and CI/CD examples.
|
|
|
|
|
|
### GITLAB_TOKEN
|
|
|
|
GitLab personal access or CI job token. Used for HTTPS clone of GitLab-hosted private repos.
|
|
|
|
**Creating a token:**
|
|
1. Go to https://gitlab.com/-/user_settings/personal_access_tokens
|
|
2. Add new token
|
|
3. Scopes: `read_repository` (pull only) or `read_repository` + `write_repository` (push & pull)
|
|
4. Copy the token (prefix `glpat-`)
|
|
|
|
Official docs: [Token overview](https://docs.gitlab.com/security/tokens/)
|
|
|
|
:::warning Token types
|
|
Only **Personal Access Token** (`glpat-`) and **Project/Group Access Token** work for git operations. Feed Tokens (`glft-`) do **not** have git access.
|
|
:::
|
|
|
|
```bash
|
|
export GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx
|
|
skillshare install https://gitlab.com/org/skills.git --track
|
|
```
|
|
|
|
**Windows:**
|
|
```powershell
|
|
$env:GITLAB_TOKEN = "glpat-xxxxxxxxxxxxxxxxxxxx"
|
|
```
|
|
|
|
### BITBUCKET_TOKEN
|
|
|
|
Bitbucket repository access token, or app password. Used for HTTPS clone of Bitbucket-hosted private repos.
|
|
|
|
**Creating a token (repository access token):**
|
|
1. Go to Repository → Settings → Access tokens
|
|
2. Create token with **Read** permission (pull only) or **Read + Write** (push & pull)
|
|
3. Copy the token — uses `x-token-auth` automatically (no username needed)
|
|
|
|
**Creating a token (app password):**
|
|
1. Go to https://bitbucket.org/account/settings/app-passwords/
|
|
2. Create app password with **Repositories: Read** (pull only) or **Repositories: Read + Write** (push & pull)
|
|
3. Also set `BITBUCKET_USERNAME` (or include it in the URL as `https://<username>@bitbucket.org/...`)
|
|
|
|
Official docs: [Access tokens](https://support.atlassian.com/bitbucket-cloud/docs/access-tokens/)
|
|
|
|
```bash
|
|
export BITBUCKET_USERNAME=your_bitbucket_username
|
|
export BITBUCKET_TOKEN=your_app_password
|
|
skillshare install https://bitbucket.org/team/skills.git --track
|
|
```
|
|
|
|
**Windows:**
|
|
```powershell
|
|
$env:BITBUCKET_USERNAME = "your_bitbucket_username"
|
|
$env:BITBUCKET_TOKEN = "your_app_password"
|
|
```
|
|
|
|
### BITBUCKET_USERNAME
|
|
|
|
Bitbucket username used with `BITBUCKET_TOKEN` when that token is an app password.
|
|
|
|
```bash
|
|
export BITBUCKET_USERNAME=your_bitbucket_username
|
|
export BITBUCKET_TOKEN=your_app_password
|
|
skillshare install https://bitbucket.org/team/skills.git --track
|
|
```
|
|
|
|
### AZURE_DEVOPS_TOKEN
|
|
|
|
Azure DevOps Personal Access Token (PAT). Used for HTTPS clone of Azure DevOps-hosted private repos.
|
|
|
|
**Creating a token:**
|
|
1. Go to `https://dev.azure.com/{org}/_usersSettings/tokens`
|
|
2. Select **+ New Token**
|
|
3. Scopes: **Code → Read** (pull only) or **Code → Read & Write** (push & pull)
|
|
4. Copy the token (84-character string with `AZDO` signature)
|
|
|
|
Official docs: [Use Personal Access Tokens](https://learn.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops)
|
|
|
|
```bash
|
|
export AZURE_DEVOPS_TOKEN=your_pat_here
|
|
skillshare install https://dev.azure.com/org/project/_git/repo --track
|
|
```
|
|
|
|
**Windows:**
|
|
```powershell
|
|
$env:AZURE_DEVOPS_TOKEN = "your_pat_here"
|
|
```
|
|
|
|
### GITEA_TOKEN
|
|
|
|
Gitea access token. Used for HTTPS clone of private repos on `gitea.com` and self-hosted Gitea, and for the Gitea Contents API when a subdirectory is installed without a full clone.
|
|
|
|
**Creating a token:**
|
|
1. In Gitea, go to **Settings → Applications**
|
|
2. Generate a new token
|
|
3. Permissions: `repository: Read` (pull only) or `repository: Read and Write` (push & pull)
|
|
|
|
```bash
|
|
export GITEA_TOKEN=your_token
|
|
skillshare install https://gitea.com/org/skills.git --track
|
|
```
|
|
|
|
**Windows:**
|
|
```powershell
|
|
$env:GITEA_TOKEN = "your_token"
|
|
```
|
|
|
|
The token is sent only to the host you install from. A self-hosted instance on a domain without `gitea` in its name needs [`gitea_hosts`](/docs/reference/targets/configuration#gitea_hosts), otherwise `SKILLSHARE_GIT_TOKEN` is used for it.
|
|
|
|
### CNB_TOKEN
|
|
|
|
[CNB](https://cnb.cool) access token with read permission on the repository. Used for HTTPS clone of private repos on `cnb.cool` and self-hosted CNB.
|
|
|
|
```bash
|
|
export CNB_TOKEN=your_token
|
|
skillshare install https://cnb.cool/org/skills --track
|
|
```
|
|
|
|
**Windows:**
|
|
```powershell
|
|
$env:CNB_TOKEN = "your_token"
|
|
```
|
|
|
|
A private deployment on another domain needs [`cnb_hosts`](/docs/reference/targets/configuration#cnb_hosts).
|
|
|
|
### SKILLSHARE_GIT_TOKEN
|
|
|
|
Generic fallback token for any HTTPS git host. Used when no platform-specific token is set.
|
|
|
|
```bash
|
|
export SKILLSHARE_GIT_TOKEN=your_token
|
|
skillshare install https://git.example.com/org/skills.git --track
|
|
```
|
|
|
|
**Windows:**
|
|
```powershell
|
|
$env:SKILLSHARE_GIT_TOKEN = "your_token"
|
|
```
|
|
|
|
**Token priority:** Platform-specific (`GITHUB_TOKEN`, `GITLAB_TOKEN`, `BITBUCKET_TOKEN`, `AZURE_DEVOPS_TOKEN`, `GITEA_TOKEN`, `CNB_TOKEN`) > `SKILLSHARE_GIT_TOKEN`.
|
|
|
|
---
|
|
|
|
## Git SSL / TLS {#git-ssl--tls}
|
|
|
|
These standard Git environment variables are passed through to all git operations. They are useful for self-hosted Git servers (GitLab, Gitea, etc.) with self-signed certificates or internal CAs.
|
|
|
|
### GIT_SSL_CAINFO
|
|
|
|
Path to a custom CA certificate bundle. Use this when your self-hosted Git server uses a certificate signed by an internal CA.
|
|
|
|
```bash
|
|
export GIT_SSL_CAINFO=/path/to/ca-bundle.crt
|
|
skillshare install https://gitlab.internal.company.com/team/skills.git --track
|
|
```
|
|
|
|
### GIT_SSL_NO_VERIFY
|
|
|
|
Disable SSL certificate verification entirely. Use as a last resort when CA certificate setup is not feasible.
|
|
|
|
:::warning Security risk
|
|
Disabling SSL verification makes connections vulnerable to man-in-the-middle attacks. Prefer `GIT_SSL_CAINFO` with a proper CA bundle, or use SSH instead.
|
|
:::
|
|
|
|
```bash
|
|
GIT_SSL_NO_VERIFY=true skillshare install https://gitlab.internal.company.com/team/skills.git --track
|
|
```
|
|
|
|
**Alternative: use SSH to avoid SSL entirely:**
|
|
```bash
|
|
skillshare install git@gitlab.internal.company.com:team/skills.git --track
|
|
```
|
|
|
|
---
|
|
|
|
## Testing
|
|
|
|
### SKILLSHARE_TEST_BINARY
|
|
|
|
Override the CLI binary path for integration tests.
|
|
|
|
```bash
|
|
SKILLSHARE_TEST_BINARY=/path/to/skillshare go test ./tests/integration
|
|
```
|
|
|
|
**Default:** `bin/skillshare` in project root
|
|
|
|
---
|
|
|
|
## Usage Examples
|
|
|
|
### Temporary override
|
|
|
|
```bash
|
|
# Single command
|
|
SKILLSHARE_CONFIG=/tmp/test-config.yaml skillshare status
|
|
|
|
# Multiple commands
|
|
export SKILLSHARE_CONFIG=/tmp/test-config.yaml
|
|
skillshare status
|
|
skillshare list
|
|
unset SKILLSHARE_CONFIG
|
|
```
|
|
|
|
### Permanent setup (macOS/Linux)
|
|
|
|
Add to `~/.bashrc` or `~/.zshrc`:
|
|
```bash
|
|
export GITHUB_TOKEN="ghp_your_token_here"
|
|
```
|
|
|
|
### Permanent setup (Windows)
|
|
|
|
```powershell
|
|
[Environment]::SetEnvironmentVariable("GITHUB_TOKEN", "ghp_your_token", "User")
|
|
```
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
| Variable | Purpose | Default |
|
|
|----------|---------|---------|
|
|
| `SKILLSHARE_CONFIG` | Config file path | `~/.config/skillshare/config.yaml` |
|
|
| `SKILLSHARE_UI_BASE_PATH` | Web UI sub-path for reverse proxy | None |
|
|
| `SKILLSHARE_GITLAB_HOSTS` | Custom GitLab hostnames (comma-separated) | None |
|
|
| `SKILLSHARE_AZURE_HOSTS` | Custom Azure DevOps Server hostnames (comma-separated) | None |
|
|
| `SKILLSHARE_GITEA_HOSTS` | Custom Gitea hostnames (comma-separated) | None |
|
|
| `SKILLSHARE_CNB_HOSTS` | Custom CNB hostnames (comma-separated) | None |
|
|
| `XDG_CONFIG_HOME` | Base config directory | `~/.config` (Linux/macOS), `%AppData%` (Windows) |
|
|
| `XDG_DATA_HOME` | Data directory (backups, trash) | `~/.local/share` |
|
|
| `XDG_STATE_HOME` | State directory (logs) | `~/.local/state` |
|
|
| `XDG_CACHE_HOME` | Cache directory (version check, UI) | `~/.cache` |
|
|
| `GITHUB_TOKEN` | GitHub API + git clone auth | None |
|
|
| `GH_TOKEN` | GitHub API (fallback for `GITHUB_TOKEN`) | None |
|
|
| `GITLAB_TOKEN` | GitLab git clone auth | None |
|
|
| `BITBUCKET_TOKEN` | Bitbucket git clone auth | None |
|
|
| `BITBUCKET_USERNAME` | Bitbucket username for app password auth | None |
|
|
| `AZURE_DEVOPS_TOKEN` | Azure DevOps git clone auth | None |
|
|
| `GITEA_TOKEN` | Gitea git clone + Contents API auth | None |
|
|
| `CNB_TOKEN` | CNB git clone + contents API auth | None |
|
|
| `SKILLSHARE_GIT_TOKEN` | Generic git clone auth (fallback) | None |
|
|
| `GIT_SSL_CAINFO` | Custom CA certificate bundle path | System default |
|
|
| `GIT_SSL_NO_VERIFY` | Disable SSL certificate verification | `false` |
|
|
| `SKILLSHARE_TEST_BINARY` | Test binary path | `bin/skillshare` |
|
|
|
|
---
|
|
|
|
## Related
|
|
|
|
- [Configuration](/docs/reference/targets/configuration) — Config file reference
|
|
- [Windows Issues](/docs/troubleshooting/windows) — Windows environment setup
|