Aan de slag

Deze handleiding brengt je van registratie tot een werkende CI-pipeline. We gaan ervan uit dat je een terminal open hebt met git geïnstalleerd.

Ga je fremforge kopen of beheren in plaats van erop te programmeren? Je eerste uur met fremforge loopt in begrijpelijke taal en met een stroomschema door registratie, SSO, betaling en de break-glass-inrichting. Lees die pagina eerst als je eigenaar van de organisatie bent, en kom hier terug zodra je klaar bent om code te pushen.

Stap 1: Registreren

1. Ga naar www.frem.sh en klik op Sign up in de bovenste navigatie (of ga direct naar frem.sh/_app/signup). Vul je zakelijke e-mailadres, de slug van je organisatie (bijv. acme, 3-30 tekens) en een weergavenaam in.
2. Kijk in je inbox voor een verificatiemail van noreply@frem.sh. Klik op de link Aanmelding bevestigen. Die is 24 uur geldig.
3. Kies op de bevestigingspagina je wachtwoord en klik op Organisatie aanmaken.

Je organisatie is direct bereikbaar op https://frem.sh/<your-org>.

Stap 2: Git Credential Manager instellen (HTTPS + MFA)

De aanbevolen manier om bij fremforge in te loggen is HTTPS + Git Credential Manager (GCM): interactief inloggen via de IdP van je organisatie, waarbij MFA bij elke tokenvernieuwing wordt gevraagd. Bij nieuwe organisaties staat SSH standaard uit; HTTPS+GCM is de weg.

1. Installeer GCM:

# 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+

2. Configureer GCM voor fremforge (eenmalig per werkstation):

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

De client-ID is de ingebouwde git-credential-manager-app van Forgejo; je hoeft per organisatie niets in te stellen.

De volledige inrichting, met details over de MFA-stroom, alternatieven (PAT voor CI, SSH voor organisaties die het weer hebben aangezet) en aanwijzingen per platform, vind je in de handleiding voor veilig inloggen.

Stap 3: Je eerste repository aanmaken

Via de interface: ga naar frem.sh/<your-org> → + Nieuwe repository. Vul de naam van de repository in, kies de zichtbaarheid (openbaar of privé), initialiseer eventueel met een README en klik op Nieuwe repository.

Een bestaande lokale repository pushen (HTTPS, aanbevolen):

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.

Heeft de beheerder van je organisatie SSH weer aangezet en werk je daar liever mee, dan werkt de SSH-variant ook; zie Verbinding maken.

Bestaat de repository nog niet, dan maakt fremforge hem bij de eerste push automatisch aan, mits je het recht Maak repositories hebt (dat alle eigenaren van de organisatie standaard hebben).

Stap 4: Teamleden uitnodigen

Teamlidmaatschap regel je in de eigen teaminterface van Forgejo. fremforge heeft geen kopie van de rollen-editor.

1. Ga naar https://frem.sh/org/<your-org>/teams en kies het team waarvoor je iemand wilt uitnodigen (of Nieuw team om er een aan te maken).
2. Vul het e-mailadres van de genodigde in (of diens fremforge-gebruikersnaam, zodra die een account heeft).
3. Kies een rol:

De genodigde krijgt een e-mail met een link om de uitnodiging te accepteren. Tot die tijd staat de persoon als In behandeling in de ledenlijst en telt hij niet mee als betalende gebruiker.

Stap 5: Je eerste CI-workflow

Maak in je repository een bestand .forgejo/workflows/ci.yaml aan. Forgejo Actions gebruikt hetzelfde YAML-schema als GitHub Actions:

on: [push, pull_request]

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

Commit en push. De workflow start meteen. Volg de run op:

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

Klik op de run om de logs per stap te zien. De gehoste fremforge-runner draait op T Cloud Public ECS (een tijdelijke VM per commit) in eu-de. Je code verlaat de EU niet.

Een echt workflowvoorbeeld

Vervang de echo door je eigen build- en testcommando’s:

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

Zie CI-runners voor de beschikbare runner-labels, de meegeleverde tools en de limieten voor gelijktijdige jobs.

Stap 6: Een secret toevoegen

Secrets worden at rest versleuteld met T Cloud Public DEW KMS en als omgevingsvariabelen in workflowjobs geïnjecteerd. Waarden van secrets worden in joblogs gemaskeerd.

Secret op organisatieniveau (beschikbaar voor alle repository’s in de organisatie):

1. Ga naar Organisatiebeheer → Secrets → New secret (frem.sh/<your-org>/_admin/secrets).
2. Vul een naam in (hoofdletters en underscores, bijv. DEPLOY_API_KEY) en de waarde.
3. Sla op.

Secret op repositoryniveau (alleen beschikbaar voor één repository):

1. Ga naar Repository → Instellingen → Geheimen → Geheim toevoegen.
2. Vul naam en waarde in. Sla op.

Gebruik het in je workflow:

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

Gebruik voor inloggegevens van cloudproviders (AWS, T Cloud Public, GCP, Azure) bij voorkeur OIDC-tokenfederatie in plaats van langlevende secrets. Dan is er geen secret om op te slaan en geen secret om te roteren.

Zie Secrets voor de volledige referentie, inclusief secrets per omgeving en overerving van secrets.

Stap 7: Je IdP koppelen (optioneel, maar aanbevolen)

Gebruikt je team Okta, Entra ID, Google Workspace of Authentik, stel dan SSO in, zodat leden met hun zakelijke identiteit inloggen. SSO is optioneel, maar sterk aanbevolen voor teams van meer dan twee personen.

OIDC-SSO (aanbevolen):

1. Ga naar Organisatiebeheer → SSO → Auth-bronnen → New auth source.
2. Kies OIDC.
3. Vul de discovery-URL, de client-ID en het client-secret van je IdP in.
4. Sla op en test.

Zodra SSO is ingericht, komen leden via frem.sh/user/login?redirect_to=/<your-org> op de inlogpagina van de organisatie en authenticeren ze via je IdP. Eenvoudiger is de discovery-inlog op frem.sh/_app/login, die hen op basis van het e-maildomein naar je organisatie stuurt. Zie Zo werkt inloggen voor het volledige model.

Werkt SSO eenmaal, stel dan SCIM-provisioning in om de levenscyclus van gebruikers te automatiseren. Nieuwe medewerkers krijgen automatisch toegang, en vertrekkende medewerkers verliezen hun toegang op het moment dat hun IdP-account wordt gedeactiveerd.

Stap 8: Migreren vanaf GitHub, GitLab of Azure DevOps

De migratietools zijn er al: zie Migratie voor de handleidingen voor GitHub, GitLab en Azure DevOps, de ingebouwde importer en de controle vóór migratie.

Voor hulp bij het aanpassen van je bestaande workflows en een compatibiliteitsreferentie, zie de migratiehandleidingen.

Wat nu?

Zodra je eerste pipeline groen is:

• Versterk de toeleveringsketen: schakel secret-scanning-overrides, SAST, dependency-scanning en ondertekende commits in. Zie Beveiliging en toeleveringsketen.
• Stel branchbescherming in: eis reviews van pull requests en geslaagde CI vóór een merge. In te stellen onder Repository → Instellingen → Branches → <branch>.
• Richt omgevingen in: gebruik deployment-omgevingen om productiedeploys achter een handmatige goedkeuring te zetten. In te stellen onder Organisatiebeheer → Omgevingen (https://frem.sh/<org>/_admin/environments).
• Verken het pakketregister: push Docker-images, npm-pakketten of Maven-artefacten. Zie de documentatie van het pakketregister voor het push-endpoint en de authenticatie.

Zie ook

• Migratiehandleidingen: stapsgewijze import vanaf GitHub, GitLab en Azure DevOps
• CI-runners: runner-labels, meegeleverde tools, eigen runners
• OIDC-SSO: inloggen via Okta, Entra of Google Workspace instellen
• Secrets: secrets op organisatie-, repository- en omgevingsniveau
• Organisatiebeheer: de volledige referentie van de beheeromgeving