Web Services, Workers, and Cron Jobs
Services are the core building block. Each service runs a single process from your repository in an isolated Docker container.
Service Types
| Type | Tag | Description |
|---|---|---|
| Web Service | web | HTTP services with a public URL. Automatically gets a subdomain and TLS certificate. |
| Private Service | pserv | Internal services only accessible within your private network. No public URL. |
| Background Worker | worker | Long-running processes without HTTP endpoints. Queue consumers, data processors, etc. |
| Cron Job | cron | Scheduled tasks that run on a cron expression. Spins up, runs, and shuts down. |
| Static Site | static | Pre-rendered sites served via nginx with CDN-optimized caching headers. Build once, deploy instantly. |
Configuration
Each service has these core settings:
| Setting | Description | Default |
|---|---|---|
buildCommand | Build step (e.g., npm run build) | Auto-detected |
startCommand | Process entry point | Auto-detected |
port | HTTP port your app listens on | 10000 |
healthCheckPath | Endpoint for health checks | / |
plan | Resource size tier | s |
numInstances | Number of running instances | 1 |
autoDeploy | Auto-deploy on push | true |
GitHub Actions-Gated Deploys
By default, auto-deploy triggers on GitHub push webhooks. To gate deploys on GitHub Actions success, open Service → Settings → Build & Deploy and set Auto-Deploy to After GitHub Actions Success.
You can optionally add a comma-separated workflow allowlist in that panel. Leave it blank to allow any successful workflow_run on the tracked branch.
The active deploy automation mode is also visible on each service detail page so you can quickly confirm whether it is set to commit-based, workflow-gated, or manual-only deploys.
You can also switch modes directly from the service detail header using the Automation quick-action menu, and edit the workflow allowlist in both Service Detail and Service Settings with known workflow-name suggestions loaded from GitHub.
When services are created from GitHub repos, RailPush auto-registers webhook events for both push and workflow_run so workflow-gated deploys can trigger without extra manual webhook setup.
This webhook registration works for both HTTPS and SSH GitHub repository URL formats.
Service Detail now surfaces GitHub webhook health as Installed, Missing, or Permission denied, and provides a one-click Repair Webhook action when a fix can be applied automatically.
Workflow-name suggestions in Service Detail and Service Settings use service-scoped GitHub lookup so team members can still see suggestions even if their personal GitHub account is not connected.
RailPush also supports signed deploy event webhooks per service (foundation event system). You can subscribe to deploy.started, deploy.success, deploy.failed, and deploy.rollback.
For API or MCP automation, configure the same service env vars directly:
# Enable deploys from GitHub workflow_run success events
RAILPUSH_GITHUB_ACTIONS_AUTO_DEPLOY=true
# Optional: only allow specific workflow names (comma-separated)
RAILPUSH_GITHUB_ACTIONS_WORKFLOWS=CI, Release Build
# Enable deploy event webhooks for this service
RAILPUSH_EVENT_WEBHOOK_URL=https://example.com/webhooks/railpush
# Optional: HMAC SHA-256 signing secret (header: X-RailPush-Signature)
RAILPUSH_EVENT_WEBHOOK_SECRET=super-secret
# Optional: comma-separated events (defaults to all deploy events)
RAILPUSH_EVENT_WEBHOOK_EVENTS=deploy.started,deploy.success,deploy.failed
get_github_actions_deploy_gate(service_id)
set_deploy_automation_mode(service_id, mode, workflows?)
set_github_actions_deploy_workflows(service_id, workflows)
list_github_workflows(owner, repo)
list_service_github_workflows(service_id)
get_service_github_webhook_status(service_id)
repair_service_github_webhook(service_id)
get_service_event_webhook(service_id)
set_service_event_webhook(service_id, enabled, url?, events?, secret?)
test_service_event_webhook(service_id)
enable_github_actions_deploy_gate(service_id, workflows?)
disable_github_actions_deploy_gate(service_id)
For set_deploy_automation_mode(..., mode="workflow_success"), omitting workflows preserves the existing allowlist, while passing an empty list clears it.
Use set_github_actions_deploy_workflows to update allowlist names without changing deploy mode.
Use list_github_workflows to fetch exact workflow names before setting an allowlist.
Self-Hosted GitHub Actions Runners on RailPush
Need CI even when GitHub-hosted minutes are exhausted, or want builds to run inside your own infrastructure? Deploy a dedicated RailPush worker service using the recipe in recipes/github-actions-runner/.
The secure flow uses a RailPush API key inside the runner container. The runner calls POST /api/v1/services/:id/github/runner-token, and RailPush mints a short-lived GitHub registration or removal token from the workspace GitHub connection. The container never needs a long-lived GitHub PAT.
For the managed multi-tenant path, workspace admins can now link a GitHub App installation from Settings. RailPush stores the workspace-to-installation mapping, syncs accessible repositories, and uses installation-scoped auth as the foundation for managed runner pools. This keeps runner control separate from a human user's personal GitHub login.
Keep the runner private, single-instance, and dedicated to trusted repositories. Self-hosted runners execute repository code, so treat them like privileged build infrastructure.
RAILPUSH_NETWORK_VISIBILITY=internal
RAILPUSH_API_URL=http://railpush-control-plane.railpush.svc.cluster.local:8080/api/v1
RAILPUSH_API_KEY=<workspace-api-key>
GITHUB_REPOSITORY=owner/repo
RUNNER_LABELS=railpush,linux,x64
RUNNER_EPHEMERAL=true
{
"CI_RUNS_ON_JSON": "[\"self-hosted\",\"linux\",\"x64\",\"railpush\"]",
"DEPLOY_RUNS_ON_JSON": "[\"self-hosted\",\"linux\",\"x64\",\"railpush\"]"
}
Prerequisites: the workspace owner must have GitHub connected in RailPush with permission to manage self-hosted runners for the target repository. If the workflow variables above are unset, GitHub Actions falls back to ubuntu-latest.
Use list_service_github_workflows when you only know a service ID and want workflow names for its configured repo.
Use get_service_github_webhook_status to verify whether a service webhook is installed, missing, or permission denied.
Use repair_service_github_webhook to re-create or update webhook events when status is missing.
Use set_service_event_webhook and test_service_event_webhook to configure and validate deploy event notifications.