Skip to main content

# 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.