`/api/plan` returning an error about post-merge verification failing

[khung]

Community Note

• Please vote on this issue by adding a 👍 reaction to the original issue to help the community and maintainers prioritize this request. Searching for pre-existing feature requests helps us consolidate datapoints for identical requirements into a single place, thank you!
• Please do not leave "+1" or other comments that do not add relevant new information or questions, they generate extra noise for issue followers and do not help prioritize the request.
• If you are interested in working on this issue or have submitted a pull request, please leave a comment.

---

Overview of the Issue

It looks like PR #5895 may not work the same way as the old logic when using the API endpoints. When I try running the API endpoint /api/plan against the main branch, the API returns the following error:

{
  "error": "post-merge verification failed: HEAD^2 != main"
}

Reproduction Steps

Make a POST request to https://hostname/api/plan with the following body:

{
  "Repository": "myorg/myrepo",
  "Ref": "main",
  "Type": "Github",
  "Paths": [{
    "Directory": "myterraformconfig"
  }]
}

Logs

Logs

{"level":"info","ts":"2025-12-03T15:31:09.818Z","caller":"events/working_dir.go:120","msg":"repo was already cloned but branch is not at correct commit, updating to \"main\"","json":{}}
{"level":"warn","ts":"2025-12-03T15:31:25.985Z","caller":"controllers/api_controller.go:391","msg":"{\"error\":\"post-merge verification failed: HEAD^2 != main\"}","json":{},"stacktrace":"github.com/runatlantis/atlantis/server/controllers.(*APIController).respond\n\tgithub.com/runatlantis/atlantis/server/controllers/api_controller.go:391\ngithub.com/runatlantis/atlantis/server/controllers.(*APIController).apiReportError\n\tgithub.com/runatlantis/atlantis/server/controllers/api_controller.go:87\ngithub.com/runatlantis/atlantis/server/controllers.(*APIController).Plan\n\tgithub.com/runatlantis/atlantis/server/controllers/api_controller.go:101\nnet/http.HandlerFunc.ServeHTTP\n\tnet/http/server.go:2322\ngithub.com/gorilla/mux.(*Router).ServeHTTP\n\tgithub.com/gorilla/mux@v1.8.1/mux.go:212\ngithub.com/urfave/negroni/v3.(*Negroni).UseHandler.Wrap.func1\n\tgithub.com/urfave/negroni/v3@v3.1.1/negroni.go:59\ngithub.com/urfave/negroni/v3.HandlerFunc.ServeHTTP\n\tgithub.com/urfave/negroni/v3@v3.1.1/negroni.go:33\ngithub.com/urfave/negroni/v3.middleware.ServeHTTP\n\tgithub.com/urfave/negroni/v3@v3.1.1/negroni.go:51\ngithub.com/runatlantis/atlantis/server.(*RequestLogger).ServeHTTP\n\tgithub.com/runatlantis/atlantis/server/middleware.go:70\ngithub.com/urfave/negroni/v3.middleware.ServeHTTP\n\tgithub.com/urfave/negroni/v3@v3.1.1/negroni.go:51\ngithub.com/urfave/negroni/v3.(*Recovery).ServeHTTP\n\tgithub.com/urfave/negroni/v3@v3.1.1/recovery.go:210\ngithub.com/urfave/negroni/v3.middleware.ServeHTTP\n\tgithub.com/urfave/negroni/v3@v3.1.1/negroni.go:51\ngithub.com/urfave/negroni/v3.(*Negroni).ServeHTTP\n\tgithub.com/urfave/negroni/v3@v3.1.1/negroni.go:111\nnet/http.serverHandler.ServeHTTP\n\tnet/http/server.go:3340\nnet/http.(*conn).serve\n\tnet/http/server.go:2109"}

Environment details

• Atlantis version: v0.37.1
• Deployment method: helm
• If not running the latest Atlantis version have you tried to reproduce this issue on the latest version: n/a
• Atlantis flags: see helm chart values below

Atlantis helm chart values:

# config file
github:
  hostname: <removed>
enableDiffMarkdownFormat: true
ingress:
  enabled: false
environment:
  ATLANTIS_CHECKOUT_STRATEGY: merge
  ATLANTIS_DEFAULT_TF_VERSION: v1.11.1
  ATLANTIS_WEB_BASIC_AUTH: "true"
  AWS_ENDPOINT_URL_S3: <removed>
  TF_CLI_CONFIG_FILE: /plugins/terraform.tfrc
loadEnvFromSecrets:
  - <removed>
initConfig:
  enabled: true
  sharedDir: /plugins
atlantisUrl: <removed>
orgAllowlist: <removed>

Atlantis server-side config file:

repos:
- id: /.*/
  allowed_overrides: [apply_requirements]

workflows:
  default:
    plan:
      steps:
        - run: terraform fmt -check=true -diff=true -write=false
        - init
        - plan
    apply:
      steps:
        - apply
        - run: inventory-update.sh

Repo atlantis.yaml file:

version: 3
projects: 
- dir: ./myterraformconfig

Additional Context

The error message is part of the changes in PR #5895.

[dosubot]

Hi @khung! I'm Dosu and I’m helping the atlantis team.

This error happens because Atlantis's merge checkout strategy expects a pull request context, but the /api/plan endpoint is being used directly against a branch (like main) without a PR number. After PR #5895, Atlantis tries to verify that the second parent of the merge commit (HEAD^2) matches your target ref. In a non-PR context, this check fails since there isn't a real merge commit, resulting in the "post-merge verification failed: HEAD^2 != main" error (source).

To work around this, you can set ATLANTIS_CHECKOUT_STRATEGY=branch for API-triggered plans, which avoids the merge logic and the problematic verification step. The merge strategy is only needed for actual PR workflows where a merge commit is present. If you need both workflows, consider running separate Atlantis instances or switching the strategy dynamically based on context.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[khung]

I was able to resolve this for my particular case by setting ATLANTIS_CHECKOUT_STRATEGY=branch as suggested by Dosu. However, I'm keeping this open as there is nothing in the documentation indicating that ATLANTIS_CHECKOUT_STRATEGY=merge would not work with the API when using the API endpoint directly against a branch. I can imagine some other people who need to keep the merge strategy and want to use the /api/plan endpoint against a branch (like for checking for configuration drift).