railway-environment

環境設定

Railway環境の設定変更を照会、ステージング、適用します。

シェルのエスケープ

重要: bashでGraphQLクエリを実行する場合は、シェルのエスケープ問題を防ぐために必ずheredocで囲んでください:

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

heredocで囲まないと、複数行のコマンドが壊れ、GraphQLのNon-null型の感嘆符がエスケープされてしまい、クエリが失敗します。

使用するタイミング

• ユーザーが新しい環境を作成したい場合
• ユーザーが環境を複製したい場合（例: 「productionをstagingにコピー」）
• ユーザーが別の環境に切り替えたい場合
• ユーザーが現在のビルド/デプロイ設定、変数、レプリカ、ヘルスチェック、ドメインについて尋ねる場合
• ユーザーがサービスのソース（Dockerイメージ、ブランチ、コミット、ルートディレクトリ）を変更したい場合
• ユーザーがサービスをGitHubリポジトリに接続したい場合
• ユーザーがGitHubリポジトリからデプロイしたい場合（先にrailway-newスキルで空のサービスを作成してから、このスキルを使用します）
• ユーザーがビルドコマンドまたは開始コマンドを変更したい場合
• ユーザーが環境変数を追加/更新/削除したい場合
• ユーザーがレプリカ数の変更やヘルスチェックの設定をしたい場合
• ユーザーがサービス、ボリューム、またはバケットの削除を求めている場合
• ユーザーが「変更を適用」「変更をコミット」「変更をデプロイ」と言う場合
• ログで検出されたビルドエラーを自動修正する場合

環境の作成

リンク済みプロジェクトに新しい環境を作成します:

railway environment new <name>

既存の環境を複製します:

railway environment new staging --duplicate production

サービス固有の変数を指定する場合:

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

環境の切り替え

現在のディレクトリに別の環境をリンクします:

railway environment <name>

またはIDで指定します:

railway environment <environment-id>

コンテキストの取得

railway status --json

以下の値を抽出します:

• project.id - サービス検索用
• environment.id - ミューテーション用
• service.id - ユーザーがサービスを指定しない場合のデフォルトのサービス

サービスIDの解決

ユーザーがサービスを名前で指定した場合は、プロジェクトのサービスを照会します:

query projectServices($projectId: String!) {
  project(id: $projectId) {
    services {
      edges {
        node {
          id
          name
        }
      }
    }
  }
}

サービス名を（大文字と小文字を区別せずに）照合し、サービスIDを取得します。

設定の照会

現在の環境設定とステージング済みの変更を取得します。

query environmentConfig($environmentId: String!) {
  environment(id: $environmentId) {
    id
    config(decryptVariables: false)
    serviceInstances {
      edges {
        node {
          id
          serviceId
        }
      }
    }
  }
  environmentStagedChanges(environmentId: $environmentId) {
    id
    patch(decryptVariables: false)
  }
}

例:

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

レスポンスの構造

configフィールドには現在の設定が含まれます:

{
  "services": {
    "<serviceId>": {
      "source": { "repo": "...", "branch": "main" },
      "build": { "buildCommand": "npm run build", "builder": "NIXPACKS" },
      "deploy": {
        "startCommand": "npm start",
        "multiRegionConfig": { "us-west2": { "numReplicas": 1 } }
      },
      "variables": { "NODE_ENV": { "value": "production" } },
      "networking": { "serviceDomains": {}, "customDomains": {} }
    }
  },
  "sharedVariables": { "DATABASE_URL": { "value": "..." } }
}

environmentStagedChangesのpatchフィールドには保留中の変更が含まれます。有効な設定は、ベースのconfigにステージング済みのpatchをマージしたものです。

フィールドの完全なリファレンスについては、reference/environment-config.mdを参照してください。

変数の構文とサービス接続パターンについては、reference/variables.mdを参照してください。

レンダリング済み変数の取得

上記のGraphQLクエリは、レンダリング前の変数を返します。${{shared.DOMAIN}}のようなテンプレート構文はそのまま保持されます。これは管理・編集の目的では正しい動作です。

実行時に表示されるレンダリング済み（解決後）の値を確認するには:

# Current linked service
railway variables --json

# Specific service
railway variables --service <service-name> --json

使用するタイミング:

• 接続の問題をデバッグする場合（実際のURLやポートを確認する）
• 変数の解決が正しいか確認する場合
• Railwayが注入した値（RAILWAY_*）を確認する場合

変更のステージング

environmentStageChangesミューテーションで設定変更をステージングします。merge: trueを使用すると、既存のステージング済み変更と自動的にマージされます。

mutation stageEnvironmentChanges(
  $environmentId: String!
  $input: EnvironmentConfig!
  $merge: Boolean
) {
  environmentStageChanges(
    environmentId: $environmentId
    input: $input
    merge: $merge
  ) {
    id
  }
}

重要: サービスIDはUUIDであり、引用符で囲まれていないGraphQLのオブジェクトキーとして使用できないため、必ずインライン入力ではなく変数を使用してください。

例:

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

サービスの削除

isDeleted: trueを使用します:

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

ステージングと即時適用

すぐにデプロイすべき単一の変更には、environmentPatchCommitを使用して、1回の呼び出しでステージングと適用を行います。

mutation environmentPatchCommit(
  $environmentId: String!
  $patch: EnvironmentConfig
  $commitMessage: String
) {
  environmentPatchCommit(
    environmentId: $environmentId
    patch: $patch
    commitMessage: $commitMessage
  )
}

例:

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

使用するタイミング: 単一の変更で、まとめる必要がなく、ユーザーが即時デプロイを望む場合。

使用しないタイミング: まとめるべき関連する複数の変更がある場合、またはユーザーが「ステージングのみ」「まだデプロイしない」と言う場合。

ステージング済みの変更の適用

ステージング済みの変更をコミットし、デプロイをトリガーします。

注意: railway applyというCLIコマンドはありません。以下のミューテーションを使用するか、ユーザーをWeb UIに案内してください。

適用ミューテーション

ミューテーション名: environmentPatchCommitStaged

mutation environmentPatchCommitStaged(
  $environmentId: String!
  $message: String
  $skipDeploys: Boolean
) {
  environmentPatchCommitStaged(
    environmentId: $environmentId
    commitMessage: $message
    skipDeploys: $skipDeploys
  )
}

例:

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

Parameters

Field	Type	Default	Description
environmentId	String!	-	status から取得した環境 ID
message	String	null	変更内容の短い説明
skipDeploys	Boolean	false	デプロイをスキップ（ユーザーが明示的に依頼した場合のみ）

Commit Message

非常に短く、最大1文にしてください。例:

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

意味のある説明がない場合は空のままにしてください。

Default Behavior

ユーザーが明示的にスキップを求めない限り、常にデプロイします。ユーザーが "apply without deploying"、"commit but don't deploy"、"skip deploys" などと言った場合にのみ skipDeploys: true を設定してください。

成功時はワークフロー ID（文字列）を返します。

Auto-Apply Behavior

デフォルトでは、変更を即座に適用します。

Flow

単一の変更: environmentPatchCommit を使用して、1回の呼び出しでステージングと適用を行います。

複数の変更またはバッチ処理: 各変更に対して merge: true を指定して environmentStageChanges を使用し、その後 environmentPatchCommitStaged で適用します。

When NOT to Auto-Apply

• ユーザーが "stage only"、"don't deploy yet" などと明示的に言った場合
• ユーザーが一緒にデプロイされるべき複数の関連変更を行っている場合

自動適用しない場合は、ユーザーに次のように伝えてください:

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

projectId は 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

コミットするステージング済みの変更がありません。先に変更をステージングしてください。

Invalid Configuration

よくある問題:

• buildCommand と startCommand を同じ値にすることはできません
• buildCommand は NIXPACKS ビルダーでのみ有効です
• dockerfilePath は DOCKERFILE ビルダーでのみ有効です

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

• サービスの作成: railway-service スキルを使用
• ログの表示: railway-deployment スキルを使用
• ドメインの追加: railway-domain スキルを使用
• ローカルコードのデプロイ: railway-deploy スキルを使用