Catalyst · Complete User Guide

The Catalyst User Guide

Everything you need to write, review, ship, secure and operate code on Catalyst — your self-hosted, GitHub-comparable platform. Written for complete newcomers and seasoned engineers alike.

How to use this guide

Sections are tagged by the experience they assume. Follow the path that fits you:

• New to Git entirely? Read Git in five minutes, then Your first repository and Browsing & editing — you can do a lot without ever touching a terminal.
• Comfortable with GitHub/GitLab? Skim Getting the code for the Catalyst-specific URLs, then jump to Pull requests, Pipelines and the Cheat sheet.
• Running the instance? Head to Administration and REST API.

Git in five minutes Beginner

If you've never used version control, here's the whole mental model. Git tracks the history of a folder of files. Catalyst is where that history lives so a team can share it.

A typical day looks like this:

# 1. get the project onto your machine (once)
git clone http://<host>/acme/payments-api.git
cd payments-api

# 2. start a branch for your change
git checkout -b fix-login

# 3. edit files, then save a snapshot
git add .
git commit -m "Fix the login redirect"

# 4. send it to Catalyst
git push origin fix-login

Then you open a pull request in the web UI to get it reviewed and merged. That's the core loop. Everything else in this guide builds on it.

Signing in & two-factor Beginner

1. Open this instance and click Sign in. Enter the username and password your administrator gave you.
2. If single sign-on is enabled, click Sign in with SSO instead and authenticate with your company account.
3. Turn on two-factor (recommended). Go to your avatar → Account → Two-factor authentication → Set up 2FA. Scan the secret into an authenticator app (Google Authenticator, 1Password, Aegis…), enter the 6-digit code, and click Enable 2FA.

Your first repository Beginner

1. Click ＋ New in the top bar.
2. Give it an owner (your username or a team namespace), a name (e.g. payments-api), and a description.
3. Choose Public (anyone on the instance can read) or Private (only you and collaborators).
4. Leave Add a README ticked so the repository is browsable immediately, then Create repository.

If you create an empty repository instead, Catalyst shows the exact commands to push an existing project:

echo "# payments-api" >> README.md
git init
git add README.md
git commit -m "Initial commit"
git branch -M main
git remote add origin http://<host>/acme/payments-api.git
git push -u origin main

Getting the code: clone & wget URLs Beginner

Every repository page has a Get the code panel with two ready-to-copy commands. This is a signature Catalyst feature: the host adapts to how you reached the instance. Reach it on the internal network and you get the internal address; reach it from outside and you get the external one. A toggle switches between them.

# Clone with Git (full history, to work on it)
git clone http://<host>/acme/payments-api.git

# Download a snapshot with wget (just the files, no history)
wget http://<host>/acme/payments-api/archive/main.tar.gz

The archive endpoint accepts any branch or tag, and both formats:

Browsing & editing in the browser Beginner

Click View code (or the file tree) to browse. Click a folder to go in, a file to read it — text files are syntax-highlighted. Use the branch links in the file panel header to switch branches, and the Commits tab for history.

To make a quick change without cloning:

1. Open a file and click Edit.
2. Change the content, write a commit message, and click Commit to main.
3. To add a new file, use New file on the repository page.

Uploading files & folders (drag & drop). Click ↑ Upload files on the repository page, then drag files or whole folders onto the drop zone — any type, including images and binaries. Dropped folders keep their structure. You can also use Choose files or Choose folder. Optionally set a destination folder, add a commit message, and Commit. No terminal or Git required.

Branches & commits Intermediate

git checkout -b feature/webhooks   # create + switch to a branch
git add path/to/file               # stage specific changes
git commit -m "Add webhook retries"
git push -u origin feature/webhooks # publish the branch

git fetch                          # see what's new on the server
git pull                           # fetch + merge into your branch
git log --oneline -10              # recent history

Write commit messages in the imperative ("Add…", "Fix…") and keep each commit focused — it makes review and history far easier to follow.

Issues Beginner

Issues track bugs, tasks and ideas. Open the Issues tab on a repository and click New issue.

• Give it a clear title and a description of what's wrong or wanted.
• Mention a teammate with @username — they get a notification.
• Comment to discuss; click Close issue when it's resolved (or Reopen later).

Pull requests & code review Intermediate

A pull request (PR) proposes merging a source branch into a target branch (usually main), with review first.

1. Push your branch, open the Pull requests tab, click New pull request.
2. Pick the base (target) and your source branch, then Compare to preview the commits and diff.
3. Add a title and description, then Create pull request.

Reviewing

• Read the coloured diff. To comment on a precise place, use Comment on a specific line (give the file path and line number).
• Submit a review: Approve, Request changes, or Comment. A "request changes" review blocks the merge until resolved.
• Owners can Request review from specific people.

When requirements are met, click Merge pull request. Catalyst creates a merge commit and marks the PR merged. If the automatic merge conflicts, the details are posted as a comment so you can rebase and try again.

Protected branches & merge gating Advanced

Protect important branches so changes can't merge until they're reviewed and green. In the repository's Settings → Branch protection, add a rule:

On a protected PR the merge button stays disabled and shows exactly what's missing. A CODEOWNERS file auto-requests review from the owners of the changed paths:

# CODEOWNERS (in repo root, .catalyst/ or docs/)
*.py            @backend-lead
/frontend/      @alice @bob
/docs/          @tech-writer

Pipelines (CI/CD) Intermediate Advanced

Add a .catalyst-ci.yml file to your repository root. It runs automatically on every push to the default branch, and you can run it manually on any branch from the Pipelines tab.

name: build-and-test
steps:
  - name: install
    run: pip install -r requirements.txt
  - name: test
    run: pytest -q

Each step's run is a shell command executed in a fresh checkout of the ref. Steps run in order; the run fails on the first non-zero exit. Open a run to read the combined logs.

Secrets, artifacts & schedules Advanced

Secrets are added in Settings → CI secrets and injected as environment variables — they never appear in logs. Artifacts are files to keep after a successful run. A schedule runs the pipeline periodically.

name: nightly
schedule: "@daily"            # or "@hourly", or { every_minutes: 30 }
artifacts:
  - dist/*                    # collected & downloadable from the run page
steps:
  - name: build
    run: make build           # $DEPLOY_TOKEN etc. available as env vars
  - name: package
    run: tar czf dist/app.tgz build/

Deployments & environments Advanced

Define environments in Settings → Environments (e.g. staging, production), optionally requiring approval. Then from Pipelines → Deployments, request a deploy of a ref to an environment. If approval is required, an admin approves it, which triggers the pipeline with CATALYST_ENVIRONMENT set so your steps know where they're deploying.

Publishing a version Intermediate

Click the prominent ⌦ Publish version button (on the Code page or the Packages tab) to cut a version. Give it a tag (e.g. v1.2.0), a project overview, the features & changes in this version, and optionally attach a binary. Publishing creates the git tag and opens the version page — a clean overview of the release with the exact commands to pull it:

git clone --branch v1.2.0 http://<host>/acme/payments-api.git
# or, in an existing clone:
git fetch --tags && git checkout v1.2.0
# or grab the source snapshot:
wget http://<host>/acme/payments-api/archive/v1.2.0.tar.gz

The Packages tab lists every version; each links to its version page and downloads. To remove a version, open its version page and click Delete this version — this deletes the release and its git tag (it will no longer be pullable).

Package registries Advanced

Catalyst hosts language package registries so build tools install straight from your instance. Uploads authenticate with a personal access token as the password.

Python (PyPI)

pip install --index-url http://<host>/registry/pypi/simple/ mypackage
twine upload --repository-url http://<host>/registry/pypi/ dist/* -u __token__ -p cat_XXXX

Node (npm)

npm install --registry http://<host>/registry/npm/ mypackage
npm publish --registry http://<host>/registry/npm/

Java (Maven)

<repository>
  <id>catalyst</id>
  <url>http://<host>/registry/maven/</url>
</repository>

Anything else (generic)

curl -u user:cat_XXXX --upload-file app.bin \
  http://<host>/registry/generic/acme/app/1.0.0/app.bin
curl -O http://<host>/registry/generic/acme/app/1.0.0/app.bin

Security: secret & dependency scanning Intermediate

On every push Catalyst scans your code and dependencies and raises alerts on the repository's Security tab.

Secret scanning

Flags credentials committed by accident — cloud keys, private-key blocks, API tokens. Each finding shows the file and line. Rotate the exposed secret, remove it from the code, and mark the alert Resolved.

Dependency scanning (SCA)

Catalyst parses your manifests and compares them to a security advisory feed, raising a "vulnerable dependency" alert with the advisory ID and severity.

Fix by upgrading to the fixed version and pushing again; the alert clears on the next scan. Use Re-scan default branch to check on demand. Administrators manage the advisory feed under Admin → Security advisories.

Git over SSH Intermediate

SSH avoids typing a password on every push. It must be enabled on the instance (default port 2222).

1. Create a key pair if you don't have one: ssh-keygen -t ed25519.
2. Copy your public key (~/.ssh/id_ed25519.pub) into Account → SSH keys → Add SSH key.
3. Clone and push over SSH:

git clone ssh://git@<host>:2222/acme/payments-api.git
# then the usual: git push / git pull

Personal access tokens Intermediate

Tokens authenticate Git-over-HTTP and the REST API without your password (and bypass 2FA prompts, which is what you want for automation). Create one in Account → Personal access tokens — copy it immediately; it's shown only once.

# use a token as the git password over HTTP
git clone http://alice:cat_XXXXXXXX@<host>/acme/payments-api.git

# use it as a Bearer token for the API
curl -H "Authorization: Bearer cat_XXXXXXXX" http://<host>/api/v1/user

Teams, collaborators & permissions Advanced

Grant access two ways:

• Per repository — Settings → Collaborators, add a user with read, write or admin.
• By team — admins create teams under Teams and add members.

The repository owner and site administrators always have admin rights. Public repositories are readable (and cloneable) by anyone on the instance. Single sign-on (OIDC) and LDAP directory sign-in can be enabled by an administrator; accounts are created automatically on first login.

Deleting a repository. With admin rights, open Settings → Danger zone, type the repository name to confirm, and click Delete this repository. This permanently removes the code, issues, pull requests, pipelines, packages and settings — it cannot be undone.

Search, wiki & insights Beginner

• Search — the top-bar box searches repositories and issues; switch to Include code to grep across code you can read.
• Wiki — each repository has a Markdown wiki (the Wiki tab). Create a home page and link others.
• Insights — commit counts, branches, contributors and open issue/PR totals for a repository.

REST API Advanced

Automate Catalyst from scripts and CI. Authenticate with a token as a Bearer header (or Basic auth).

TOKEN=cat_XXXXXXXX
# list your repositories
curl -H "Authorization: Bearer $TOKEN" http://<host>/api/v1/repos

# open an issue from a script
curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"title":"Nightly job failed","body":"See attached log"}' \
  http://<host>/api/v1/repos/acme/payments-api/issues

Webhooks Advanced

Fire an HTTP POST to your own service when things happen. In Settings → Webhooks, add a URL, the events (comma-separated: push, issue, pull_request, pipeline, release, or *), and a secret. Each delivery is signed with HMAC-SHA256 in the X-Catalyst-Signature header.

# verify a delivery (Python)
import hmac, hashlib
def valid(secret, body_bytes, header):
    expected = "sha256=" + hmac.new(secret.encode(), body_bytes, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header)   # header = X-Catalyst-Signature

Import & mirroring Intermediate

Move existing projects onto Catalyst. From the dashboard click Import, give the source Git URL (GitHub, GitLab, any Git remote) and a new name. The full history is mirrored. A scheduled pull mirror can keep the copy in sync with an upstream automatically.

Git LFS (large files) Advanced

Catalyst includes a Git LFS server for large binaries (datasets, media, models). With the git-lfs client installed:

git lfs install
git lfs track "*.psd"        # store these via LFS
git add .gitattributes design.psd
git commit -m "Add design asset"
git push                     # the large object goes to the LFS store

Administration Advanced

Site administrators get an Admin link in the top bar.

Operations

• Backups & restore — download from Admin → Backups. To restore: stop Catalyst, extract the archive over an empty data directory, start again.
• Metrics — GET /metrics exposes Prometheus gauges (users, repos, runs, open issues/PRs/alerts) for scraping.
• Rate limiting — set CATALYST_RATE_LIMIT (requests/min/IP) to protect the web UI.

Cheat sheet All levels

Everyday Git

git clone http://<host>/<owner>/<repo>.git   # or ssh://git@<host>:2222/…
git checkout -b my-branch
git add .  &&  git commit -m "message"
git push -u origin my-branch
git pull ; git fetch --all

Catalyst URLs

.catalyst-ci.yml keys

name: <pipeline name>
schedule: "@hourly" | "@daily" | { every_minutes: N }
artifacts: [ "glob", ... ]
steps:
  - name: <step name>
    run: <shell command>

Troubleshooting All levels

Glossary Beginner