Skip to content

feat: Declarative script execution ordering in the Terraform provider #22365

Closed

Description

@matifali

Originally posted by @ewengillies in #10352

Problem

coder_script resources run concurrently. There is no Terraform-level way to declare execution ordering between scripts or modules. The current workaround (coder exp sync) requires manually instrumenting every bash script with signaling boilerplate and is experimental.

This causes race conditions, failed startups, and makes composable modules unreliable.

Use cases

UC1 — Sequential scripts within a template

A template has scripts that must run in order: configure SSH keys → clone repo → install dependencies. Today these race.

UC2 — Script depends on a module completing

A template-level script (e.g. "run AI agent on repo") needs all scripts from the git-clone module to finish first. The template author should not need to know the module's internal script names.

UC3 — Module depends on another module

The claude-code module depends on the git-clone module. All scripts in claude-code should wait for all scripts in git-clone to complete. This must work without either module author hardcoding the other's internals.

UC4 — "Run before everything" (inverse dependency)

A script that configures apt mirrors must run before any other script installs packages — including scripts inside third-party modules. Today there is no way to express "run me first" without modifying every downstream script.

UC5 — Resource contention (dpkg/apt lock)

Multiple scripts that use apt-get fail with lock conflicts when run concurrently. Ordering or mutual exclusion must be expressible to prevent this.

UC6 — AI agent multi-step workflow

A user needs this exact sequence, reliably:

  1. Bootstrap user config (SSH keys, git config)
  2. Clone repo (requires 1)
  3. Run coding agent on cloned repo (requires 2)
  4. Push changes (requires 1-3)

All of these currently run in parallel, regularly failing. (Ref: comment)

UC7 — Preserve parallelism for independent scripts

Scripts with no ordering relationship must continue to run concurrently. Ordering is opt-in and should not regress startup times.

UC8 — Clear failure propagation

If a script fails, dependent scripts should be skipped with a clear error indicating which upstream dependency failed.

Constraints

  • The solution must work across modules from the Coder registry without requiring module consumers to know internal script names.
  • Module authors must be able to expose ordering interfaces for their scripts.
  • The mechanism should be declarative in Terraform, not require bash-level instrumentation.
  • An RFC is likely warranted given the public API surface and complexity. See prior discussion on trade-offs between order, run_after, depends_on, and CLI-based signaling in #10352.

References

Activity

  1. added theissue type on Feb 27, 2026
  2. self-assigned this
    on Apr 17, 2026
  3. matifali commented on Nov 5, 2026

    @matifali
    ContributorAuthor

    Declarative script ordering shipped in Coder v2.39.0 with terraform-provider-coder v2.20.0.

    Docs: https://coder.com/docs/admin/templates/extending-templates/script-ordering
    Reference: https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/script_order

    data "coder_script_order" "startup" {
      rule {
        phase = "start"
        run   = ["module.claude_code"]
        after = ["module.git_clone", "coder_script.bootstrap"]
      }
    }
    • Order individual scripts or whole modules (module.<name>) without knowing a module's internal script names or changing its source.
    • Ordering is opt-in. Scripts without rules still run in parallel.
    • If a prerequisite fails, its dependents are skipped and the logs name the script that failed. Use requires = "completion" for scripts that should run anyway.
    • Shutdown scripts can be ordered with phase = "stop".

    Requires provider v2.20.0+ and Coder v2.39.0+. Older components ignore the rules and run scripts concurrently.

    coder exp sync is still available, and the docs include a migration guide.

    Closing as complete. Please open a new issue for any gaps.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions