# KiCI Providers This bundle covers: Connecting sources: GitHub App, universal-git (Forgejo/Gitea/GitLab), local file://. ## GitHub App provider Source: https://docs.kici.dev/user/providers/github/ The **GitHub App** is KiCI's flagship source. A single App: 1. receives `push`, `pull_request`, and related events from every repo it's installed on, 2. clones repos with a short-lived installation token (no deploy key to manage), 3. posts workflow / job / step Check runs back to the commit — visible on the commit view for a plain `push` and on the **Checks** tab of any pull request that contains it (see [GitHub checks architecture](https://docs.kici.dev/architecture/webhooks/github-checks/)). You don't need an App for every scenario — if you only care about `push` events, don't want to install an App, or are using a non-GitHub forge, use the [universal-git provider](https://docs.kici.dev/user/providers/universal-git/) instead. ## GitHub App vs. `github-repo` preset Both paths reach the same trigger pipeline; they differ in what the forge side looks like: | Capability | GitHub App (this guide) | `github-repo` preset on universal-git | | ---------------------------------------- | -------------------------------------- | ------------------------------------------- | | Webhook source | App-level webhook (one per App) | Per-repo webhook (one per repo) | | Clone auth | Installation token (auto, short-lived) | PAT or SSH deploy key (you manage rotation) | | Check runs on pull requests | Yes — full KiCI Checks UI | No (status post only via custom step) | | Cross-repo install in seconds | Yes (install the App on more repos) | No (new webhook per repo) | | Works without a GitHub org admin | No (App creation is org-scoped) | Yes (per-repo webhook is repo-admin) | | Works on Forgejo / Gitea / Gogs / GitLab | No | Yes (other presets) | Use the App when you can; the `github-repo` preset is a fallback for repos where you can't install an App. ## One-click setup (recommended) `kici-admin source add github --manifest` creates **and** configures the GitHub App for you via GitHub's App Manifest flow. KiCI builds a manifest with the exact permissions, events, webhook URL, and webhook secret baked in, so you never pick permissions, paste a URL, generate a secret, or download a `.pem` by hand — the App is correct by construction. ```bash kici-admin --url http://:4000 --token $KICI_BOOTSTRAP_ADMIN_TOKEN \ source add github --manifest --name my-org --github-org my-org ``` `--github-org ` creates the App under a GitHub **organization** (the `` is the org's `github.com/` URL slug, not its display name) — the recommended default, since org-owned Apps can be installed across the org. Drop the flag only when you deliberately want a personal-account App, which can be installed solely on repos you own. You need permission to create Apps in that org (be an org owner, or have the org allow member App creation). What happens: 1. The CLI resolves your org's webhook URL and opens GitHub with a pre-filled App manifest. You click **"Create GitHub App"** once — the only manual step. 2. GitHub redirects back to a localhost callback; the CLI exchanges the returned setup code for the App's id, private key, and webhook secret. **The private key is exchanged and stored only on your orchestrator host — it never transits the KiCI Platform.** 3. The CLI stores the credentials encrypted under `KICI_SECRET_KEY` and registers the routing key `github:`, reusing the same storage path as the manual flow. 4. It opens the App's install page so you can pick repos, then verifies end-to-end: it waits for the installation, mints an installation token, and confirms repo access before declaring success. ``` $ kici-admin source add github --manifest --name my-org --github-org my-org → Opening GitHub to create your App… → ✓ App created (id 12345), credentials captured → ✓ Stored on orchestrator (encrypted), registered as github:12345 → Install the App on your repos: https://github.com/apps/my-org/installations/new → ✓ Installation detected (account my-org) → ✓ Credentials verified (3 repositories reachable) GitHub App "my-org" is live. Webhook: https:///webhook//github ``` **Flags:** | Flag | Effect | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--name ` | The App name you _request_ on GitHub (required). GitHub assigns the final name + slug; the stored, displayed name always comes from GitHub (see [Display name and slug](https://docs.kici.dev/user/providers/github/#display-name-and-slug)). | | `--github-org ` | Create the App under a GitHub organization instead of your personal account. | | `--webhook-url ` | **Advanced / self-hosted.** Bake this `https://` URL into the App's webhook verbatim and skip the platform-mode webhook-URL resolution (so it works even where the auto-resolved KiCI Platform URL is unavailable). See [Self-hosted webhook URL](https://docs.kici.dev/user/providers/github/#self-hosted-webhook-url-override). | | `--no-browser` | Headless mode: the CLI prints a `kici.dev` URL to open, then reads the setup code you paste back. The page is pure client-side — it only displays the short-lived code, which is useless once the CLI exchanges it. | The manifest flow always creates a **new** App on GitHub. If a source for that App id already exists on the orchestrator, the command refuses — use `source update` to rotate an existing App's credentials. If any step after App creation fails (e.g. storage), the CLI prints the captured App id and writes the private key to a `0600` file, then tells you how to finish with the manual `source add github` command — so a created App is never orphaned. Independent-mode orchestrators have no GitHub-App ingress (it is Platform-relayed), so the manifest flow is unavailable there; use a generic webhook source instead. ## Manual setup (fallback) When you'd rather create the App by hand — or your environment can't run the manifest flow — follow these steps. ### Create the GitHub App on GitHub's side 1. **Decide the App scope.** User-owned Apps can only be installed on repos you own; organization-owned Apps can be installed anywhere in the org. For production, create the App under the org. 2. **Create the App.** Go to _Settings -> Developer settings -> GitHub Apps -> New GitHub App_ (org-level is _Settings -> Developer settings -> GitHub Apps_ on the org page). 3. **Set the webhook URL.** KiCI exposes one webhook endpoint per org: ``` https:///webhook//github ``` GitHub App webhooks are always delivered to this Platform endpoint and relayed to your orchestrator over its outbound connection — platform and hybrid orchestrators both receive GitHub events this way. Independent-mode orchestrators have no Platform connection and therefore no GitHub-App ingress; use a generic webhook source instead. The `` segment is the KiCI organization ID the source belongs to; the `` is discovered from `X-GitHub-Hook-Installation-Target-ID` at request time and is _not_ part of the URL. 4. **Set the webhook secret.** Generate a random hex string (e.g. `openssl rand -hex 32`) and save it for step 4 of the orchestrator registration below. GitHub uses this secret to HMAC-sign every webhook; KiCI rejects mismatches. 5. **Pick permissions.** Minimum required: | Scope | Access | Why | | --------------------------- | ------------ | ------------------------------------ | | Repository -> Contents | Read | Clone the repo to read the lock file | | Repository -> Metadata | Read (auto) | Default for every App | | Repository -> Pull requests | Read | Match `pull_request` triggers | | Repository -> Checks | Read & write | Post KiCI's enriched Check runs | Those four cover the whole flow: clone, trigger matching, Check runs. [CI trust](https://docs.kici.dev/architecture/security/ci-security/) needs no permission of its own — it reads the fork relationship straight out of the webhook payload and calls no GitHub API. 6. **Subscribe to events.** At minimum: `push`, `pull_request`, `check_run`, `check_suite`. Add others (`issues`, `release`, ...) if your workflows use those triggers. 7. **Generate a private key.** Scroll to the bottom of the App settings and click _Generate a private key_. A `.pem` file downloads — store it safely; you cannot redownload it. 8. **Copy the App ID.** It's the numeric ID near the top of the App settings page. You'll need it for `--app-id` below. 9. **Install the App on target repos.** Under the App's _Install App_ tab, install it on the repos (or whole org) that should trigger KiCI runs. Re-install to add repos later — this is live and revocable without redeploying the App. ### Register the App with the orchestrator With the App ID, private key `.pem`, and webhook secret in hand: ```bash kici-admin --url http://:4000 --token $KICI_BOOTSTRAP_ADMIN_TOKEN \ source add github \ --name my-org \ --app-id 12345 \ --private-key @/path/to/private-key.pem \ --webhook-secret ``` The command prints the routing key (always `github:`) and the public webhook URL to paste into the GitHub App's "Webhook URL" field: ``` Source added: github: (my-org) Webhook URL: https:///webhook//github ↳ Paste this into your GitHub App's "Webhook URL" field. ``` When the orchestrator runs in independent mode (no Platform connection) the URL line reads `(unavailable — this orchestrator runs in independent mode)`, because GitHub-App ingress is Platform-relayed. The private key and webhook secret are stored encrypted in the orchestrator database under `KICI_SECRET_KEY`; no restart needed — the orchestrator accepts webhooks from this App immediately. **Secret input modes** (for `--private-key` and `--webhook-secret`): | Mode | Syntax | Example | | -------------------- | ----------------------- | --------------------------------------------------------- | | Direct value | `--private-key ` | `--webhook-secret mysecret` | | File (`@` prefix) | `--private-key @` | `--private-key @/path/to/key.pem` | | Environment variable | `--from-env ` | `--from-env GITHUB_PRIVATE_KEY` | | Standard input | `--stdin` | `cat key.pem \| kici-admin source add github --stdin ...` | Use `@file` for private keys — it reads the full PEM including newlines without quoting pitfalls. To list and inspect: ```bash kici-admin source list # All configured sources kici-admin source get-webhook-secret github:12345 # Fetch the secret (for debugging) ``` For the full CLI reference see the `source` section of the [kici-admin CLI reference](https://docs.kici.dev/operator/orchestrator/kici-admin-cli/). ## Routing keys Every GitHub App source has routing key `github:`. It's the identifier every other KiCI surface uses to talk about the source: - `kici-admin source update github: ...` for rotation / updates - `kici-admin source remove github:` to decommission - `kici-admin org-settings global-workflows ... --customer-id [--source github:]` for policy (org-scoped row, optional per-entry source qualifier) - The orchestrator's source records and event-log entries key on `github:`; org-level settings key on `customer_id` (one row per org) If you install the same App across multiple KiCI orgs, each org has its own source record and the orchestrator looks up the right one by combining the URL's `` with the App ID from the `X-GitHub-Hook-Installation-Target-ID` header. ## Display name and slug For a GitHub App source, **GitHub is the source of truth for the displayed name**. `--name` is only the name you _request_ when the App is created; GitHub assigns the final display name and a URL-safe **slug** (`my-org` → `my-org-1` if the name was taken). KiCI captures both at creation and shows them in the dashboard **Sources** tab — the display name prominently, with the slug as dimmed secondary text. If you later rename the App in GitHub's UI, KiCI keeps the displayed name in sync two ways: - **Automatically**, on a daily schedule. The orchestrator re-reads each GitHub source's name + slug from GitHub and updates the dashboard if they changed. The interval is configurable via `KICI_GITHUB_APP_NAME_REFRESH_INTERVAL_MS` (default 24h). - **On demand**, with `source refresh`: ```bash kici-admin source refresh github: # one source kici-admin source refresh --all # every GitHub source ``` It prints `old → new` for any name or slug that changed, and is a no-op when GitHub already matches what KiCI has stored. Non-GitHub routing keys are rejected — name/slug sync applies only to GitHub App sources. ## Self-hosted webhook URL override By default the manifest flow bakes the KiCI Platform webhook endpoint (`https:///webhook//github`) into the App. If you run your own ingress and want GitHub to deliver events to it instead, pass `--webhook-url` when creating the App: ```bash kici-admin source add github --manifest --name my-org \ --webhook-url https://hooks.my-infra.example/github ``` The supplied URL must be an absolute `https://` URL; it is written into the App's webhook configuration **verbatim**. This is the operator asserting "I own webhook delivery": KiCI adds **no** ingress at this URL and does **not** receive events there — your own infrastructure is responsible for accepting GitHub's deliveries and routing them onward. Supplying the flag also decouples App creation from platform-mode URL resolution, so it works even in a configuration where the auto-resolved KiCI Platform URL is unavailable. ## Global workflows A GitHub App source opts in to org-wide global workflows using the org-scoped settings row. Pass `--customer-id ` (alias `--org`) to select the row; on `*-add` mutators, pass `--source github:` when you want a list entry pinned to this specific App rather than applying to any source in the org: ```bash # Enable global workflows cluster-wide (the master switch is fleet-wide, held by the operator) kici-admin cluster-settings set --global-workflows-enabled true # Allow the listed repo as an author for any source in the org kici-admin org-settings global-workflows allow-add 'my-org/ci-workflows/*' \ --customer-id # Allow the listed repo as an author only when authored on this App kici-admin org-settings global-workflows allow-add 'my-org/ci-workflows/*' \ --customer-id --source github:12345 # Deny events from untrusted repos delivered on this App kici-admin org-settings global-workflows deny-add 'my-org/contrib/*' \ --customer-id --source github:12345 ``` Global workflows authored in a GitHub App repo can dispatch against events from universal-git sources in the same org, and vice versa, with each clone using its own source's credentials. See [Global workflows](https://docs.kici.dev/architecture/global-workflows/) for the policy model and cross-source dispatch contract. ## Check runs Once registered, the App's Check-runs permission lets KiCI post enriched Check runs: - `kici/{workflowName}` — overall pass/fail for the workflow - `kici/{workflowName}/job/{jobName}` — per-job detail with step progress - `kici/{workflowName}/setup` — (optional) build / dependency-install check Step progress, log tails, and source-location annotations are all driven by the orchestrator's reporting module; no workflow configuration is required beyond installing the App with the `checks: write` permission. Check runs are keyed to the head commit SHA, so they surface whether or not a pull request exists: after a `push` you see the pass/fail directly on the commit (a red ✗ / green ✓ next to the SHA in GitHub's commit list and on the commit page), and the same checks roll up into the **Checks** tab of any pull request that later includes the commit. A failing run is therefore visible in GitHub itself without opening the KiCI dashboard. For architecture details see [GitHub checks architecture](https://docs.kici.dev/architecture/webhooks/github-checks/). ## Rotation ### Rotate the webhook secret 1. Generate a new random hex: `openssl rand -hex 32`. 2. Update GitHub: _App settings -> Webhook -> Webhook secret_. GitHub will sign new deliveries with this immediately. 3. Update the orchestrator: ```bash kici-admin source update github:12345 --webhook-secret ``` The orchestrator verifies signatures against every cached secret during a dual-secret window, so brief mismatches during rotation don't drop deliveries. The HMAC verifier iterates over all stored secrets for the routing key. ### Rotate the private key 1. In GitHub's App settings click _Generate a private key_ — this does **not** revoke existing keys. Download the new `.pem`. 2. Push it to the orchestrator: ```bash kici-admin source update github:12345 --private-key @/path/to/new-key.pem ``` 3. After confirming clones work on the new key, delete the old key from GitHub's App settings. ### Decommission ```bash kici-admin source remove github:12345 ``` After removal the routing-key row and its secrets are purged; GitHub deliveries to the endpoint will be rejected as "Unknown routing key". Uninstall the App from GitHub's side separately. ## Troubleshooting **Webhook hits the endpoint but KiCI replies 404 `Unknown organization`.** The `` segment of the webhook URL doesn't match the org that owns the source. Check the URL registered in _App settings -> Webhook_ against `kici-admin source list`. **Webhook hits the endpoint but KiCI replies 401 `Invalid signature`.** The webhook secret in the App settings doesn't match the one stored with the source. Rotate it via the steps above. **Webhook hits the endpoint but KiCI replies 400 `Missing GitHub App target headers`.** The request isn't actually from a GitHub App (missing `X-GitHub-Hook-Installation-Target-Type: integration` + `X-GitHub-Hook-Installation-Target-ID`). If you're test-firing a webhook, use the App's _Recent Deliveries_ tab on GitHub to re-send a real one. **Webhook arrives but no run fires.** The orchestrator accepted the webhook but no workflow registration matched. Causes (in order of likelihood): the repo isn't registered with the orchestrator yet (push a commit that touches `.kici/kici.lock.json` first), the event type isn't one the workflow's triggers list, or `global_workflow_denied_repos` filtered out the source repo. Check `kici-admin event-log list --routing-key github:12345` and the orchestrator logs for `no registrations for event`. **Clone fails with 401 / 403.** The installation token minted from the App private key was refused. Usually means the App was uninstalled from the repo, or the private key on the orchestrator no longer matches the one GitHub knows about (rotate it). **Check runs don't appear on pull requests.** The App is missing the `checks: write` permission or wasn't installed on the target repo. Re-request permissions in _App settings -> Permissions & events_ (GitHub will prompt installers to accept the new scope on next visit) and confirm the App is installed on that repo. ## See also - [Universal-git provider](https://docs.kici.dev/user/providers/universal-git/) — for Forgejo / Gitea / Gogs / GitLab, and for plain-GitHub repos without an App - [GitHub checks architecture](https://docs.kici.dev/architecture/webhooks/github-checks/) - [Global workflows](https://docs.kici.dev/architecture/global-workflows/) - [kici-admin CLI reference](https://docs.kici.dev/operator/orchestrator/kici-admin-cli/) - [Event routing](https://docs.kici.dev/operator/event-routing/) — operator-level routing-key mechanics --- ## Local filesystem (file://) source Source: https://docs.kici.dev/user/providers/local-file/ The **local** provider lets the orchestrator run workflows from a git repository that already lives on the agent's filesystem — cloned via a `file://` URL rather than fetched from a remote forge. There is no webhook from GitHub or GitLab; the operator drives runs explicitly with the `kici-admin` CLI or a generated `post-receive` hook. > **This is an operator-curated source, not daily developer CI.** Use it for > globally-registered or policy workflows the operator controls — a vendored > repo baked into an agent image, a repo synced onto a host out-of-band, a > golden internal pipeline. For ordinary per-developer CI driven by pull > requests and pushes, use the [GitHub App provider](https://docs.kici.dev/user/providers/github/) or the > [universal-git provider](https://docs.kici.dev/user/providers/universal-git/) against a real forge. ## Trust caveat (read first) A local source uses signature verification `none` — there is no remote forge to sign the webhook payload, so the orchestrator cannot authenticate the trigger. **Only register repos you trust.** Anyone who can reach the orchestrator's webhook route for this source, or push to the repo on disk, can drive a run. Treat the repo path as a trusted operator input, the same way you treat the orchestrator's own configuration. ## Register a source ```bash kici-admin source add local \ --org \ --path /abs/path/to/repo \ --name my-local-repo ``` - `--path` must be an **absolute** directory on the agent filesystem. It is the base path the orchestrator's lock-file fetcher reads (`/.kici/kici.lock.json`) and the base for the `file://` clone the agent performs. - `--clone-url-base ` is optional. By default the agent clones via `file://`. Supply a `git://` or `http://` base when the agent does **not** share the orchestrator's filesystem and must fetch the repo over a git server instead (see "Per-scaler reachability" below). Update the path or name later: ```bash kici-admin source update-local --path /new/abs/path kici-admin source update-local --name new-name ``` Remove it: ```bash kici-admin source remove --local ``` List and inspect (local sources render their `repoBasePath`): ```bash kici-admin source list --org kici-admin source get ``` ## Trigger runs A local repo has no forge to send webhooks, so you trigger runs yourself. **One-shot, by hand:** ```bash kici-admin source trigger-local ``` The command reads the repo's current HEAD ref and commit SHA, builds a GitHub-shaped `push` payload, and POSTs it to the orchestrator's generic webhook route. Override the ref/sha/event explicitly when needed: ```bash kici-admin source trigger-local --event push --ref refs/heads/main --sha ``` **On every push, via a hook:** ```bash kici-admin source install-hook ``` This writes a `post-receive` hook into the repo so that every push to it triggers a run automatically — the local equivalent of a forge webhook. ## Per-scaler reachability (operator's responsibility) The orchestrator accepts a local source on **any** scaler backend and does **not** verify that the repo is actually reachable inside the agent. Making the path reachable is the operator's job. On a container or Firecracker scaler the orchestrator logs a reachability warning when it registers the source, but it does not reject it. | Scaler | How the repo must be reachable in the agent | | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | bare-metal | The agent runs on the host, so the `--path` host directory is used directly. | | container | Bake the repo into the agent image, or bind-mount it at the **same absolute path** the source was registered with. Alternatively register `--clone-url-base` pointing at a git server the container can reach. | | Firecracker | The repo must be present on the microVM rootfs at the registered path, or reachable via a `--clone-url-base` git server. | If the path is not reachable inside the agent, the clone fails at run time — the run is created and then fails, rather than being silently dropped. ## See also - [Universal-git provider](https://docs.kici.dev/user/providers/universal-git/) — for a remote forge (or any `http://` git server) when there is no shared filesystem. - [GitHub App provider](https://docs.kici.dev/user/providers/github/) — the flagship source for pull-request CI with Checks. --- ## Universal-git provider Source: https://docs.kici.dev/user/providers/universal-git/ The **universal-git** provider lets KiCI treat any git forge that speaks a GitHub-shaped webhook payload as a first-class source. That covers Forgejo, Gitea, Gogs, GitLab, plain GitHub (without the App), and any custom webhook-driven forge you can describe in JSONPath. > **Want Check runs on pull requests?** Use the [GitHub App > provider](https://docs.kici.dev/user/providers/github/) instead — it clones via short-lived installation > tokens and drives KiCI's enriched Checks UI out of the box. The > universal-git `github-repo` preset is the right fallback when you > can't install an App. The orchestrator: 1. receives the forge's webhook, 2. clones the repo via HTTPS (PAT) or SSH (deploy key) to read the lock file at `.kici/kici.lock.json`, 3. dispatches workflows that match the push / pull_request event. No mirror, no GitHub App, no `checkout: false` escape hatch. The same trigger matching, global-workflow policy, and agent execution pipeline that back the GitHub App source also serve universal-git sources. > **No shared filesystem between orchestrator and agent?** Universal-git is > the right choice for the **remote-agent** case — point it at an `http://` > git server and the agent clones over the network. When the repo instead > lives on the agent's own filesystem (a vendored / operator-curated repo), > use a [local `file://` source](https://docs.kici.dev/user/providers/local-file/) and drive it with the > `kici-admin` CLI. ## Which preset do I need? KiCI ships canonical presets so you don't have to spell out JSONPath for every forge: | Preset | Forge | Webhook header | | ------------- | --------------------------------------- | ---------------- | | `forgejo` | Forgejo | `X-Gitea-Event` | | `gitea` | Gitea | `X-Gitea-Event` | | `gogs` | Gogs | `X-Gogs-Event` | | `gitlab-repo` | GitLab (per-project webhooks) | `X-Gitlab-Event` | | `github-repo` | Plain GitHub (per-repo webhook, no App) | `X-GitHub-Event` | | `custom` | Anything else | You supply it | Pick `custom` only when the forge's payload structure or event header deviates from GitHub's — you'll then supply `payloadPaths` and `eventMapping` explicitly. ## Create a source (PAT) ```bash kici-admin source add generic \ --org \ --name forgejo-main \ --verification hmac_sha256 \ --secret \ --preset forgejo \ --git-url-template 'https://forgejo.example.com/{owner}/{name}.git' \ --credential-ref pat \ --credential-type pat \ --credential-user bot-user ``` Then seed the PAT under the source's own secret scope: ```bash # The scope __source__/ is the orchestrator's convention for # source-level credentials. Use the sourceId printed by `source add`. kici-admin secret set "__source__/" pat --value "" ``` Finally, configure the forge to deliver webhooks to: ``` https:///webhook//generic/ ``` with the same secret you passed to `--secret`. `` is your Platform organization id — the same value you passed to `--org`, which the source's routing key embeds — and `` is the id `source add` printed. The orchestrator's own ingest URL has the same shape but takes the source **name** in place of the id. ## SSH deploy key For SSH instead of HTTPS: 1. **Generate an Ed25519 deploy key.** Ed25519 is the recommended default. ```bash ssh-keygen -t ed25519 -N '' -C 'kici-forgejo-deploy-key' -f ~/.ssh/forgejo-deploy-key ``` This produces `~/.ssh/forgejo-deploy-key` (private, OpenSSH PEM) and `~/.ssh/forgejo-deploy-key.pub` (public). 2. **Register the public key as a deploy key on the forge.** On Forgejo / Gitea this is _Repository -> Settings -> Deploy Keys -> Add Key_ (paste the `.pub` contents). On GitLab it's _Settings -> Repository -> Deploy keys_. On plain GitHub it's _Settings -> Deploy keys_. Read-only access is enough — KiCI only clones. 3. **Capture the forge's host keys** (needed only for `--ssh-host-key-policy pinned`): ```bash ssh-keyscan -t ed25519,rsa forgejo.example.com > forgejo.known_hosts ``` Inspect the file before trusting it (compare against what the forge publishes in its docs) — this is your one chance to pin the key out-of-band rather than trust-on-first-use. 4. **Create the source:** ```bash kici-admin source add generic \ --org \ --name forgejo-ssh \ --verification hmac_sha256 \ --secret \ --preset forgejo \ --git-url-template 'ssh://git@forgejo.example.com:22/{owner}/{name}.git' \ --credential-ref deploy-key \ --credential-type ssh \ --ssh-host-key-policy pinned \ --ssh-known-hosts-pem "@/path/to/forgejo.known_hosts" ``` The `@` prefix on `--ssh-known-hosts-pem` tells the CLI to read the file contents. 5. **Store the private key PEM under the source scope:** ```bash kici-admin secret set "__source__/" deploy-key \ --value "$(cat ~/.ssh/forgejo-deploy-key)" ``` The orchestrator materialises this PEM into a tempfile (mode `0600`) at every clone and drives `git` with a purpose-built `GIT_SSH_COMMAND` (`IdentitiesOnly=yes`, `BatchMode=yes`, plus the host-key flags below). The tempdir is cleaned up as soon as the clone finishes. **Host-key policy:** `accept-new` (default) auto-trusts the forge on first connection (TOFU) and logs a one-time warning. `pinned` sets `StrictHostKeyChecking=yes` with `UserKnownHostsFile=` and rejects any host key that doesn't match — use this for production supply-chain hardening. `pinned` requires `--ssh-known-hosts-pem` (or the equivalent `sshKnownHostsPem` field on update); the CLI rejects the request otherwise. **Updating an existing source:** use `kici-admin source update-generic ` with the same flags to switch an HTTPS/PAT source to SSH, rotate the host-key policy, or flip presets. Pass `--clear-git-config` to revert the source back to a payload-only generic webhook. ## Credential rotation To rotate a PAT or SSH key, overwrite the value under the same scope + key and the next clone picks it up: ```bash kici-admin secret set "__source__/" pat --value "" ``` The orchestrator re-reads the secret at each clone. No source update needed. ## Global workflows Universal-git sources participate in the org-wide global-workflow model exactly like GitHub App sources — a global workflow authored in one source can dispatch against pushes from a different source in the same org (including across forges), with each clone using its own bundle's credentials. Enable and tune the policy via the org-settings CLI. Settings are org-scoped (one row per `customer_id`); each list entry can optionally pin to a specific source via `--source `: ```bash # Enable global workflows cluster-wide (the master switch is fleet-wide, held by the operator) kici-admin cluster-settings set --global-workflows-enabled true # Allow authors from any source in the org kici-admin org-settings global-workflows allow-add \ 'forgejo.example.com/ci-workflows/*' \ --customer-id # Allow authors only when the workflow lives on a specific source kici-admin org-settings global-workflows allow-add \ 'forgejo.example.com/ci-workflows/*' \ --customer-id \ --source "generic::" # Forbid events from a specific source from firing any global workflow kici-admin org-settings global-workflows deny-add \ 'forgejo.example.com/untrusted/*' \ --customer-id \ --source "generic::" ``` See [Global workflows](https://docs.kici.dev/architecture/global-workflows/) for the policy model (`isWorkflowRepoAllowed` + `isSourceRepoAllowed` + `isElevatedAccessAllowed`) and the cross-provider dispatch contract. ## Routing-key collisions When a user has both a GitHub App source and a universal-git source targeting the same `owner/repo`, each creates its own registration and each fires its own run on a matching push. This is intentional: the two sources are independently authenticated and may resolve different lock files. If you want deduplication, either: - constrain one side via `global_workflow_denied_repos`, or - don't create both sources. ## Troubleshooting **The webhook hits the orchestrator but no run fires.** Check the orchestrator log for `Skipping global workflow dispatch` or `no registrations for event`. Most common cause: the webhook event header doesn't match the preset's `eventMapping`. For `custom` sources, make sure the `eventMapping` array includes every value the forge actually sends (they can vary by event type). **Clone fails with 401.** The source-scoped secret is missing or wrong. Verify with: ```bash kici-admin secret list "__source__/" ``` **Clone fails with 403 `default branch` fetch.** The PAT lacks read-access to the repo or the SSH deploy key isn't registered on it. **SSH clone fails with host-key rejection.** If you set `sshHostKeyPolicy: pinned`, verify the known-hosts PEM matches the forge's current key. If you're still using `accept-new`, the orch's `~/.ssh/known_hosts` has a stale entry — clear it or flip to `pinned` with the right PEM. ---