Erste Schritte

Diese Anleitung führt dich von der Registrierung bis zu einer funktionierenden CI-Pipeline. Sie setzt voraus, dass du ein Terminal mit installiertem git geöffnet hast.

Du kaufst oder verwaltest fremforge, statt darauf zu programmieren? Deine erste Stunde mit fremforge führt in verständlicher Sprache und mit einem Ablaufdiagramm durch Registrierung, SSO, Zahlung und die Einrichtung des Break-Glass-Zugangs. Lies diese Seite zuerst, wenn du Owner der Organisation bist, und komm hierher zurück, sobald du Code pushen willst.

Schritt 1: Registrieren

Gehe zu www.frem.sh und klicke in der oberen Navigation auf Sign up (oder direkt zu frem.sh/_app/signup). Gib deine geschäftliche E-Mail-Adresse, den Slug deiner Organisation (z. B. acme, 3–30 Zeichen) und einen Anzeigenamen ein.
Suche in deinem Posteingang nach einer Bestätigungs-E-Mail von noreply@frem.sh. Klicke auf den Link Registrierung bestätigen. Er ist 24 Stunden gültig.
Lege auf der Bestätigungsseite dein Passwort fest und klicke auf Organisation anlegen.

Deine Organisation ist sofort unter https://frem.sh/<your-org> erreichbar.

Schritt 2: Git Credential Manager einrichten (HTTPS + MFA)

fremforge empfiehlt die Anmeldung über HTTPS + Git Credential Manager (GCM) – eine interaktive Anmeldung über den IdP deiner Organisation, bei der bei jeder Token-Erneuerung MFA verlangt wird. In neuen Organisationen ist SSH standardmäßig deaktiviert; HTTPS+GCM ist der vorgesehene Weg.

GCM installieren:

# macOS
brew install --cask git-credential-manager

# Linux
curl -sL https://aka.ms/gcm/linux-install-source.sh | sh && git-credential-manager configure

# Windows: bundled with Git for Windows 2.28+

GCM für fremforge konfigurieren (einmal pro Arbeitsrechner):

git config --global credential.https://frem.sh.gitProvider gitea
git config --global credential.https://frem.sh.oauthClientId e90ee53c-94e2-48ac-9358-a874fb9e0662

Die Client-ID gehört zur eingebauten App git-credential-manager von Forgejo – eine Einrichtung pro Organisation ist nicht nötig.

Die vollständige Einrichtung, einschließlich Details zum MFA-Ablauf, Ausweichwegen (PAT für CI, SSH für Organisationen, die es wieder aktiviert haben) und Hinweisen je Plattform, findest du in der Anleitung zur sicheren Anmeldung.

Schritt 3: Dein erstes Repository anlegen

In der Oberfläche: Gehe zu frem.sh/<your-org> → + New repository. Gib den Namen des Repositorys ein, wähle die Sichtbarkeit (öffentlich oder privat), initialisiere es bei Bedarf mit einer README und klicke auf Create repository.

Ein vorhandenes lokales Repository pushen (HTTPS, empfohlen):

git remote add origin https://frem.sh/<your-org>/<your-repo>.git
git push -u origin main
# First push: GCM opens a browser tab → IdP sign-in + MFA → token cached.
# Subsequent pushes within the token's lifetime are silent.

Hat der Admin deiner Organisation SSH wieder aktiviert und bevorzugst du es, funktioniert die SSH-Variante ebenso – siehe Verbinden.

Existiert das Repository noch nicht, legt fremforge es beim ersten Push automatisch an, sofern du die Berechtigung Create repositories hast (standardmäßig alle Owner der Organisation).

Schritt 4: Teammitglieder einladen

Teammitgliedschaften werden in der nativen Team-Oberfläche von Forgejo für Organisationen verwaltet. fremforge dupliziert den Rolleneditor nicht.

Gehe zu https://frem.sh/org/<your-org>/teams und wähle das Team, in das du einladen willst (oder New team, um eines anzulegen).
Gib die E-Mail-Adresse der eingeladenen Person ein (oder ihren fremforge-Benutzernamen, sobald sie ein Konto hat).
Wähle eine Rolle:

Rolle	Zugriff
Owner	Vollständige Verwaltung der Organisation: Abrechnung, SSO, Sicherheitsrichtlinien, Mitgliederverwaltung, alle Repositorys
Mitglied	Nur Zugriff auf Repositorys, weiter eingeschränkt durch die Berechtigungen pro Repository

Die eingeladene Person erhält eine E-Mail mit einem Link zum Annehmen. Bis sie annimmt, erscheint sie in der Mitgliederliste als Ausstehend und zählt nicht als abrechenbarer Nutzer.

Schritt 5: Dein erster CI-Workflow

Lege in deinem Repository eine Datei unter .forgejo/workflows/ci.yaml an. Forgejo Actions verwendet dasselbe YAML-Schema wie GitHub Actions:

on: [push, pull_request]

jobs:
  test:
    runs-on: fremforge
    steps:
      - uses: actions/checkout@v4
      - run: echo "Hello from fremforge CI"

Committe und pushe. Der Workflow startet sofort. Den Lauf verfolgst du unter:

frem.sh/<your-org>/<your-repo>/actions

Klicke auf den Lauf, um die Logs der einzelnen Schritte zu sehen. Der gehostete Runner fremforge wird in T Cloud Public ECS (eine kurzlebige VM pro Commit) in eu-de bereitgestellt. Dein Code verlässt die EU nicht.

Ein echtes Workflow-Beispiel

Ersetze das echo durch deine tatsächlichen Build- und Testbefehle:

on: [push, pull_request]

jobs:
  test:
    runs-on: fremforge
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: "20"

      - run: npm ci
      - run: npm test

Verfügbare Runner-Labels, enthaltene Werkzeuge und Grenzen für parallele Läufe findest du unter CI-Runner.

Schritt 6: Ein Secret hinzufügen

Secrets werden im Ruhezustand mit T Cloud Public DEW KMS verschlüsselt und als Umgebungsvariablen in Workflow-Jobs eingespeist. Die Werte von Secrets werden in Job-Logs maskiert.

Secret auf Organisationsebene (für alle Repositorys der Organisation verfügbar):

Gehe zu Organisationsverwaltung → Secrets → New secret (frem.sh/<your-org>/_admin/secrets).
Gib einen Namen ein (Großbuchstaben, nur Unterstriche, z. B. DEPLOY_API_KEY) und den Wert.
Speichere.

Secret auf Repository-Ebene (nur für ein Repository verfügbar):

Gehe zu Repository → Einstellungen → Geheimnisse → Geheimnis hinzufügen.
Gib Namen und Wert ein. Speichere.

So verwendest du es in deinem Workflow:

steps:
  - name: Deploy
    env:
      API_KEY: ${{ secrets.DEPLOY_API_KEY }}
    run: ./deploy.sh

Für Zugangsdaten von Cloud-Anbietern (AWS, T Cloud Public, GCP, Azure) ist die OIDC-Token-Föderation langlebigen Secrets vorzuziehen. Dann gibt es kein Secret zu speichern und keines zu rotieren.

Die vollständige Referenz, einschließlich Secrets für Umgebungen und der Vererbung von Secrets, findest du unter Secrets.

Schritt 7: Deinen IdP anbinden (optional, aber empfohlen)

Nutzt dein Team Okta, Entra ID, Google Workspace oder Authentik, richte SSO ein, damit sich Mitglieder mit ihrer Unternehmensidentität anmelden. SSO ist optional, für Teams mit mehr als zwei Personen aber dringend empfohlen.

OIDC-SSO (empfohlen):

Gehe zu Organisationsverwaltung → SSO → Auth-Quellen → Neue SSO-Quelle hinzufügen.
Wähle OIDC.
Gib die Discovery-URL, die Client-ID und das Client-Secret deines IdP ein.
Speichere und teste.

Ist SSO konfiguriert, erreichen Mitglieder die organisationsspezifische Anmeldung unter frem.sh/user/login?redirect_to=/<your-org> und authentifizieren sich über euren IdP – oder einfacher über die Discovery-Anmeldung unter frem.sh/_app/login, die sie anhand der E-Mail-Domain zu eurer Organisation leitet. Das vollständige Modell beschreibt So funktioniert die Anmeldung.

IdP	Anleitung
Okta	OIDC-SSO
Microsoft Entra ID	OIDC-SSO
Google Workspace	OIDC-SSO
ADFS	OIDC-SSO

Sobald SSO funktioniert, richte die SCIM-Provisionierung ein, um den Lebenszyklus der Benutzer zu automatisieren. Neue Mitarbeitende erhalten automatisch Zugang, und ausscheidende Mitarbeitende verlieren ihn in dem Moment, in dem ihr Konto im IdP deaktiviert wird.

Schritt 8: Von GitHub, GitLab oder Azure DevOps migrieren

Werkzeuge für die Migration sind bereits verfügbar – unter Migration findest du die Migrationsanleitungen für GitHub, GitLab und Azure DevOps, den eingebauten Importer und die Prüfung vor der Migration.

Hinweise zum Anpassen deiner bestehenden Workflows und eine Kompatibilitätsreferenz findest du in den Migrationsanleitungen.

Wie geht es weiter?

Sobald deine erste Pipeline grün ist:

Lieferkette absichern: Aktiviere Ausnahmen für Secret Scanning, SAST, Abhängigkeits-Scans und signierte Commits. Siehe Sicherheit und Lieferkette.
Branch-Schutz konfigurieren: Verlange vor dem Merge Reviews von Pull Requests und erfolgreiche CI. Einzustellen unter Repository → Einstellungen → Branches → <branch>.
Umgebungen einrichten: Nutze Deployment-Umgebungen, um Produktions-Deployments hinter eine manuelle Freigabe zu stellen. Zu konfigurieren unter Organisationsverwaltung → Umgebungen (https://frem.sh/<org>/_admin/environments).
Die Paket-Registry erkunden: Pushe Docker-Images, npm-Pakete oder Maven-Artefakte. Push-Endpunkt und Authentifizierung beschreibt die Dokumentation zur Paket-Registry.

Querverweise

Migrationsanleitungen – Schritt-für-Schritt-Import aus GitHub, GitLab und Azure DevOps
CI-Runner – Runner-Labels, enthaltene Werkzeuge, eigene Runner (BYO)
OIDC-SSO – Anmeldung mit Okta, Entra oder Google Workspace konfigurieren
Secrets – Secrets für Organisation, Repository und Umgebung
Organisationsverwaltung – die vollständige Referenz der Verwaltung