mirror of
https://github.com/Studio-Saelix/sencho.git
synced 2026-08-05 00:18:00 +00:00
Anso
3955267bbe
* refactor(git-sources): extract GitSourceFields from GitSourcePanel Pure extraction of the repo/branch/path/auth/apply-mode form fields into a reusable controlled component so the upcoming Create Stack from Git flow can render the same form in the Create Stack dialog. No behavior change. * feat(git-sources): create a stack from a Git repository Add a From Git tab to the Create Stack dialog so users can name a new stack, point it at a repo + branch + compose path, and have the compose fetched, validated, written to disk, and linked in one shot. Optional deploy-after-create runs the initial bring-up when requested. Backend: new POST /api/stacks/from-git route gated by stack:create. GitSourceService.createStackFromGit() fetches and validates before touching disk, then creates the stack, writes the compose (and .env if sync is enabled), and seeds the git source row with the fetched commit so future pulls produce a clean diff. Runs under the per-stack lock so a concurrent webhook cannot race the create. Deploy failure is non-fatal and surfaced to the caller. Frontend: the existing Create Stack dialog is now tabbed, with Empty keeping the original single-field flow unchanged. * test(git-sources): cover create-from-git endpoint and e2e flow Service tests verify createStackFromGit seeds the last_applied columns on success, writes the env file when sync is enabled, refuses an invalid apply-matrix without fetching, rejects invalid compose without leaving orphan state, and rolls back the on-disk stack dir when a post-create step fails. Route tests cover auth, missing stack_name, invalid stack name, http:// rejection, oversized repo_url, and the 409 collision guard. E2E adds a Create-stack-from-Git block covering tab visibility, client-side HTTPS check, backend .git/config rejection, and a happy-path fetch against a public demo repo (skipped on network failure). * docs(git-sources): document create-stack-from-git tab Add a new section near the top describing the From Git tab in the Create Stack dialog: what it does, the Deploy after create checkbox, and the four failure modes (name collision, unreachable repo, invalid compose, deploy-after-create failure).
186 lines
11 KiB
Plaintext
186 lines
11 KiB
Plaintext
---
|
|
title: Git Sources
|
|
description: Link a stack to a Git repository and keep compose.yaml in sync via manual pulls or webhook triggers.
|
|
---
|
|
|
|
Git Sources turn any stack into a GitOps target. Point Sencho at a repository, branch, and `compose.yaml` path; pull updates on demand or from CI; and review a diff before applying changes to disk. Optional sibling `.env` sync keeps configuration consistent too.
|
|
|
|
Git Sources are available to all Sencho users on the Community tier.
|
|
|
|
## How it works
|
|
|
|
1. Open a stack's editor and click **Git Source**.
|
|
2. Fill in the repository URL, branch, and compose file path. Add a token if the repo is private.
|
|
3. Click **Pull now** to fetch the latest compose content. Sencho shows a side-by-side diff.
|
|
4. Click **Apply** to write the incoming content to disk. Optionally deploy immediately.
|
|
|
|
Writes land in the stack's existing directory using the same storage Sencho uses for the in-browser editor. Existing history, alerts, and metrics are unaffected.
|
|
|
|
## Create a stack from a Git repository
|
|
|
|
Skip the "empty stack then link later" detour and point at a repo from the start. Click **Create Stack** in the sidebar, switch to the **From Git** tab, and fill in the same fields you would on the Git Source panel.
|
|
|
|
<Frame>
|
|
<img src="/images/git-sources/create-from-git-tab.png" alt="Create Stack dialog with the From Git tab selected, showing stack name, repository URL, branch, compose path, and a Deploy after create checkbox" />
|
|
</Frame>
|
|
|
|
Sencho fetches the compose file, validates it with `docker compose config`, writes it to a fresh stack directory, and links the git source in one step. The last-applied commit sha is seeded from the fetch so the first pull produces a clean diff rather than a "local edits detected" warning.
|
|
|
|
Tick **Deploy after create** to run `docker compose up -d` immediately after the files land. If the deploy fails, the stack and git source are kept on disk so you can fix the underlying issue (missing image, port conflict, host resources) and retry the deploy from the editor.
|
|
|
|
### Failure modes on create
|
|
|
|
| Situation | What happens |
|
|
|-----------|--------------|
|
|
| Stack name already exists | Sencho returns **409** with "Stack already exists" and makes no changes on disk or in the database. Pick a different name or remove the existing stack. |
|
|
| Repository unreachable or auth failed | Fetch fails before anything is created. The form stays open with an error toast describing the cause. |
|
|
| Fetched compose fails validation | The stack directory is not created and no git source row is inserted. The error toast shows the `docker compose config` message. |
|
|
| Fetch + validate succeed but optional deploy fails | The stack and git source are kept. The toast reads "Stack created, but deploy failed: ..." and you can retry the deploy from the editor. |
|
|
|
|
## Configure a source
|
|
|
|
<Frame>
|
|
<img src="/images/git-sources/panel.png" alt="Git Source panel with repository URL, branch, compose path, and apply mode" />
|
|
</Frame>
|
|
|
|
| Field | Description |
|
|
|-------|-------------|
|
|
| **Repository URL** | `https://github.com/your-org/your-repo.git` (HTTPS only) |
|
|
| **Branch** | Branch to track (e.g. `main`) |
|
|
| **Compose file path** | Path within the repo (e.g. `deploy/compose.yaml`) |
|
|
| **Also sync sibling `.env`** | When enabled, also pulls `.env` from the same directory as the compose file |
|
|
| **Auth** | `None` for public repos, `Personal Access Token` for private repos |
|
|
| **Apply behavior** | See the three modes below |
|
|
|
|
Saving runs a reachability check against the repository. If the URL is wrong, the token is invalid, the branch does not exist, or the file is missing, Sencho surfaces the error inline and nothing is persisted.
|
|
|
|
### Apply behavior modes
|
|
|
|
| Mode | What happens when a webhook fires |
|
|
|------|-----------------------------------|
|
|
| **Review only** | Sencho fetches + validates the incoming commit and marks the stack as having a pending update. You review the diff and apply manually. |
|
|
| **Auto-write** | Sencho writes the new compose + env to disk automatically but does not redeploy. Use this when another process handles rollout. |
|
|
| **Auto-deploy** | Sencho writes the files and immediately runs `docker compose up -d` so the stack picks up the new configuration. |
|
|
|
|
You can always override on the spot: when you click **Apply** in the diff dialog, a **Deploy after apply** checkbox lets you deploy regardless of the configured mode.
|
|
|
|
## Pulling and reviewing changes
|
|
|
|
Click **Pull now** on the Git Source panel to fetch the latest commit on the configured branch.
|
|
|
|
<Frame>
|
|
<img src="/images/git-sources/diff-dialog.png" alt="Diff dialog showing a side-by-side comparison between the on-disk compose.yaml and the incoming commit" />
|
|
</Frame>
|
|
|
|
The diff dialog shows:
|
|
|
|
- The commit sha being compared (short form, next to the stack name)
|
|
- A side-by-side compare of the on-disk compose file and the incoming version
|
|
- A `.env` tab when the source is configured to sync `.env`
|
|
- A **validation** banner when the incoming compose fails `docker compose config` (you cannot apply an invalid file)
|
|
- A **local edits detected** banner when the on-disk content differs from the last applied commit. Applying in this state overwrites those edits. The Apply button becomes a confirmation prompt.
|
|
|
|
### Pending updates
|
|
|
|
When a webhook fires in **Review only** mode, the stack gets a pending update badge in the sidebar and a dot on the **Git Source** button in the editor. Clicking either opens the diff dialog with the incoming content already loaded; there's no second network round-trip to apply.
|
|
|
|
<Frame>
|
|
<img src="/images/git-sources/sidebar-badge.png" alt="Sidebar stack entry with a small branded dot indicating a pending Git source update" />
|
|
</Frame>
|
|
|
|
Click **Dismiss** on the Git Source panel to discard a pending update without applying.
|
|
|
|
## Trigger from CI with a webhook
|
|
|
|
Git sources integrate with Sencho's existing webhook system. Create a webhook targeting the stack with the **Git source sync** action.
|
|
|
|
<Frame>
|
|
<img src="/images/git-sources/webhook-action.png" alt="Webhook creation form with Git source sync selected in the action dropdown" />
|
|
</Frame>
|
|
|
|
The webhook's behavior on trigger depends on the source's apply mode:
|
|
|
|
- **Review only**: fetch + validate + diff, mark pending.
|
|
- **Auto-write**: fetch, validate, write to disk.
|
|
- **Auto-deploy**: fetch, validate, write, deploy.
|
|
|
|
The Git source sync action is only selectable on webhooks whose target stack already has a Git source configured. Webhook triggers for a single source are debounced so a runaway pipeline cannot overwhelm Sencho (or your repository host's rate limits); the dashboard records the skipped trigger in the webhook's execution history.
|
|
|
|
### GitHub Actions example
|
|
|
|
```yaml
|
|
- name: Sync compose via Sencho
|
|
run: |
|
|
BODY='{}'
|
|
SIGNATURE=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "${{ secrets.SENCHO_WEBHOOK_SECRET }}" | cut -d' ' -f2)
|
|
curl -X POST "${{ secrets.SENCHO_URL }}/api/webhooks/${{ secrets.SENCHO_WEBHOOK_ID }}/trigger" \
|
|
-H "Content-Type: application/json" \
|
|
-H "X-Webhook-Signature: sha256=$SIGNATURE" \
|
|
-d "$BODY"
|
|
```
|
|
|
|
See the [Webhooks](/features/webhooks) page for the full signing protocol.
|
|
|
|
## Private repositories
|
|
|
|
For private repositories, use a Personal Access Token scoped to read access on the target repo:
|
|
|
|
- **GitHub**: a fine-grained PAT with **Contents: Read** permission on the repo, or a classic PAT with the `repo` scope.
|
|
- **GitLab**: a project or group access token with the `read_repository` scope.
|
|
- **Bitbucket**: an app password with **Repositories: Read**.
|
|
|
|
Paste the token into the **Token** field and save. Sencho stores it encrypted at rest and never returns it in API responses or UI. When editing the source later, the token field shows a masked placeholder; leave it blank to keep the stored value, or type a new token to replace it. Switching the auth type to **None** clears the stored token.
|
|
|
|
## Local edits vs Git
|
|
|
|
Sencho tracks a hash of the compose + env contents at the moment of the last apply. When you pull, it compares that hash against the current on-disk content.
|
|
|
|
- Matching hash: applying overwrites content that Sencho itself last wrote.
|
|
- Differing hash: someone edited the files outside Git. The diff dialog shows a warning, and Apply requires confirmation.
|
|
|
|
The in-browser editor and the Git Source panel both write to the same files, so you can always fall back to editing locally. The next pull will just flag the divergence rather than silently clobbering your edits.
|
|
|
|
## Troubleshooting
|
|
|
|
<AccordionGroup>
|
|
<Accordion title="Repository not found or not accessible">
|
|
Verify the URL is reachable from the Sencho host and ends with `.git`. For private repos, confirm the token is present and has read access. If you rotated the token, open the panel and paste the new value.
|
|
</Accordion>
|
|
|
|
<Accordion title="Authentication failed">
|
|
Your token is missing, expired, or lacks read access to the repository. Generate a new token and replace the value in the **Token** field.
|
|
</Accordion>
|
|
|
|
<Accordion title="Branch not found">
|
|
The branch name is case-sensitive and must exist on the remote. Confirm the branch with `git ls-remote <url>` from a shell that has access.
|
|
</Accordion>
|
|
|
|
<Accordion title="File not found">
|
|
The compose path is relative to the repository root and must point at the file, not its parent directory. If the file was moved, update the path on the panel and save.
|
|
</Accordion>
|
|
|
|
<Accordion title="Compose validation failed">
|
|
Sencho runs `docker compose config` against the incoming content before letting you apply. The error banner shows the exact message. Common causes: unresolved `${VAR}` interpolation (fix by enabling sibling `.env` sync and committing the file), invalid `include:` paths, or schema issues introduced by a recent compose change.
|
|
</Accordion>
|
|
|
|
<Accordion title="Local edits detected">
|
|
The on-disk files diverge from the last applied Git commit. Either apply anyway to overwrite the local edits (the confirmation prompt makes this explicit), or discard local work with a redeploy from the stack editor, or commit your local changes back to the repo so the diff becomes clean.
|
|
</Accordion>
|
|
|
|
<Accordion title="Webhook skipped (rate limited)">
|
|
Sencho debounces rapid-fire triggers per source. Wait a few seconds and retry, or consolidate multiple CI triggers into a single call at the end of your pipeline.
|
|
</Accordion>
|
|
|
|
<Accordion title="Network timeout">
|
|
The clone did not finish in time. Check that the Sencho host can reach the repository host (proxies, firewalls, DNS) and try again.
|
|
</Accordion>
|
|
|
|
<Accordion title="Applied but deploy failed">
|
|
The incoming compose file was written to disk successfully, but the subsequent `docker compose up -d` did not complete. The toast message includes the underlying reason (for example, an image pull failure or a port conflict). The stack is already on the new content, so you can retry the deploy directly from the editor's **Deploy** button without re-pulling. Fix the root cause first (image availability, host resources, network config) and redeploy.
|
|
</Accordion>
|
|
</AccordionGroup>
|
|
|
|
<Note>
|
|
Git Sources currently use HTTPS only. SSH URLs and SSH keys are not supported.
|
|
</Note>
|