Troubleshooting

Something not working? Here are the most common issues and how to fix them.

DNS Not Propagating

Symptom: Your domain doesn't resolve to your ship after configuring DNS.

Check your DNS records

# Check A record
dig +short yourdomain.com

# Check www
dig +short www.yourdomain.com

# Check preview wildcard
dig +short test.preview.yourdomain.com

Common fixes

• Wait longer — DNS propagation can take up to 48 hours, though usually 5-30 minutes. Check with whatsmydns.net
• Check for typos — Ensure the IP address matches exactly what's shown in your ship dashboard
• Flush local DNS — Your computer may have cached the old records
• Cloudflare proxy — If using Cloudflare, set DNS records to "DNS only" (grey cloud) initially. You can enable the proxy later once everything works
• Conflicting records — Remove any existing A or AAAA records for the same subdomain before adding new ones

# Flush DNS cache
# macOS
sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder

# Linux
sudo systemd-resolve --flush-caches

Build Failures

Symptom: Deployment fails during the build step in GitHub Actions.

Check the build logs

Go to your repository's Actions tab on GitHub and find the failed workflow run. The logs will show exactly what went wrong.

Common causes

• Test failures — CI runs your test suite before deploying. Fix the failing tests and push again.

  # Run tests locally first
  bin/rails test

• Missing dependencies — If you added a gem or npm package, make sure Gemfile.lock or package-lock.json is committed.
• Asset compilation errors — CSS or JavaScript build errors. Run bin/rails assets:precompile locally to debug.
• Docker build issues — Check that your Dockerfile hasn't been modified in a way that breaks the build. The Omaship-managed Dockerfile should work out of the box.

SSL Certificate Issues

Symptom: Browser shows "Not Secure" or certificate warnings.

Common fixes

• DNS not ready yet — SSL certificates can only be issued once DNS is correctly pointing to your server. Verify DNS first (see above).
• Wait for the latest run — Let's Encrypt certificates are issued automatically once DNS resolves. This can take a few minutes after DNS propagates.
• Rate limits — Let's Encrypt has rate limits. If you've been testing with many domain changes, you may need to wait up to an hour.
• Wildcard for previews — Preview subdomain SSL uses the same Traefik certificate automation. Ensure the wildcard CNAME record is set.

Preview Deployments Not Working

Symptom: PR previews don't deploy or the preview URL doesn't load.

Checklist

• Wildcard DNS — You need a CNAME record for *.preview pointing to your domain:

  CNAME *.preview → yourdomain.com

• Feature enabled — Check that preview deployments are enabled in Settings → Features
• GitHub Actions permissions — The Omaship GitHub App needs write access to deploy previews (see below)
• PR from fork — Preview deployments only work for PRs from branches in the same repository, not from forks (security restriction)

GitHub App Permissions

Symptom: Deployments fail with permission errors, or the GitHub App can't create repositories.

Required permissions

The Omaship GitHub App needs these permissions to function:

• Repository access — Read & write on repositories (for creating repos and managing code)
• Actions — Read & write (for triggering and managing CI/CD workflows)
• Secrets — Read & write (for managing deployment secrets)
• Pull requests — Read & write (for preview deployment comments)
• Webhooks — Read (for receiving push and PR events)

Fixing permission issues

1. Go to GitHub → Settings → Applications → Omaship
2. Click "Configure"
3. Ensure the app has access to the correct repositories (or "All repositories")
4. Review and accept any pending permission requests

Still Stuck?

If none of the above solves your issue:

• Check the Omaship status page for any ongoing incidents
• Reach out via the in-app chat widget
• Email [email protected] with your ship name and a description of the issue