Skip to main content
Private preview. fremforge is in private preview — invited customers only. Content is still subject to change. Request access →
Reference
Troubleshooting

Troubleshooting

Common issues and their fixes. Each section links to the relevant reference page for deeper context.

Authentication and login

Password reset email not arriving

Check your spam folder. Password reset emails come from hello@frem.sh. If your org uses SSO, password reset is not the right path. Use the Sign in with <IdP> button on the login page instead. SSO accounts may not have a local password set.

SSO login fails with redirect_uri mismatch

The IdP rejected the callback because the redirect URI registered there doesn’t exactly match what fremforge sends. Copy the exact redirect URI from Org admin → SSO → <auth source> → Details and do not type it manually. A single trailing slash difference causes this error. See OIDC single sign-on or SAML 2.0 SSO.

SSH: Permission denied (publickey)

Three common causes:

  • The key has not been added to your fremforge account (User settings → SSH / GPG Keys → Add key).
  • The key file referenced by your SSH client belongs to a different user account.
  • The key format is unsupported (Ed25519, RSA 3072+, and ECDSA are supported; DSA keys are rejected).

Test your key: ssh -T -p 443 git@ssh.frem.sh, fremforge exposes SSH on port 443 via ssh.frem.sh (port 22 isn’t open). A successful auth returns Hi <username>! You've successfully authenticated.... See Getting started for key setup and Connecting for the ~/.ssh/config Host alias that lets you keep writing git@frem.sh in your remotes.

PAT expired / 401 on API calls

PATs expire after 90 days by default (max 365 days, configurable at creation). Check:

  1. The token is still listed under User settings → Applications.
  2. The token has the required scope, read:packages for registry pulls, api for REST calls, write:packages for publishing.
  3. The token value was copied correctly (it is shown only once at creation).

Generate a new token if in doubt.

CI / Runners

Job stuck in queue

The org has a concurrency cap of 2 jobs per seat (max 100/org). Check how many jobs are currently running at frem.sh/<org>/-/admin/runners. If all runner slots are occupied, jobs queue until a slot opens; runs queued above the cap are cancelled within seconds and reported in the audit log.

If the queue is empty but jobs are still stuck, the runner agent may be offline. Check runner status at Org admin → Runners.

actions/checkout fails: repository not found

The built-in FORGEJO_TOKEN needs contents: read permission. Add a permissions: block to the job or workflow:

permissions:
  contents: read

If the repository is private and the token is a PAT rather than the built-in token, verify the PAT has repo scope.

Secret is set but shows as empty in the job

The secret is set at the wrong scope. Secrets follow this precedence: environment secret → repo secret → org secret. If your job declares environment: production, only secrets set on that environment (and repo/org secrets not shadowed by it) are injected. Check that the secret is set at the scope that matches the job’s environment: declaration.

Docker: Cannot connect to the Docker daemon

fremforge runners run on T Cloud Cloud Container Instance (CCI) v2, which doesn’t permit privileged containers, Docker-in-Docker is therefore not available, and the docker CLI is not pre-installed. For container image builds, use the pre-installed kaniko:

jobs:
  build-image:
    runs-on: fremforge
    steps:
      - uses: actions/checkout@v4
      - run: |
          /usr/local/bin/kaniko \
            --context=$GITHUB_WORKSPACE \
            --dockerfile=Dockerfile \
            --destination=registry.example.com/$GITHUB_REPOSITORY:$GITHUB_SHA

For pure image copy/retag/push between registries, install skopeo in the step: apk add skopeo. See CI runners for available runner labels and docs.frem.sh/build/actions/runner-image/ for the full pre-installed tooling list.

Action not found: uses: some/action@v1

Most GitHub Marketplace actions work on fremforge (~95% compatibility). Actions that call github.com/api/v3 directly will fail because they target the GitHub API, not the fremforge API. Check Marketplace compatibility for the top-100 action compatibility matrix.

Git and repositories

Push rejected: secret detected

Gitleaks (pre-receive hook) blocked the push because a secret pattern was detected in the commit. The push was not accepted. The secret never reached the repository.

Steps to resolve:

  1. Rotate the secret immediately in the system that issued it, even if the push was rejected. Assume the value is compromised from the moment it appeared in your working tree.
  2. Remove the secret from your working tree and commit history using git filter-repo.
  3. Re-push the cleaned history.

See Security and supply chain for details on what patterns are detected.

Push rejected: branch protection

A branch protection rule is blocking the push. Check the rules under Repo Settings → Branches → <branch name>. Common causes: a required status check hasn’t passed, force-push is disabled, or the push requires a signed commit.

LFS: batch request failed

LFS must be enabled per-repo. Enable it under Repo Settings → Git LFS → Enable. If LFS is enabled and the error persists, check the org storage quota. LFS storage counts toward the 5 GB/seat LFS pool, which is separate from the 5 GB/seat package registry pool.

Webhooks

Webhook not firing

Check recent delivery attempts at Repo Settings → Webhooks → <webhook> → Recent deliveries. The most common cause is the payload URL being unreachable from fremforge’s T Cloud egress IPs. If deliveries show as failed, the response body typically includes the HTTP status returned by your endpoint. See Webhooks for egress IP ranges.

Webhook fires but payload is wrong

Verify which event types are subscribed. A push to a tag sends a push event, not a create event. Check the Events configuration on the webhook. See Webhooks for the full event vocabulary.

SSO / SCIM

SCIM user provisioned but cannot log in

Domain verification is required before SCIM-provisioned users can authenticate. Verify the email domain under Org admin → SSO → Verified domains. The domain in the user’s email address must appear there.

SAML: InResponseTo mismatch

Clock skew between the IdP and fremforge exceeds 5 minutes. The SAML response’s InResponseTo assertion is time-bounded; skew outside the tolerance causes validation failure. Synchronise NTP on your IdP server. See SAML 2.0 SSO.

Packages / Registry

npm: 403 Forbidden on publish

The PAT used by the CI job or local .npmrc does not have write:packages scope. Update the PAT at User settings → Applications, or add permissions: packages: write to the workflow job so the built-in token gets the right scope.

docker pull: unauthorized

The Docker credentials have expired or were never set for this machine. Re-authenticate:

docker login frem.sh -u <username> -p <PAT>

PATs do not auto-refresh. The Docker credential store keeps the value you provided at login time. If the PAT was revoked or expired, generate a new one and log in again.

Org slug and name availability

Org slugs must be 3-30 characters, lowercase, letters/digits/hyphens only, no leading or trailing hyphens.

If a slug shows as unavailable during signup: it is either registered by another org or on the reserved-names list. The reserved list covers common role names (admin, api, billing, support, status, security, abuse, root, system, fremforge, and similar) to prevent phishing or service-path collisions.

Trademark-adjacent names (e.g., slugs that closely resemble well-known brand names) enter a soft-review queue instead of being immediately blocked. If your signup is in the queue, you receive an email from support@frem.sh within one business day. In most cases, legitimate companies using their own brand name are approved without friction.

If your preferred slug is taken by an inactive or squatting org, contact support@frem.sh. Include the desired slug and your org’s domain or other ownership evidence. Slug transfers are handled case-by-case.

Changing your org slug after creation: Org admin → Settings → Rename organization. All existing repository URLs, clone URLs, and API calls using the old slug continue to redirect for 90 days. After 90 days the old slug becomes available for registration.

Cross-references