AWS Builder Center
Atlantis + Bitbucket Cloud Integration: A DevOps Journey

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

  1. The Vision
  1. Initial Setup
  1. The Authentication Nightmare
  1. Debugging Journey
  1. The Breakthrough
  1. Final Working Configuration
  1. Lessons Learned
  1. 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:
  1. Developer creates a PR modifying DNS records
  1. Atlantis automatically runs  terraform plan 
  1. Team reviews the plan in the PR
  1. Developer comments  atlantis apply 
  1. 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-user  flag set to your email address."
The key insight:
  • Git operations (clone, push, pull) use:  username:token  with Basic auth
  • API operations (comments, status updates) use:  email:token  with 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 username
ATLANTIS_BITBUCKET_USER=username

# API operations use email
ATLANTIS_BITBUCKET_API_USER=example@gmail.com

# Same token for both
ATLANTIS_BITBUCKET_TOKEN=<Personal API Token>

# Webhook secret for security
ATLANTIS_BITBUCKET_WEBHOOK_SECRET=<webhook-secret>

# Allow custom workflows from repos
ATLANTIS_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:ListHostedZones
Error: 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=username
ATLANTIS_BITBUCKET_API_USER=example@gmail.com
ATLANTIS_BITBUCKET_TOKEN=<Personal API Token>
ATLANTIS_BITBUCKET_WEBHOOK_SECRET=<Webhook Secret>
ATLANTIS_REPO_ALLOWLIST=bitbucket.org/WorkspaceName/*
ATLANTIS_ATLANTIS_URL=https://atlantis.*.com
ATLANTIS_WEB_BASIC_AUTH=true
ATLANTIS_WEB_USERNAME=admin
ATLANTIS_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: 3
projects:
- 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:
  1. EC2 + ALB (infrastructure)
  1. S3 + DynamoDB (state backend)
  1. IAM permissions (authorization)
  1. 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

  1. Create a feature branch:__PRE_PLACEHOLDER_22__
  1. Modify route53/main.tf:__PRE_PLACEHOLDER_23__
  1. Push and create PR:__PRE_PLACEHOLDER_24__
  1. Wait for Atlantis auto-plan (or comment  atlantis plan )
  1. Review the plan in PR comments
  1. Apply changes:__PRE_PLACEHOLDER_25__
  1. 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
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article