Getting started

This guide takes you from signup to a working CI pipeline. It assumes you have a terminal open with git installed.

Buying or admin’ing fremforge rather than coding on it? Your first hour with fremforge walks through signup, SSO, payment, and break-glass setup in plain language with a flow diagram. Read that one first if you’re the org owner; come back here when you’re ready to push code.

Step 1, Sign up

1. Visit www.frem.sh and click Sign up in the top nav (or go directly to frem.sh/_app/signup). Fill in your work email, org slug (e.g. acme, 3-30 characters), and display name.
2. Check your inbox for a verification email from noreply@frem.sh. Click the Verify email link. It is valid for 24 hours.
3. On the confirmation page, set your password and click Create org.

Your org is immediately available at https://frem.sh/<your-org>.

Step 2, Set up Git Credential Manager (HTTPS + MFA)

fremforge’s recommended sign-in path is HTTPS + Git Credential Manager (GCM) — interactive sign-in through your org’s IdP with MFA fired on every token refresh. New orgs default to SSH disabled; HTTPS+GCM is the path.

1. Install 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. Configure GCM for fremforge (once per workstation):

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

The client ID is Forgejo’s built-in git-credential-manager app — no per-org setup needed.

For the full setup including MFA flow details, fallback paths (PAT for CI, SSH for orgs that have re-enabled it), and platform-specific notes, see the Secure sign-in guide.

Step 3, Create your first repository

From the UI: go to frem.sh/<your-org> → + New repository. Fill in the repository name, set visibility (public or private), optionally initialize with a README, and click Create repository.

Push an existing local repo (HTTPS, recommended):

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.

If your org admin has re-enabled SSH and you prefer it, the SSH equivalent works too — see Connecting.

If the repository does not exist yet, fremforge creates it automatically on the first push if you have the Create repositories permission (granted to all org owners by default).

Step 4, Invite team members

Team membership lives in Forgejo’s native org-teams UI. fremforge doesn’t duplicate the role editor.

1. Go to https://frem.sh/<your-org>/-/teams and pick the team to invite into (or New team to create one).
2. Enter the invitee’s email address (or their fremforge username once they have an account).
3. Select a role:

The invitee receives an email with an accept link. Until they accept, they appear as Pending in the member list and do not count as a billable seat.

Step 5, Your first CI workflow

Create a file at .forgejo/workflows/ci.yaml in your repository. Forgejo Actions uses the same YAML schema as GitHub Actions:

on: [push, pull_request]

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

Commit and push. The workflow triggers immediately. Watch the run at:

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

Click the run to see per-step logs. The hosted fremforge runner is provisioned on T Cloud CCI in eu-de. Your code does not leave the EU.

A real workflow example

Replace the echo with your actual build and test commands:

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

See CI runners for available runner labels, included tools, and concurrency limits.

Step 6, Add a secret

Secrets are encrypted at rest with T Cloud DEW KMS and injected into workflow jobs as environment variables. Secret values are masked in job logs.

Org-scoped secret (available to all repositories in the org):

1. Go to Org admin → Secrets → New secret (frem.sh/<your-org>/_admin/secrets).
2. Enter a name (uppercase, underscores only, e.g. DEPLOY_API_KEY) and the value.
3. Save.

Repo-scoped secret (available to one repository only):

1. Go to Repository → Settings → Secrets → New secret.
2. Enter name and value. Save.

Reference in your workflow:

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

For cloud provider credentials (AWS, T Cloud, GCP, Azure), prefer OIDC token federation over long-lived secrets. There is no secret to store and no secret to rotate.

See Secrets for the full reference including environment-scoped secrets and secret inheritance.

Step 7, Connect your IdP (optional but recommended)

If your team uses Okta, Entra ID, Google Workspace, or Authentik, set up SSO so members sign in with their corporate identity. SSO is optional but strongly recommended for teams larger than two people.

OIDC SSO (recommended):

1. Go to Org admin → SSO → Auth sources → New auth source.
2. Select OIDC.
3. Enter your IdP’s discovery URL, client ID, and client secret.
4. Save and test.

After SSO is configured, members reach the org-specific login at frem.sh/user/login?redirect_to=/<your-org> and authenticate via your IdP.

After SSO is working, set up SCIM provisioning to automate user lifecycle. New hires get access automatically, and offboarded employees are deprovisioned the moment their IdP account is deactivated.

Step 8, Migrate from GitHub, GitLab, or Azure DevOps

Migration tooling is available from Phase 1. Until then, you can migrate manually by pushing existing repositories to fremforge using git push and recreating any CI workflows.

For guidance on adapting your existing workflows and a compatibility reference, see the migration guides.

What’s next

Once your first pipeline is green:

• Harden the supply chain, enable secret scanning overrides, SAST, dependency scanning, and signed commits. See Security and supply chain.
• Configure branch protection, require PR reviews and passing CI before merge. Set at Repository → Settings → Branches → <branch>.
• Set up environments, use deployment environments to gate production deploys behind manual approval. Configure at Repository → Settings → Environments.
• Explore the package registry, push Docker images, npm packages, or Maven artifacts. See the Package registry docs for the push endpoint and authentication.

Cross-references

• Migration guides, step-by-step import from GitHub, GitLab, and Azure DevOps
• CI runners, runner labels, included tools, BYO runners
• OIDC SSO, configure Okta, Entra, or Google Workspace sign-in
• Secrets, org, repo, and environment secrets
• Org admin, the full admin surface reference