
Atlantis + Bitbucket Cloud Integration: A DevOps Journey
After extensive debugging, research, and multiple iterations, I successfully integrated Atlantis with Bitbucket Cloud for GitOps-based Route53 DNS management.
Executive Summary
After extensive debugging, research, and multiple iterations, I successfully integrated Atlantis with Bitbucket Cloud for GitOps-based Route53 DNS management. This document chronicles the journey from initial setup through the challenges encountered, the debugging process, and ultimately the working solution.
The goal was simple: manage AWS Route53 DNS records through Pull Requests instead of manual AWS Console changes. The execution? Not so simple.
Table of Contents
- The Vision
- Initial Setup
- The Authentication Nightmare
- Debugging Journey
- The Breakthrough
- Final Working Configuration
- Lessons Learned
- Architecture Overview
The Vision
As a DevOps engineer, I've always believed in the principle: "If it's not in version control, it doesn't exist." DNS records are critical infrastructure, yet they're often managed through point-and-click interfaces with no audit trail, no peer review, and no rollback capability.
The solution? Atlantis — a tool that brings Terraform workflows into Pull Requests. The idea is elegant:
- Developer creates a PR modifying DNS records
- Atlantis automatically runs
terraform plan
- Team reviews the plan in the PR
- Developer comments
atlantis apply
- Changes are applied with full audit trail
Simple, right? Well, not quite.
Initial Setup
Infrastructure Deployed
I started by creating the Atlantis infrastructure using Terraform:
atlantis/├── main.tf # EC2, IAM, Security Groups, ALB├── terraform.tfvars # Configuration (gitignored)└── *-atlantis-key.pem
Resources Created:
- EC2 Instance (t3.small) with Docker
- Application Load Balancer with HTTPS
- Route53 A record for
atlantis.*.com
- IAM Role with necessary permissions
- Security Groups for HTTP/HTTPS/SSH
The deployment went smoothly. Atlantis was accessible at
https://atlantis.*.com . The web UI loaded perfectly.Then came the fun part: authentication.
The Authentication Nightmare
Attempt #1: App Passwords (The "Easy" Way)

Following Atlantis documentation, I configured Bitbucket App Passwords. Created the token, set it up, triggered a webhook...
401 Unauthorized
Checked the credentials. They looked correct. Tried again.
401 Unauthorized
After hours of debugging, I discovered: Bitbucket deprecated App Passwords in September 2025. The documentation I was following was outdated.
Attempt #2: Repository Access Tokens
Bitbucket's recommended replacement: Repository Access Tokens. Created one with all necessary scopes:
-
repository:read
-
repository:write
-
pullrequest:read
-
pullrequest:write
-
webhook
Configured Atlantis with the token...
401 Unauthorized
Wait, what? The token works when I test it with curl using Bearer authentication:
# This works!curl -H "Authorization: Bearer $TOKEN" https://api.bitbucket.org/2.0/repositories/...
But Atlantis was still failing. More investigation revealed the issue:
Repository Access Tokens require Bearer authentication for API calls, but Atlantis uses Basic authentication.
This is a fundamental incompatibility. Atlantis sends:
Authorization: Basic base64(username:token)
But Repository Access Tokens expect:
Authorization: Bearer token
Attempt #3: Various Username Combinations
I tried every username format imaginable:
-
x-token-auth:token
-
x-bitbucket-api-token-auth:token
- Repository Access Token UUID
- Workspace UUID
- Account UUID
All resulted in the same dreaded response:
401 Unauthorized
At this point, I had spent hours on what should have been a 30-minute setup.
Debugging Journey
The Investigation
I started digging deeper. Enabled verbose logging in Atlantis:
{"level":"error","msg":"POST https://api.bitbucket.org/2.0/repositories/.../pullrequests/1/comments: 401"}
Tested git clone operations separately — they worked! The issue was specifically with Bitbucket API calls.
The GitHub Issue Discovery
After extensive searching, I found GitHub Issue #5696: "Bitbucket Cloud Atlantis Incompatibility After App Password Deprecation"
This was exactly my problem! And buried in the discussion was the solution:
"Use a Personal API Token (not Repository Access Token) with--bitbucket-api-userflag set to your email address."
The key insight:
- Git operations (clone, push, pull) use:
username:tokenwith Basic auth
- API operations (comments, status updates) use:
email:tokenwith Basic auth
Personal API Tokens work with Basic auth using the email as username, while Repository Access Tokens do not.
The Breakthrough
The Working Authentication Model
Atlantis v0.37.1 added a new flag:
--bitbucket-api-user This allows specifying a different username for API operations than for Git operations:
Operation | Username | Auth Method |
|---|---|---|
Git clone/push | (Bitbucket username) | Basic |
API calls | (Email) | Basic |
Both use the same Personal API Token, but with different usernames!
Testing the Theory
First, I verified git operations:
git clone https://username:$TOKEN@bitbucket.org/WorkspaceName/repo.git# Success!
Then API operations:
curl -u "example@gmail.com:$TOKEN" \ https://api.bitbucket.org/2.0/repositories/WorkspaceName/repo# Success!
Both worked! Now to configure Atlantis...
Environment Configuration
Updated the server's
/home/ubuntu/atlantis/.env :# Git operations use usernameATLANTIS_BITBUCKET_USER=username
# API operations use emailATLANTIS_BITBUCKET_API_USER=example@gmail.com
# Same token for bothATLANTIS_BITBUCKET_TOKEN=<Personal API Token>
# Webhook secret for securityATLANTIS_BITBUCKET_WEBHOOK_SECRET=<webhook-secret>
# Allow custom workflows from reposATLANTIS_REPO_CONFIG_JSON={"repos":[{"id":"/.*/","allowed_overrides":["workflow","apply_requirements"],"allow_custom_workflows":true}]}
Restarted Atlantis, triggered a plan...
{"level":"info","msg":"Updating BitBucket commit status for 'atlantis/plan' to 'SUCCESSFUL'"}
IT WORKED!
But we weren't done yet...
Additional Challenges Overcome
Challenge 1: Terraform State Backend
The plan failed because there was no S3 bucket for Terraform state:
Error: S3 bucket "*-terraform-state" does not exist.
Solution: Created the state backend infrastructure:
- S3 bucket with versioning and encryption
- DynamoDB table for state locking
- IAM policy for Atlantis access
cd state-backend && terraform apply
Challenge 2: Missing IAM Permissions
Error: AccessDenied: route53:ListHostedZonesError: UnauthorizedOperation: ec2:DescribeInstanceCreditSpecifications
Solution: Added inline policies to the Atlantis IAM role:
{ "Statement": [ { "Sid": "Route53FullAccess", "Effect": "Allow", "Action": [ "route53:GetHostedZone", "route53:ListHostedZones", "route53:ListTagsForResource", "route53:ChangeResourceRecordSets", "route53:GetChange" ], "Resource": "*" }, { "Sid": "EC2ReadAccess", "Effect": "Allow", "Action": [ "ec2:DescribeInstances", "ec2:DescribeInstanceTypes", "ec2:DescribeVolumes", "ec2:DescribeInstanceAttribute", "ec2:DescribeInstanceCreditSpecifications" ], "Resource": "*" } ]}
Challenge 3: Workflow Override Not Allowed
Error: repo config not allowed to set 'workflow' key
Solution: Added server-side repo config via environment variable:
ATLANTIS_REPO_CONFIG_JSON={"repos":[{"id":"/.*/","allowed_overrides":["workflow"],"allow_custom_workflows":true}]}
Challenge 4: Incorrect EC2 Instance Tags
The Route53 Terraform config referenced EC2 instances by tag name, but the actual tag names were different:
Expected | Actual |
|---|---|
*-frontend-dev | *ctl-frontend-dev |
*-monitor | *-monitor-dev |
Solution: Updated the data source filters in
route53/main.tf .
Final Working Configuration
Server Environment Variables
# /home/ubuntu/atlantis/.env
ATLANTIS_BITBUCKET_USER=usernameATLANTIS_BITBUCKET_API_USER=example@gmail.comATLANTIS_BITBUCKET_TOKEN=<Personal API Token>ATLANTIS_BITBUCKET_WEBHOOK_SECRET=<Webhook Secret>ATLANTIS_REPO_ALLOWLIST=bitbucket.org/WorkspaceName/*ATLANTIS_ATLANTIS_URL=https://atlantis.*.comATLANTIS_WEB_BASIC_AUTH=trueATLANTIS_WEB_USERNAME=adminATLANTIS_WEB_PASSWORD=<Web UI Password>ATLANTIS_REPO_CONFIG_JSON={"repos":[{"id":"/.*/","allowed_overrides":["workflow","apply_requirements","plan_requirements"],"allow_custom_workflows":true}]}
Repository atlantis.yaml
version: 3projects: - name: route53 dir: route53 workspace: default terraform_version: v1.6.0 workflow: route53 autoplan: when_modified: - "*.tf" - "*.tfvars" enabled: true
workflows: route53: plan: steps: - init: extra_args: ["-upgrade"] - run: echo "🌐 Planning Route53 DNS changes..." - plan - run: echo "⚠️ Review DNS changes carefully before approving!" apply: steps: - run: echo "🚀 Applying Route53 DNS changes..." - apply - run: echo "✅ DNS changes applied successfully!"
AWS Resources Created
Resource | Name/ID |
|---|---|
EC2 Instance | uuid |
Public IP | ip-address |
ALB | *-alb-dev |
Route53 Record | atlantis.*.com |
S3 Bucket | *-terraform-state |
DynamoDB Table | *-terraform-locks |
IAM Role | *-atlantis-role |
Lessons Learned
1. Documentation Gets Outdated
Bitbucket deprecated App Passwords, but many tutorials and even official docs hadn't caught up. Always check the date of documentation and verify against current platform behavior.
2. Authentication is Hard
The difference between "Bearer" and "Basic" authentication, combined with platform-specific quirks (email vs username), created a debugging nightmare. When something says "401 Unauthorized," the issue might be more nuanced than wrong credentials.
3. GitHub Issues Are Gold
The solution was found in a GitHub issue discussion, not official documentation. When facing integration problems, searching the project's issues is often helpful.
4. Test Components in Isolation
When the full system failed, I broke it down:
- Tested git clone separately ✅
- Tested API calls separately ✅
- Identified the mismatch
5. Infrastructure Has Dependencies
The Atlantis setup required:
- EC2 + ALB (infrastructure)
- S3 + DynamoDB (state backend)
- IAM permissions (authorization)
- Correct tokens (authentication)
Each layer had to work before the next could be tested.
6. Document Everything
I'm writing this at midnight after finally getting everything working. But future me (and future team members) will thank present me for documenting the journey, not just the destination.
How to Use the System
Creating a DNS Change
- Create a feature branch:__PRE_PLACEHOLDER_22__
- Modify route53/main.tf:__PRE_PLACEHOLDER_23__
- Push and create PR:__PRE_PLACEHOLDER_24__
- Wait for Atlantis auto-plan (or comment
atlantis plan)
- Review the plan in PR comments
- Apply changes:__PRE_PLACEHOLDER_25__
- Merge PR after successful apply
Useful Atlantis Commands
Command | Description |
|---|---|
atlantis plan | Run plan for all projects |
atlantis plan -p route53 | Run plan for specific project |
atlantis apply | Apply all planned changes |
atlantis apply -p route53 | Apply specific project |
atlantis unlock | Release locks without applying |
Conclusion
What started as a "quick 30-minute setup" turned into a multi-hour debugging odyssey through deprecated authentication methods, undocumented platform quirks, and infrastructure dependencies. But in the end, we have a robust, production-ready GitOps pipeline for DNS management.
The system now provides:
- Version Control: All DNS changes tracked in git
- Peer Review: Changes require PR approval
- Audit Trail: Full history of who changed what and when
- Automation: No more manual AWS Console clicking
- Safety: Plan before apply, review before merge
Was it worth the struggle? Absolutely. The infrastructure will serve the team for years to come, and this documentation ensures the next engineer won't have to repeat the same debugging journey.
"The best time to document was when you started. The second best time is now."
— Every DevOps Engineer Ever
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article