Linux and Container Portability

Gitea-Tools is fully supported on Linux and inside headless containers (such as CI/CD pipelines or Docker environments), but requires slightly different authentication configuration than standard macOS operator usage.

Setup Assumptions

Python Environment: Requires Python 3.9+ and venv.
Keychain Access: Linux environments typically lack macOS Keychain or a GUI prompt. All type: "keychain" profile authentication methods will fail in a headless Linux environment.
Provenance: The macOS com.apple.provenance extended attribute block does not exist on Linux.

Headless and Container MCP Server Usage

When running the MCP server in a headless container or remote Linux environment, you cannot rely on interactive prompts or local Keychain. The server will run successfully out of the box as long as the profile is configured to use environment variables for authentication.

Environment-Variable Credential Loading

Linux users must use environment variables for credential loading. Define your secrets in a gitignored .env file (e.g., .env) or inject them via standard container orchestration mechanisms.

Example .env:

GITEA_TOKEN_MDCPS="your_actual_token_here"

CRITICAL: Never commit .env files containing actual tokens. The .env file is in .gitignore, but ensure it stays there.

In your canonical profile JSON (e.g., profiles.json), configure authentication to use the env type rather than keychain:

{
  "profiles": {
    "linux-ci": {
      "base_url": "https://gitea.example.com",
      "username": "ci_bot",
      "auth": { "type": "env", "name": "GITEA_TOKEN_MDCPS" },
      "execution_profile": "ci_worker"
    }
  }
}

This ensures the MCP server safely loads the secret directly from the process environment when linux-ci is activated.

Avoiding macOS Keychain Assumptions

If you are a Linux user or configuring a container, do not use { "auth": { "type": "keychain", "id": "..." } }. If you run a profile configured for keychain, the underlying security find-generic-password calls will fail.

This setup is the primary difference from local operator profiles (e.g., prgs-reviewer on a developer's Macbook), which typically rely on keychain to avoid writing tokens to .env files locally. Both methods are safe when used properly in their intended environments.

macOS-Specific Features

scripts/clear-provenance: This script uses xattr to remove macOS-specific execution restrictions. It is not needed and will not work on Linux.
scripts/gitea-config-menu: The interactive menu depends on macOS Keychain integration for token storage. While the JSON editing parts might work, token storage will fail on Linux.

Running Tests on Linux

Running the test suite on Linux works identically to macOS. The tests fully mock all network requests and keychain interactions, ensuring the test suite can execute securely in a headless CI environment without needing actual credentials.

python3 -m pytest tests/ -v

Known Limitations

Multi-token switching in a single runtime is not currently supported (one token per process).
The interactive gitea-config-menu script is primarily tailored for macOS operators.

3.2 KiB Raw Blame History