Neptune 🌊

Terraform and OpenTofu Pull Request Automation with Github Actions

• Neptune 🌊
  • Resources
  • What is Neptune?
  • What does it do?
  • Why should you use it?

Resources

• Code of Conduct: CODE_OF_CONDUCT.md – we adopt the CNCF Community Code of Conduct.
• Documentation: docs/ – Configuration, object storage, installation, usage, and development. Log level can be set via log_level in config or NEPTUNE_LOG_LEVEL (DEBUG, INFO, ERROR).
• E2E tests: e2e/README.md – Run against MinIO with ./e2e/scripts/run-terramate.sh or make e2e
• Releases: github.com/devopsfactory-io/neptune/releases
• Infra examples: examples/ – S3/GCS backend, automerge, Terramate stacks, Terragrunt.
• neptbot: Trigger Neptune from PR open and @-mention comments by installing the neptbot GitHub App and adding the workflow (recommended). To self-host, see lambda/ and lambda/README.md.
• Contributing: CONTRIBUTING.md – how to contribute; docs/development.md and AGENTS.md for setup and AI/contributor guidance
• Dependencies: Renovate opens PRs for Go modules and GitHub Actions updates (see .github/renovate.json5).

What is Neptune?

A Terraform and OpenTofu pull request automation tool inspired by Atlantis, but runs entirely in GitHub Actions. It supports two modes for stack management: Terramate (using the Terramate Go SDK for change detection and run order) or local (config or stack.hcl discovery with git-based change detection). Object storage (GCS or S3) is used for stack locking (we make sure that an stack can not be changed by multiple PRs at the same time), and GitHub for PR requirements and comments.

What does it do?

Runs Terraform or OpenTofu plan and apply on pull requests safely with github actions. Locks stacks in object storage, checks PR requirements (e.g. approved, mergeable, undiverged), posts results as PR comments, and sets GitHub commit statuses for neptune plan and neptune apply (so you can require neptune apply in branch protection to block merge until apply has run).

Why should you use it?

With the typical Terraform + GitHub Actions flow, apply often runs after merge. Code on main can end up broken, and you fix it with follow-up PRs. Apply-before-merge (plan on PR → approve → apply on the PR → merge only when apply succeeds) keeps main fully executable. Neptune and Atlantis both support this; Neptune runs entirely in GitHub Actions—no separate servers or self-hosted runners.

• Make Terraform/OpenTofu changes visible to your whole team
• Apply approved changes in a consistent way
• Standardize workflows with configurable plan/apply steps

For a detailed comparison of the normal Terraform workflow, Neptune, and Atlantis, see Workflow comparison.