Deployment Profiles

Deployment profiles turn repeatable release steps into named actions. A profile pairs a small JSON definition with a shell script in the environment setup repo. Users can run the profile from the task dashboard, administrators can run it from the environment's Deploy tab, and automations can trigger it without asking an AI agent to write deployment commands.

Use deployment profiles for actions that should be reviewed, versioned, and reused: promoting an approved change to QA, publishing an extension, compiling to an IBM i target, copying generated artifacts, or running a release script with a few prompted inputs.

Where Profiles Live

Deployment profiles are stored under the environment directory in your coder setup repository:

environments/
  my-environment/
    environment.json
    deployment-profiles/
      qa.json
      qa.sh
      production.json
      production.sh

The profile name is the file basename. qa.json and qa.sh define the qa profile.

Each profile needs:

• A JSON file named <profile>.json
• A shell script named <profile>.sh
• A non-empty description in the JSON file

Profiles without a script can be saved, but they cannot run until the matching .sh file exists.

Naming Rules

Profile names must:

• Start with a letter or underscore
• Contain only letters, numbers, hyphens, and underscores
• Be 64 characters or fewer
• Avoid reserved names: new, add, create, default, list, all

Use short target-oriented names such as qa, production, publish-vscode, or compile-base.

JSON Format

A minimal profile contains only a description:

{
  "description": "Deploy the current approved code to QA"
}

A profile with parameters and deploy-scoped secrets looks like this:

{
  "description": "Deploy the application to a selected target",
  "parameters": {
    "TARGET": {
      "type": "select",
      "label": "Target",
      "description": "Deployment target",
      "required": true,
      "options": ["qa", "staging", "production"],
      "default": "qa"
    },
    "RUN_MIGRATIONS": {
      "type": "boolean",
      "label": "Run database migrations",
      "default": false
    },
    "RELEASE_NOTES": {
      "type": "textarea",
      "label": "Release notes"
    }
  },
  "secrets": [
    { "name": "deploy_token" },
    { "name": "ssh_private_key" }
  ]
}

Supported top-level fields:

Field	Required	Purpose
description	Yes	Human-readable summary shown in the UI and deploy task instructions.
parameters	No	Named values collected before the profile runs and exported to the script environment.
secrets	No	References to environment secrets that are available for the Deploy context.

Keep select options as string values when authoring JSON by hand. The parameter editor can display richer labels in some places, but string options are the most portable format for every deployment run surface.

Parameters

Parameters are named environment variables for the deployment script. Parameter names must use letters, numbers, and underscores, and must start with a letter or underscore.

Do not use reserved runtime variable names as parameters:

CODER_AGENT
TASK_ID
TASK_TYPE
ENVIRONMENT
CONTAINER_MODE
TZ
TERM
TASK_PARAMETERS_B64
TASK_ENV_VARS_B64
SETUP_SCRIPT
CLEANUP_SCRIPT
REPOS_CONFIG

Common parameter fields:

Field	Purpose
type	Input type. Use text, select, boolean, or textarea for profiles run from the dashboard. The environment Deploy tab also supports command parameters for loading choices.
label	Display label in the run dialog.
description	Help text below the input.
required	Blocks the run until a value is provided. Required booleans can be either true or false.
default	Default value used when the user does not provide one.
options	Allowed values for select parameters.
command	Command used by the environment Deploy tab to load choices for command parameters. Output is parsed as lines.

Example dynamic parameter:

{
  "parameters": {
    "VERSION": {
      "type": "command",
      "label": "Version",
      "description": "Choose a version discovered from the repository",
      "required": true,
      "command": "find dist -maxdepth 1 -type f -name '*.tgz' -printf '%f\\n' | sort"
    }
  }
}

The command runs in a short-lived CoderFlow container for the environment when the profile is run from the environment Deploy tab. Use it for safe discovery commands, not for deployment side effects. For profiles that most users run from the dashboard Deploy menu, prefer select parameters when values should be constrained.

Secrets

Deployment profiles do not store secret values. They reference environment secrets by name:

{
  "secrets": [
    { "name": "deploy_token" }
  ]
}

Before adding a secret to a profile:

1. Open the environment's Secrets tab.
2. Create or edit the secret.
3. Include Deploy in Available For.
4. Choose how it is exposed: environment variable or file mount.
5. Add the secret reference to the deployment profile.

At runtime, CoderFlow reads the environment secret definition and injects it according to that definition. Value secrets can become environment variables. File secrets can be mounted read-only at their configured container path.

Script Format

The script is a normal shell script:

#!/usr/bin/env bash
set -euo pipefail

echo "Deploying to ${TARGET}"

if [ "${RUN_MIGRATIONS:-false}" = "true" ]; then
  ./scripts/migrate.sh "${TARGET}"
fi

./scripts/deploy.sh "${TARGET}"

The script runs in a deployment container built from the environment image. The container has the environment's repositories, setup script, deploy-scoped secrets, configured connections, CA certificates, and volume mounts available in the same style as other CoderFlow task containers.

Parameter values are exported as environment variables using their parameter names. Branch selections are exported as <REPO_NAME>_BRANCH variables, with hyphens changed to underscores and the name uppercased. For example, a branch override for a repo named web-ui becomes WEB_UI_BRANCH.

Deployment tasks also receive run metadata such as the environment name, profile name, and task ID. Use your own profile parameters and secrets for business logic; treat metadata variables as helpers for logging and links.

Ordering Profiles

Use deployment_profile_order in environment.json to control the order shown in the UI:

{
  "deployment_profile_order": ["qa", "production"]
}

Profiles listed there appear first. Any remaining profiles fall back to alphabetical order. Reordering profiles in the environment UI updates this setting.

Running Profiles

Users usually run profiles from the task dashboard:

1. Select the environment.
2. Open the Deploy menu.
3. Choose a profile.
4. Fill in required parameters.
5. Start the deployment.

This creates a deploy task through /deploy-task. The run appears in the task list, streams output, records status, and can be pinned like other tasks.

Administrators can also open Environments, select an environment, and use the Deploy tab. That tab is useful for editing profiles, running a dry run, and reviewing deployment history for a profile.

Automations

Automations can target a deployment profile instead of a task template. Use this when a webhook, schedule, or SCM trigger should start a known deploy path. The automation stores the profile name and parameter values; when it fires, CoderFlow creates a deployment-backed task for that run.

See Automations for trigger setup and run history.

Authoring Workflow

1. Create deployment-profiles/<name>.json and deployment-profiles/<name>.sh.
2. Add a clear description and any parameters.
3. Add deploy-scoped secrets in the environment's Secrets tab, then reference them from the profile.
4. Add the profile to deployment_profile_order if it should appear before alphabetical fallback.
5. Commit and push the setup repo change.
6. Run the profile from the dashboard or the environment Deploy tab.
7. Review the output and adjust the script or parameters before promoting the same pattern to production.