Atlantis Hook Execution#

Overview#

Atlantis supports pre-workflow hooks and post-workflow hooks — shell commands that run before or after default/custom workflows execute on a pull request. Unlike custom workflow run steps, hooks run outside Atlantis command workflows and do not surface output as PR comments. They are configured exclusively in the Server-Side Repo Config under the repos key — not in per-repo atlantis.yaml files. 1 2

A primary use case for pre-hooks is dynamic repo config generation: running a script that writes atlantis.yaml before Atlantis parses it. Post-hooks are commonly used for cross-project cost estimation summaries (e.g., aggregating Infracost outputs after all plan workflows complete). 1 2

Configuration#

Hooks are specified under repos[].pre_workflow_hooks or repos[].post_workflow_hooks in the server config.

repos:
  - id: /.*/
    pre_workflow_hooks:
      - run: ./gen-atlantis-yaml.sh
        description: Generate atlantis.yaml
        commands: plan
        shell: bash
        shellArgs: -c
    post_workflow_hooks:
      - run: ./notify.sh
        description: Notify on plan or apply
        commands: plan, apply

Supported fields per hook (post-workflow-hooks docs, pre-workflow-hooks docs):

The valid.WorkflowHook struct holds exactly these fields: RunCommand, StepDescription, Commands, Shell, ShellArgs 3. There are no directory-scoping fields — hooks are matched at the repo level only.

Invocation Flow#

Both hook types follow the same lifecycle, orchestrated by DefaultCommandRunner in server/events/command_runner.go:

RunCommentCommand / RunAutoplanCommand
  │
  ├── shouldSkipPreWorkflowHooks? ──yes──▶ return (no hooks, no command)
  │
  ├── PreWorkflowHooksCommandRunner.RunPreHooks() ← pre hooks
  │
  ├── cmdRunner.Run() ← plan / apply / etc.
  │
  ├── if ctx.CommandSkipped → return (no post hooks)
  │
  └── PostWorkflowHooksCommandRunner.RunPostHooks() ← post hooks

4 5

• Pre hooks — RunPreHooks: collects hooks from GlobalCfg repos matching by repo ID only 6, acquires a workspace lock, clones the repo, and executes hooks in order.
• Post hooks — RunPostHooks: matches by both repo ID and branch 7, and additionally surfaces CommandHasErrors and CommandName in the hook context 8, useful for conditional post-hook behavior.
• Both runners short-circuit immediately if no hooks are configured for the repo 9 10.

VCS Commit Status#

Each hook posts commit status updates: Pending → Success (or Failed) for every hook step. Updates can be suppressed via SuppressVCSStatus on the context 11 12.

Command Targeting (commands field)#

By default, every hook runs for every Atlantis command. Set commands to restrict execution to specific commands. The check is a substring match against the comma-separated string:

if hook.Commands != "" && !strings.Contains(hook.Commands, ctx.CommandName) {
    continue // skip this hook
}

13 14

commands: plan, apply matches both plan and apply. Values must match the command names exactly as Atlantis uses them (e.g., plan, apply, import, state).

Two environment variables are available inside hook scripts for conditional logic 2:

• COMMAND_NAME — the triggering command (plan, apply, etc.)
• COMMAND_HAS_ERRORS — post-hooks only; true if the preceding command had errors, otherwise false

Directory-Based Skip Logic (autodiscover.ignore_paths)#

Hooks have no directory-scoping configuration of their own. However, when a user targets a specific directory (via -d <dir>) that matches an autodiscover.ignore_paths pattern, hooks are skipped entirely:

1. PlanCommandRunner.ShouldSkipPreWorkflowHooks and its apply equivalent delegate to MarkCommandSkippedIfIgnoredTarget 15.
2. That function sets ctx.CommandSkipped = true when cmd.RepoRelDir matches an ignored path (and no project name was explicitly targeted) 16.
3. If the skip is triggered before pre-hooks, pre-hooks are not run 17.
4. If ctx.CommandSkipped is true after command execution, post-hooks are also skipped 18.

Special case — pre-hooks updating repo config: If pre-hooks are configured (e.g., to generate atlantis.yaml), DefaultCommandRunner runs them even when the target is initially ignored, then re-evaluates the skip via ctx.PreferLocalRepoCfgForTargetedIgnore. If the directory is still ignored after hooks run, execution stops before the command 19.

Pre-Hook Error Handling#

Pre-hook failures do not block command execution by default. Control this with the --fail-on-pre-workflow-hook-error server flag 1:

• Flag set: Atlantis posts the error as a PR comment, marks plan/apply commit status as failed, and aborts the command 20.
• Flag unset: error is logged and execution continues 21.

Post-hook errors are logged but do not affect PR state or commit statuses 22.

Key Source Files#