Git & Repositories

Git & Repositories

Sencai includes a built-in Git hosting service powered by Gitea — a self-hosted, open-source Git platform. Every organisation gets its own isolated namespace where repositories, packages, and CI pipelines live.

Note

Sencai runs a single Gitea instance (Apps) for all organisation repositories. An earlier “Toolbox” instance existed during initial development but was retired in Phase 1 (2026-04-19) — all repositories, packages, and CI pipelines live in the single Apps instance described below.

What is Git Integration in Sencai?

• Organisation-scoped — Repositories belong to an organisation, not individual users. Every member of the organisation can access them according to their role.
• Self-hosted — Your code stays on Sencai’s infrastructure (or your own, if you use BYOC). Nothing is shared with third-party Git hosts.
• CI/CD ready — Gitea Actions (GitHub Actions-compatible) runs pipelines directly from your workflow files.

Viewing Repositories

Navigate to Gravity → Git (/gravity/git) to see a list of all repositories in the currently selected organisation.

Use the organisation selector in the header to switch between organisations. The repository list updates automatically.

Creating a Repository

1. Open Gravity → Git
2. Click New repository
3. Fill in the details:
   • Name — Repository slug (lowercase, hyphens allowed; e.g. my-service)
   • Description (optional) — Short description shown in the repository list
   • Visibility — Private (only org members) or Public
   • Auto-initialize — Creates an initial commit with a README.md so the repository is immediately cloneable
4. Click Create repository

The repository appears in the list within seconds and is ready for git clone.

Deleting a Repository

Danger

Deleting a repository is permanent. All commits, branches, issues, and packages are removed and cannot be recovered.

1. Open the repository
2. Go to the Settings tab
3. Scroll to Danger zone
4. Click Delete this repository
5. Type the full repository name to confirm
6. Click I understand, delete this repository

Repository Detail

Each repository has six tabs:

Overview

The landing page for a repository. Shows:

• Description and optional website link

• Clone URL — copy the HTTP or SSH URL to clone locally:

  # HTTP (production)
  git clone https://git.sencai.space/acme-corp/my-service.git
  
  # SSH (production, port 22)
  git clone git@git.sencai.space:acme-corp/my-service.git

• Topics — tags for discoverability

• Meta — last push time, star count, fork count, language breakdown

Note

In local development, Gitea is reached via http://localhost/gitea-apps (Traefik PathPrefix routing), not a git. subdomain — no git.sencai.localhost/git.sencai.space Traefik host rule exists in the local orchestration config.

# HTTP (local development)
git clone http://localhost/gitea-apps/acme-corp/my-service.git

For SSH in local development, Gitea Apps SSH is exposed on host port 9033, not 22:

# SSH (local development)
git clone ssh://git@localhost:9033/acme-corp/my-service.git

Alternatively, add a Port 9033 override for localhost in your ~/.ssh/config.

Files

Browse the repository file tree at any branch or tag. Click any file to preview its contents inline. Supported previews include Markdown, JSON, YAML, and most source code files.

The Open in VS Code button (shown on file and directory views) launches VS Code with the repository URL pre-filled via the vscode:// URI scheme. Requires the VS Code remote extension to be installed locally.

Commits

Full commit history for the current branch. Each entry shows:

• Commit message and short SHA
• Author name and avatar
• Relative and absolute timestamp

Click a commit SHA to see the full diff.

Issues

A lightweight issue tracker scoped to the repository.

• Use the Open / Closed filter to switch views
• Click New issue to create an issue with a title, description, and optional labels
• Issues can be referenced from commit messages using #<number> syntax

Packages

Gitea doubles as a package registry. Packages published into this repository’s namespace appear here:

Type	Example
Container (OCI)	Docker images via docker push
npm	npm publish --registry ...
PyPI	pip install --index-url ...
Helm	Helm chart repository
Generic	Binary artifacts via curl upload

See the Gitea package registry documentation for per-type publish commands.

Settings

Repository settings (available to organisation owners and repository admins):

General

• Rename the repository
• Update description and website
• Change visibility (private ↔ public)
• Enable or disable the Issues tracker

Deploy Keys Read-only or read-write SSH keys for automated deployments (CI runners, servers). Unlike user SSH keys, deploy keys are scoped to a single repository.

Webhooks Configure outbound HTTP webhooks triggered by push, pull request, issue, or release events. Useful for connecting external services.

Secrets & Variables Repository-level secrets and variables consumed by Gitea Actions workflows:

• Secrets — Encrypted values accessible as ${{ secrets.MY_SECRET }} in workflows
• Variables — Plain-text values accessible as ${{ vars.MY_VAR }} in workflows

Mirror Repositories

Mirrors let you track an external Git repository and pull updates automatically on a schedule.

Navigate to Gravity → Git → Mirrors (/gravity/git/mirrors) to manage mirrors for the current organisation.

Adding a Mirror

1. Click Add mirror
2. Fill in:
   • Remote URL — The upstream repository URL (HTTPS recommended; e.g. https://github.com/acme/upstream.git)
   • Name — Local repository name that will be created in your organisation
   • Auth token (optional) — Personal access token for private upstream repositories
   • Sync interval — How often to pull changes:
     • 8 hours
     • 24 hours (default)
     • 72 hours
     • 168 hours (weekly)
3. Click Create mirror

Gitea pulls the remote on the chosen interval and keeps the local copy in sync. You can also trigger a manual sync from the repository’s Settings → Mirror section.

Note

Mirror repositories are read-only — you cannot push commits to them. Gitea Actions workflows are not triggered by mirror sync events (a push event is not generated during a mirror update). Use a scheduled trigger or a manual dispatch instead.

Deleting a Mirror

1. Open Gravity → Git → Mirrors
2. Find the mirror in the list
3. Click the Delete icon
4. Confirm the deletion

The local copy of the repository is removed from your organisation. The upstream source is not affected.

CI / Pipelines

Navigate to Gravity → Git → CI (/gravity/git/ci) for an overview of all Gitea Actions workflow runs across the organisation.

Each run shows:

• Repository and workflow name
• Trigger event (push, pull request, schedule, manual)
• Status: success, failure, or running
• Timestamp and duration

Click a run to see per-job logs.

Writing Workflow Files

Gitea Actions uses the same YAML syntax as GitHub Actions. Sencai’s Gitea is configured to look for workflow files in these directories (checked in order):

1. .sencai/workflows/ — recommended (Sencai-native path)
2. .gitea/workflows/
3. .github/workflows/

Minimal example

Create .sencai/workflows/ci.yml in your repository:

name: CI

on:
  push:
    branches: [main]
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install
        run: npm ci
      - name: Test
        run: npm test

Push the file to trigger the first run. Status appears in the CI tab and in Gravity → Git → CI.

Note

Gitea Actions runners must be registered for workflows to execute. If no runner is available, runs queue indefinitely. Contact your Sencai administrator to verify runner availability.

Troubleshooting

Q: Clone fails with “Repository not found”

A: Verify you are using the correct organisation name and repository slug. Check that you are a member of the organisation and that the repository is not set to a visibility you cannot access.

Q: SSH clone fails with “Permission denied (publickey)”

A: Make sure you have added your SSH public key to your Sencai account under Account Settings → SSH Keys. Test connectivity with ssh -T git@git.sencai.space in production, or ssh -T -p 9033 git@localhost in local development.

Q: Workflow is queued but never starts

A: No runner is available for the runs-on label in your workflow. Ask your administrator to check the registered runners in the Gitea admin panel.

Q: Mirror is not updating

A: The upstream URL may be unavailable or the auth token may have expired. Go to the repository Settings → Mirror and trigger a manual sync to see the error message.

Q: “Open in VS Code” does nothing

A: Make sure VS Code is installed and the Remote Repositories extension (or Remote — SSH) is active. The vscode:// URI scheme must be registered in your browser.