Bridging BitBucket to AWS DevOps Agent's Release Readiness Review: A Custom AgentCore Gateway Pattern

A note on the scenario and names. This article uses a synthetic demo environment ("Pipewright") built specifically to validate this pattern end to end. No real customer names, account IDs, or credentials are referenced. AWS service behaviors and feature status are described from public documentation as of July 2026; verify current availability and feature status against the AWS docs before you build.

The problem

AWS DevOps Agent's release management capability includes a release readiness review that runs on pull requests and merge requests, but that native integration currently covers GitHub and GitLab only (Connecting to CI/CD pipelines docs.aws.amazon). If your organization runs BitBucket Cloud with BitBucket Pipelines, there's no BitBucket app, no native webhook mapping, and no built-in way for a BitBucket PR to trigger that review today.

A lot of teams still run BitBucket Pipelines with Terraform as their infrastructure-as-code layer, and don't want to wait for a native integration before getting value from DevOps Agent. This article walks through a pattern that closes that gap using only documented, supported extension points: a custom MCP server registered to an Agent Space, and a BitBucket Pipelines step that calls the agent directly and posts the result back to the PR.

What you'll learn

• Why BitBucket isn't natively supported and what extension points are available instead
• How to expose read-only BitBucket and Terraform context to DevOps Agent through a custom MCP server on Amazon Bedrock AgentCore Gateway
• How to authenticate the BitBucket Pipelines step to AWS without storing static credentials
• What a real pass/fail verdict looks like on a genuinely risky pull request
• Where this pattern's limits are, and what broke during testing

What we built

The bridge layer has two jobs: give the agent structured, read-only access to BitBucket and Terraform data it can't reach natively, and let a BitBucket Pipelines step invoke a review and post the verdict back to the PR.

The MCP server itself is a single Lambda function behind an Amazon Bedrock AgentCore Gateway Lambda target (AWS Lambda function targets docs.aws.amazon), with Cognito handling OAuth client credentials for the gateway-to-Lambda hop. That AgentCore Gateway plus Cognito plus Lambda combination is the same pattern used in the AWS DevOps Blog's write-up on diagnosing EKS node issues with a custom MCP server, just pointed at a different backend (BitBucket and HCP Terraform instead of EKS APIs).

The five tools

The Lambda exposes exactly five tools, all read-only:

Tool	Purpose
get_pull_request	Fetch PR metadata: branches, author, diff URL, state
list_recent_deployments	List recent pipeline runs since a timestamp, for incident correlation
get_pipeline_run	Look up a specific pipeline run by build number
list_repo_commits	List commits since a timestamp
get_terraform_context	Resolve an AWS resource ARN to its Terraform address and module, by reading remote state read-only

Keeping every tool read-only is deliberate. Write-capable tools introduce prompt injection risk, since an agent's tool selection is influenced by content it reads, like PR descriptions and commit messages. None of these five tools can mutate anything in BitBucket or Terraform state. Here's the dispatch logic and one of the tools, trimmed and genericized:

BITBUCKET_SECRET_ID = "pipewright/bitbucket-token"
HCP_TF_SECRET_ID = "pipewright/hcp-terraform-token"

_TOOL_DISPATCH = {
    "get_pull_request": tool_get_pull_request,
    "list_recent_deployments": tool_list_recent_deployments,
    "get_pipeline_run": tool_get_pipeline_run,
    "list_repo_commits": tool_list_repo_commits,
    "get_terraform_context": tool_get_terraform_context,
}

def handler(event, context):
    # AgentCore Gateway passes the tool name as
    # context.client_context.custom['bedrockAgentCoreToolName'],
    # formatted as "${target_name}___${tool_name}"
    tool_name = _extract_tool_name(event, context)
    tool_fn = _TOOL_DISPATCH.get(tool_name)
    if tool_fn is None:
        return {"error": f"Unknown or missing tool name: {tool_name!r}"}
    return tool_fn(event)

def tool_get_terraform_context(args):
    resource_arn = args.get("resourceArn")
    if not resource_arn:
        return {"error": "resourceArn is required"}

    headers, org = _hcp_tf_headers_and_org()
    workspace_id, list_error = _find_workspace_by_name(headers, org, TF_WORKSPACE_NAME)
    if not workspace_id:
        return {"resourceArn": resource_arn, "found": False, "reason": "workspace not found"}

    # fetch current state version, download it, and search resources
    # for a matching computed ARN (never writes state, never triggers plan/apply)
    ...
    return {"resourceArn": resource_arn, "terraformAddress": match.get("address"), "found": True}

One implementation detail worth calling out: BitBucket's Pipelines REST API has no GET /pipelines/{build_number} endpoint, only lookup by pipeline_uuid. To resolve a build number to a pipeline in one call instead of two, get_pipeline_run uses BitBucket's documented filter syntax, q=build_number={buildNumber}.

The BitBucket Pipelines side

On the BitBucket side, a pipeline step runs on pull request triggers, gets the diff, calls the agent, and posts the result back:

pipelines:
  pull-requests:
    '**':
      - step:
          name: devops-agent-release-review
          oidc: true
          script:
            - python bridge/trigger_review.py \
                --repo "$BITBUCKET_REPO_SLUG" \
                --pr-id "$BITBUCKET_PR_ID" \
                --standards-ref standards/release-readiness.md

The pipeline step authenticates to AWS using BitBucket's native OpenID Connect support rather than static access keys. Setting oidc: true on the step makes BitBucket Pipelines present a signed identity token that AWS can verify against an IAM OIDC identity provider (Deploy on AWS using Bitbucket Pipelines OpenID Connect atlassian.com, Create an OIDC identity provider in IAM docs.aws.amazon). We scoped the trust policy down to the exact repository running the review, and the assumed role to only the release-readiness invocation action. Nothing long-lived is stored in BitBucket at all, not even in a secured pipeline variable.

The review call itself is wrapped in a small bounded retry loop, capped at three attempts. If the agent is unreachable or over its concurrency quota after retries, the pipeline step doesn't silently pass. It returns a synthetic NEEDS_ATTENTION result and fails the build. Fail closed, not fail open.

What a real review looks like

In testing, we ran two intentionally risky pull requests through this pipeline:

PR 1: Disabled S3 public access block settings on a bucket. PR 2: Applied a wildcard (*) IAM policy to a role.

Both got a genuine FAIL verdict from the agent, posted as an actual PR comment plus a failed commit build status, which combined with a branch permission requiring passing builds, blocked the merge. This wasn't a scripted demo response. It was the real DevOps Agent evaluating the actual Terraform diff against standard access control guidance and returning findings.

What didn't work, and what we learned

BitBucket's own automatic pipeline trigger failed intermittently with an agent-service.queue.timeout error on the pipeline side. This turned out to be a BitBucket platform-side queuing issue, not a problem with the integration itself. Worth flagging because if you build this pattern, don't assume every automatic trigger failure means your bridge is broken. Confirm against BitBucket's own status and logs first.

Because of that, we also built a manual "run it now" trigger as a fallback path: a separate Lambda behind API Gateway that asynchronously invokes the same review call the pipeline step would make, and streams progress back through a small DynamoDB events table while it runs. This turned out to be useful beyond just working around the flaky auto-trigger. It's a good way to demo the review flow live without waiting on a real BitBucket webhook delivery.

A few other things worth knowing before you build this yourself:

• VPC-hosted MCP servers aren't supported for this integration point. Your MCP server endpoint needs to be reachable over public HTTPS, even if it's fronted by IAM or OAuth auth. Plan your network exposure accordingly.
• Terraform topology awareness is best effort, not exact. The native topology graph understands CloudFormation stacks and AWS resource tags, not Terraform modules directly. The get_terraform_context tool helps by resolving an ARN back to a Terraform address, but consistent default_tags from your Terraform AWS provider still matters for the native topology engine to get the most value.
• Tool names have a 64 character limit, and results should stay structured and small. Trim raw API payloads before returning them, both for cost and for keeping the agent's context focused.

Where the line is

This pattern is not a replacement for DevOps Agent's native GitHub/GitLab release readiness review. It's a workaround for teams whose delivery platform isn't natively supported yet. If BitBucket support ever lands natively, this bridge becomes mostly redundant and the natural move is to migrate. It also doesn't give the agent anything beyond the five read-only tools defined here. Broader Terraform state awareness, cross-repo dependency analysis, and access-control verification are native DevOps Agent capabilities for GitHub/GitLab today, and only partially approximated here for BitBucket.

Summary

Until BitBucket is natively supported, this pattern gets teams running BitBucket Pipelines plus Terraform real release readiness coverage without waiting. The whole bridge is one Lambda function, a Cognito app client, and an OIDC trust relationship, registered as a custom MCP server on an Agent Space. It's a reasonable amount of scaffolding for what it buys you.

References

• AWS DevOps Agent — Connecting to CI/CD pipelines docs.aws.amazon
• Amazon Bedrock AgentCore — AWS Lambda function targets docs.aws.amazon
• Atlassian — Deploy on AWS using Bitbucket Pipelines OpenID Connect atlassian.com
• AWS IAM — Create an OpenID Connect (OIDC) identity provider in IAM docs.aws.amazon
• AWS DevOps Blog — Diagnose EKS Node Issues Faster with AWS DevOps Agent and Custom MCP aws.amazon

---