gsadmin/sencho
1
0
Fork 0
mirror of https://github.com/Studio-Saelix/sencho.git synced 2026-10-26 13:40:26 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
02a09688bcefe55fe86bb33ca0df9ee565c85bf1
sencho/docs/features/git-authentication.mdx
T
Anso 26f77cac96 docs: v1 docs refresh (batch 9) (#2181) 
* docs(gitops): complete the overview's source states, placement limits, and control locations

List every source state the app can show, with the order in which the most
serious one wins. Add the pin-driven and unreadable-evidence cases to what
the placement policy hands back to an operator, and name the controls where
each policy is set.

* docs(git-sources): document the polling controls, Manual behavior, and pending-update indicators

State the per-node polling interval and its range, that a Manual source is
never polled or retried but still stages a plan when a webhook delivers a
commit, and where the pending-update icon and button lead. Add common setups
and what Git sources do not do, and correct the create form's alt text.

* docs(git-authentication): cover the Git error cases and current Bitbucket credentials

Add the failures a Git source can report that were missing from
troubleshooting (embedded credentials, SSH without a deploy key, blocked
hosts, rate limits, certificate expiry and hostname mismatch, network
errors), state that the token is only given to the repository's host, and
replace the deprecated Bitbucket app password guidance.

* docs(git-webhooks): state the GitHub content type, remote-node failures, and limits

A form-encoded GitHub delivery fails verification and answers 404, so say to
set the content type to JSON. Add the 500 a delivery gets when the owning
node is unreachable, correct how the hub forwards to a remote node, and list
what provider hooks do not cover.

* docs(git-secrets): document linking an encrypted repository and where encrypted values work

A repository that is already encrypted cannot be linked, because the identity
belongs to a linked source. Encrypted values belong in env files and
file-backed secrets, not in image references or published ports, which
Sencho resolves before decrypting.

* docs(blueprints): correct permissions, remote deploys, and roadmap wording

Describe the permissions Blueprint actions need instead of an admin-only
rule, say that a remote node runs the deploy itself with its own policy and
scanner state, and list all three drift notifications. Remove the repeated
marker, policy gate, and snapshot explanations, the raw apply request
format, and statements about future features.

* docs(git-managed-blueprints): add who can take each step and the limits

List the permission each authority step and rollout control needs, say that
webhooks do not fetch a Blueprint's source so Pull source and polling bring in
new commits, and gather the constraints that were scattered through the page.

* docs(gitops-portfolio): name the row menu actions and state what the portfolio does not do

List the exact row menu items for Direct and Blueprint applications, and
add the limits: hub only, navigation from row menus, and how unreachable
nodes appear.

* docs(gitops-drift): describe the drift row as it appears and add a screenshot

The row shows the class, the deriving component, evidence age, reason, and
expected against observed; the resolving action lives on the application's
status. Name the retry-interval setting, drop rollout states Sencho never
reports, and replace a hedge about which classes are reported.

* docs(git-transport): refresh the live attestations against the 0.98.0 release

Re-run all 21 live attestations (hosted public repositories, the direct
proxy and Pilot node paths, and disposable Gitea and Forgejo instances over
HTTPS with a private CA and over SSH with a deploy key) against the 0.98.0
image, record the new date, commit, and image digest, and regenerate the
matrix page. Describe unlisted hosts without claiming more than was tested,
and add the procedure the attestation record refers to.
2026-10-23 12:51:36 -04:00

118 lines
9.1 KiB
Plaintext
Raw Blame History

---
title: Git hosts and authentication
sidebarTitle: Hosts and authentication
description: Connect a Git source to a private repository with a personal access token or an SSH deploy key, trust a private certificate authority, and understand how redirects and host keys are handled.
---
A Git source reaches its repository over HTTPS or SSH. Public repositories need nothing. Private ones need a credential, and self-hosted servers may need you to tell Sencho which certificate authority or host key to trust. Credentials belong to the Git source and stay with it when you [convert it onto a Blueprint](/features/git-managed-blueprints#convert-a-git-source).
For the full list of supported transports, ref types, and Git hosts, with the evidence behind each, see [Git transport support](/features/git-transport-support).
## Choose a method
| Repository | Authentication | Notes |
|---|---|---|
| Public, HTTPS | **Public (no auth)** | Nothing to configure. |
| Private, HTTPS | **Personal Access Token** | Read-only token. Optional custom CA for a private server certificate. |
| Private, SSH | **Deploy key (SSH)** | Read-only key plus a confirmed host key. Use an `ssh://` URL for a nonstandard port. |
<Frame caption="The authentication choices on the From Git form. Deploy key (SSH) adds the Fetch host key fingerprint button and a field for the private key. The same fields appear on the Git Source sheet.">
<img src="/images/git-authentication/ssh-deploy-key.png" alt="New stack dialog on the From Git tab with Deploy key (SSH) selected, showing the Fetch host key fingerprint button, an empty PEM private key field, and the apply behavior options Manual, Review only, Auto-write files, and Auto-deploy" />
</Frame>
Those are the only methods. GitHub App installation tokens, for example, are not supported.
Sencho stores tokens, deploy keys, and CA bundles encrypted at rest and never returns them in API responses or the UI. When you edit a source later, a secret field shows a masked placeholder. Leave it blank to keep the stored value, or type a new one to replace it. Switching **Authentication** away from a method clears what that method stored.
## HTTPS with a personal access token
Create a token with read access to the target repository only:
- **GitHub:** a fine-grained token with **Contents: Read** on the repository, or a classic token with the `repo` scope.
- **GitLab:** a project or group access token with the `read_repository` scope.
- **Bitbucket Cloud:** app passwords are deprecated in favor of API tokens, and Sencho sends a token with a fixed username. Only public Bitbucket Cloud repositories have been verified, so private access with a token or a deploy key is not yet a tested combination. [Git transport support](/features/git-transport-support) lists what has been verified.
Select **Personal Access Token**, paste the token into the field that appears, and save. Sencho gives the token only to the repository's own host. It never appears in the repository URL or in a process argument. Every pull caches the fetched compose and env content in the database so the change plan can reopen without refetching. That cache is encrypted the same way as the token, because compose files often embed secrets through env interpolation.
## SSH with a deploy key
<Steps>
<Step title="Generate a key pair">
On a trusted machine, run `ssh-keygen -t ed25519 -f deploy-key -N ""`.
</Step>
<Step title="Register the public key">
Add the public key to the Git host as a deploy key with read access. On GitHub this is **Settings → Deploy keys** on the repository.
</Step>
<Step title="Paste the private key">
In Sencho, set **Authentication** to **Deploy key (SSH)** and paste the private key.
</Step>
<Step title="Confirm the host key">
Click **Fetch host key fingerprint**. Sencho probes the host with `ssh-keyscan`, shows the SHA256 fingerprint, and stores the matching `known_hosts` line. Compare the fingerprint with the host's published value before you save.
</Step>
</Steps>
Sencho checks the host key on every fetch against the stored line. If the server's key changes, pulls fail with a host-key error until you review the new fingerprint and update trust deliberately.
The familiar `git@host:org/repo.git` form assumes port 22. When the Git server listens elsewhere, use `ssh://git@git.example.com:2222/org/repo.git`.
## Private HTTPS with a custom CA
Self-hosted Git servers often present certificates signed by a private certificate authority. By default Sencho trusts the system certificate store on the host running the fetch. When your server uses a private CA, paste its certificate (PEM) into **Custom CA certificate** on the Git source form.
Sencho combines your CA with the system trust anchors instead of replacing them, so public hosts such as GitHub keep validating. Leave the field empty when the server's certificate is publicly trusted.
Removing a stored CA always saves, even when the server currently needs it. Retiring a certificate you no longer trust should never be blocked by the unreachability that retiring it causes. If the server still needs a private CA afterward, the next pull reports a certificate trust error until you upload one again.
## Redirects
Some Git servers answer with a redirect, for example when a repository moves to a canonical path. Sencho follows a redirect that stays on the same server (same scheme, host, and port) and only changes the path, so a relocated repository keeps working.
A redirect to a different server is refused, and the pull reports that the host redirected elsewhere. Sencho does not contact that server or send it your credentials. If a repository has genuinely moved to a new host, update the repository URL on the source.
## Troubleshooting
<AccordionGroup>
<Accordion title="Repository not found or not accessible">
Verify the URL is reachable from the Sencho host and ends with `.git`. GitHub returns "not found" both for missing repositories and for private repositories you cannot read, so Sencho tailors its hint to what you supplied.
- **No token configured:** the repository may be private. Switch **Authentication** to **Personal Access Token** and paste a token with read access.
- **Token configured:** check the URL, and that the token can read this specific repository. Fine-grained tokens need **Contents: Read** on it; classic tokens need the `repo` scope.
</Accordion>
<Accordion title="Authentication failed">
The Git host rejected the credentials. For HTTPS, the token may be missing, expired, or lack read access: generate a new one and replace the value. For SSH, the deploy key may be wrong or not registered on the host: paste the matching private key or add the public key on the host. Sencho returns this as a 400 form error rather than a 401, so an upstream failure does not sign you out of the dashboard.
</Accordion>
<Accordion title="SSH host key verification failed">
The server's host key no longer matches the fingerprint you accepted. That can mean a man-in-the-middle or an intentional key rotation. Click **Fetch host key fingerprint** again, compare the SHA256 value out of band with your operator, and save only if you intend to trust the new key.
</Accordion>
<Accordion title="Certificate trust error on an HTTPS host">
The server's certificate is not signed by an authority Sencho trusts. Paste the issuing CA into **Custom CA certificate** on the source and pull again.
</Accordion>
<Accordion title="Certificate expired, not yet valid, or for another hostname">
A custom CA does not fix these. Renew the server's certificate, check the Sencho host's clock, or change the repository URL to the hostname the certificate names.
</Accordion>
<Accordion title="Unsupported repository URL">
Git sources accept `https://` URLs and SSH URLs (`git@host:org/repo.git` or `ssh://git@host:port/path`), and a URL cannot carry a username and token (`https://user:token@host/...`). Other schemes and embedded credentials are refused when you save. Put the token in the **Personal Access Token** field instead.
</Accordion>
<Accordion title="SSH repository URLs require a deploy key">
An SSH URL cannot be used with **Public (no auth)** or a token. Switch **Authentication** to **Deploy key (SSH)**, or use the repository's `https://` URL.
</Accordion>
<Accordion title="Repository host is not allowed">
The repository resolves to a loopback, link-local, multicast, or other special-use address, which Sencho refuses before sending any request. A host on your LAN or VPN is fine. See [Git transport support](/features/git-transport-support#not-supported).
</Accordion>
<Accordion title="Rate limited">
The Git host answered that too many requests arrived in a short window. Wait a few minutes and pull again. If polling is on, a longer **Poll interval** in **Settings → GitOps** lowers the request rate.
</Accordion>
<Accordion title="Could not resolve, connection refused, or timed out">
The Sencho host could not reach the repository host. Check DNS, firewalls, and proxies from the node that owns the stack, because pulls run there. A fetch that has not finished in 30 seconds reports a timeout.
</Accordion>
</AccordionGroup>
Reference in New Issue View Git Blame Copy Permalink