ADR-001: Preview Environments via Railway Native PR Environments

Status

Accepted

Context

We need preview deployments for pull requests so reviewers can test changes before merging. As an open-source project, we also need to handle PRs from external contributors (forks) safely.

Options Considered

1. Custom GitHub Actions workflow - Build our own preview deployment workflow using Railway CLI
2. Railway's native PR environments - Use Railway's built-in GitHub integration

Key Constraints

• Fork security: GitHub Actions workflows triggered by fork PRs cannot access repository secrets (by design). This makes custom workflows problematic for OSS.
• Code review before deploy: We don't want arbitrary code from unknown contributors deployed automatically.
• Simplicity: Less custom infrastructure means less maintenance burden.

Decision

Use Railway's native PR environments feature.

How It Works

1. Enable in Railway Dashboard: Project Settings → Environments → Enable PR Environments
2. Connect GitHub repo: Railway's GitHub App handles authentication
3. Automatic for team members: PRs from team members get auto-deployed
4. Gated for external contributors: PRs from forks are NOT auto-deployed (security feature)

For External Contributors

Railway only deploys PRs from users who are team members or invited to the project. This is intentional - it prevents:

• Arbitrary code execution from untrusted sources
• Secret/environment variable exposure
• Resource abuse

Workflow for external contributor PRs:

1. Contributor opens PR from fork
2. CI runs (tests, lint, build) via GitHub Actions
3. Maintainer reviews code
4. To preview: maintainer can either
   • Temporarily invite contributor to Railway project
   • Checkout branch locally and deploy manually
   • Merge to a preview branch that triggers deployment
5. Once approved, merge to main

This "review before deploy" pattern is the standard for OSS projects and is more secure than auto-deploying fork code.

Consequences

Positive

• Zero custom workflow maintenance
• Built-in security model for fork PRs
• Automatic cleanup when PRs close
• Railway handles domain provisioning
• Works with Railway's existing GitHub integration

Negative

• Less flexibility than custom workflow
• External contributor previews require manual intervention
• Dependent on Railway's feature set

Neutral

• Team members must have Railway project access for auto-deploys
• PR environment URLs follow Railway's naming convention

Setup Instructions

1. Add a Railway domain to the production service

PR environments only get auto-provisioned domains if the base (production) environment has a Railway-provided domain.

1. Go to Railway Dashboard → Toast project
2. Select the api service in the production environment
3. Go to Settings → Networking → Public Networking
4. Click "Generate Domain" to get a *.up.railway.app domain

2. Enable PR Environments

1. Go to Project Settings → Environments tab
2. Toggle "Enable PR Environments"
3. Optionally toggle "Enable Bot PR Environments" for Dependabot/Renovate

3. Verify GitHub Integration

Railway creates GitHub Deployments for each deploy. The deployment URL will appear in:

• PR sidebar: "Deployments" section shows environment with "View deployment" link
• Commit status: Checkmark links to Railway dashboard
• GitHub Deployments API: environment_url field contains the live URL

No PR comment is posted, but the URL is accessible via the GitHub Deployments UI.

References

• Railway Environments Guide
• GitHub Actions fork security