Environment Configuration

Query, stage, and apply configuration changes for Railway environments.

Shell Escaping

CRITICAL: When running GraphQL queries via bash, you MUST wrap in heredoc to prevent shell escaping issues:

1bash <<'SCRIPT'
2${CLAUDE_PLUGIN_ROOT}/skills/lib/railway-api.sh 'query ...' '{"var": "value"}'
3SCRIPT

Without the heredoc wrapper, multi-line commands break and exclamation marks in GraphQL non-null types get escaped, causing query failures.

When to Use

• User wants to create a new environment
• User wants to duplicate an environment (e.g., “copy production to staging”)
• User wants to switch to a different environment
• User asks about current build/deploy settings, variables, replicas, health checks, domains
• User asks to change service source (Docker image, branch, commit, root directory)
• User wants to connect a service to a GitHub repo
• User wants to deploy from a GitHub repo (create empty service first via railway-new skill, then use this)
• User asks to change build or start command
• User wants to add/update/delete environment variables
• User wants to change replica count or configure health checks
• User asks to delete a service, volume, or bucket
• User says “apply changes”, “commit changes”, “deploy changes”
• Auto-fixing build errors detected in logs

Create Environment

Create a new environment in the linked project:

1railway environment new <name>

Duplicate an existing environment:

1railway environment new staging --duplicate production

With service-specific variables:

1railway environment new staging --duplicate production --service-variable api PORT=3001

Switch Environment

Link a different environment to the current directory:

1railway environment <name>

Or by ID:

1railway environment <environment-id>

Get Context

1railway status --json

Extract:

• project.id - for service lookup
• environment.id - for the mutations
• service.id - default service if user doesn’t specify one

Resolve Service ID

If user specifies a service by name, query project services:

 1query projectServices($projectId: String!) {
 2  project(id: $projectId) {
 3    services {
 4      edges {
 5        node {
 6          id
 7          name
 8        }
 9      }
10    }
11  }
12}

Match the service name (case-insensitive) to get the service ID.

Query Configuration

Fetch current environment configuration and staged changes.

 1query environmentConfig($environmentId: String!) {
 2  environment(id: $environmentId) {
 3    id
 4    config(decryptVariables: false)
 5    serviceInstances {
 6      edges {
 7        node {
 8          id
 9          serviceId
10        }
11      }
12    }
13  }
14  environmentStagedChanges(environmentId: $environmentId) {
15    id
16    patch(decryptVariables: false)
17  }
18}

Example:

1bash <<'SCRIPT'
2${CLAUDE_PLUGIN_ROOT}/skills/lib/railway-api.sh \
3  'query envConfig($envId: String!) {
4    environment(id: $envId) { id config(decryptVariables: false) }
5    environmentStagedChanges(environmentId: $envId) { id patch(decryptVariables: false) }
6  }' \
7  '{"envId": "ENV_ID"}'
8SCRIPT

Response Structure

The config field contains current configuration:

 1{
 2  "services": {
 3    "<serviceId>": {
 4      "source": { "repo": "...", "branch": "main" },
 5      "build": { "buildCommand": "npm run build", "builder": "NIXPACKS" },
 6      "deploy": {
 7        "startCommand": "npm start",
 8        "multiRegionConfig": { "us-west2": { "numReplicas": 1 } }
 9      },
10      "variables": { "NODE_ENV": { "value": "production" } },
11      "networking": { "serviceDomains": {}, "customDomains": {} }
12    }
13  },
14  "sharedVariables": { "DATABASE_URL": { "value": "..." } }
15}

The patch field in environmentStagedChanges contains pending changes. The effective configuration is the base config merged with the staged patch.

For complete field reference, see reference/environment-config.md.

For variable syntax and service wiring patterns, see reference/variables.md.

Get Rendered Variables

The GraphQL queries above return unrendered variables - template syntax like ${{shared.DOMAIN}} is preserved. This is correct for management/editing.

To see rendered (resolved) values as they appear at runtime:

1# Current linked service
2railway variables --json
3
4# Specific service
5railway variables --service <service-name> --json

When to use:

• Debugging connection issues (see actual URLs/ports)
• Verifying variable resolution is correct
• Viewing Railway-injected values (RAILWAY_*)

Stage Changes

Stage configuration changes via the environmentStageChanges mutation. Use merge: true to automatically merge with existing staged changes.

 1mutation stageEnvironmentChanges(
 2  $environmentId: String!
 3  $input: EnvironmentConfig!
 4  $merge: Boolean
 5) {
 6  environmentStageChanges(
 7    environmentId: $environmentId
 8    input: $input
 9    merge: $merge
10  ) {
11    id
12  }
13}

Important: Always use variables (not inline input) because service IDs are UUIDs which can’t be used as unquoted GraphQL object keys.

Example:

1bash <<'SCRIPT'
2${CLAUDE_PLUGIN_ROOT}/skills/lib/railway-api.sh \
3  'mutation stageChanges($environmentId: String!, $input: EnvironmentConfig!, $merge: Boolean) {
4    environmentStageChanges(environmentId: $environmentId, input: $input, merge: $merge) { id }
5  }' \
6  '{"environmentId": "ENV_ID", "input": {"services": {"SERVICE_ID": {"build": {"buildCommand": "npm run build"}}}}, "merge": true}'
7SCRIPT

Delete Service

Use isDeleted: true:

1bash <<'SCRIPT'
2${CLAUDE_PLUGIN_ROOT}/skills/lib/railway-api.sh \
3  'mutation stageChanges($environmentId: String!, $input: EnvironmentConfig!, $merge: Boolean) {
4    environmentStageChanges(environmentId: $environmentId, input: $input, merge: $merge) { id }
5  }' \
6  '{"environmentId": "ENV_ID", "input": {"services": {"SERVICE_ID": {"isDeleted": true}}}, "merge": true}'
7SCRIPT

Stage and Apply Immediately

For single changes that should deploy right away, use environmentPatchCommit to stage and apply in one call.

 1mutation environmentPatchCommit(
 2  $environmentId: String!
 3  $patch: EnvironmentConfig
 4  $commitMessage: String
 5) {
 6  environmentPatchCommit(
 7    environmentId: $environmentId
 8    patch: $patch
 9    commitMessage: $commitMessage
10  )
11}

Example:

1bash <<'SCRIPT'
2${CLAUDE_PLUGIN_ROOT}/skills/lib/railway-api.sh \
3  'mutation patchCommit($environmentId: String!, $patch: EnvironmentConfig, $commitMessage: String) {
4    environmentPatchCommit(environmentId: $environmentId, patch: $patch, commitMessage: $commitMessage)
5  }' \
6  '{"environmentId": "ENV_ID", "patch": {"services": {"SERVICE_ID": {"variables": {"API_KEY": {"value": "secret"}}}}}, "commitMessage": "add API_KEY"}'
7SCRIPT

When to use: Single change, no need to batch, user wants immediate deployment.

When NOT to use: Multiple related changes to batch, or user says “stage only” / “don’t deploy yet”.

Apply Staged Changes

Commit staged changes and trigger deployments.

Note: There is no railway apply CLI command. Use the mutation below or direct users to the web UI.

Apply Mutation

Mutation name: environmentPatchCommitStaged

 1mutation environmentPatchCommitStaged(
 2  $environmentId: String!
 3  $message: String
 4  $skipDeploys: Boolean
 5) {
 6  environmentPatchCommitStaged(
 7    environmentId: $environmentId
 8    commitMessage: $message
 9    skipDeploys: $skipDeploys
10  )
11}

Example:

1bash <<'SCRIPT'
2${CLAUDE_PLUGIN_ROOT}/skills/lib/railway-api.sh \
3  'mutation commitStaged($environmentId: String!, $message: String) {
4    environmentPatchCommitStaged(environmentId: $environmentId, commitMessage: $message)
5  }' \
6  '{"environmentId": "ENV_ID", "message": "add API_KEY variable"}'
7SCRIPT

Parameters

Commit Message

Keep very short - one sentence max. Examples:

• “set build command to fix npm error”
• “add API_KEY variable”
• “increase replicas to 3”

Leave empty if no meaningful description.

Default Behavior

Always deploy unless user explicitly asks to skip. Only set skipDeploys: true if user says “apply without deploying”, “commit but don’t deploy”, or “skip deploys”.

Returns a workflow ID (string) on success.

Auto-Apply Behavior

By default, apply changes immediately.

Flow

Single change: Use environmentPatchCommit to stage and apply in one call.

Multiple changes or batching: Use environmentStageChanges with merge: true for each change, then environmentPatchCommitStaged to apply.

When NOT to Auto-Apply

• User explicitly says “stage only”, “don’t deploy yet”, or similar
• User is making multiple related changes that should deploy together

When you don’t auto-apply, tell the user:

Changes staged. Apply them at: https://railway.com/project/{projectId} Or ask me to apply them.

Get projectId from railway status --json → project.id

Error Handling

Service Not Found

Service "foo" not found in project. Available services: api, web, worker

No Staged Changes

No patch to apply

There are no staged changes to commit. Stage changes first.

Invalid Configuration

Common issues:

• buildCommand and startCommand cannot be identical
• buildCommand only valid with NIXPACKS builder
• dockerfilePath only valid with DOCKERFILE builder

No Permission

You don't have permission to modify this environment. Check your Railway role.

No Linked Project

No project linked. Run `railway link` to link a project.

Composability

• Create service: Use railway-service skill
• View logs: Use railway-deployment skill
• Add domains: Use railway-domain skill
• Deploy local code: Use railway-deploy skill