Authentication and security for Agentic Pipelines

Agentic steps run AI agents inside your Bitbucket Pipelines containers. Security is enforced through short‑lived, scoped OAuth tokens and a Bitbucket Cloud MCP server that only exposes allowed operations. This page explains how permissions are granted, how the MCP server uses those permissions, and the controls available to harden agent capabilities.

Scoped OAuth tokens and auth scopes

Each step gets a short‑lived OAuth token that is:

Scoped to the repository that the pipeline runs against
Scoped to the step’s configured max-time (expires automatically when the step ends)
Implicitly allowed to read the repository to enable checkout and build

For agentic steps, you grant additional scopes so the AI agent can act via the Bitbucket MCP server without managing separate bot accounts. These scopes are added on top of the implicit read-only access.

Example

pipelines:
  custom:
    example:
      - step:
          auth:
            system:
              scopes:
                # read:repository:bitbucket is implicit
                - write:repository:bitbucket
                - read:pullrequest:bitbucket
                - write:pullrequest:bitbucket
          script:
            - agent: my-agent

Typical actions unlocked by these scopes:

Create or update pull requests
Add or edit pull request comments
Create and manage pull request tasks

Grant the minimum required scopes. Use read-only scopes by default (if possible) and add write scopes only to the specific steps that need them.

MCP servers

Pipelines supports multiple Model Context Protocol (MCP) servers when running AI agents in your steps. This includes a built‑in Bitbucket Cloud MCP server, as well as any additional custom MCP servers you configure (for example, Atlassian MCP or other custom MCP servers).

Bitbucket Cloud MCP server

When a step runs an agent, Pipelines starts a Bitbucket Cloud MCP server inside the container and injects the step’s OAuth token. Rovo Dev is automatically configured to use this server.

The Bitbucket Cloud MCP server:

Restricts the agent to allowed Bitbucket operations
Enforces the scopes granted to the step’s OAuth token
Provides tools focused on working with Bitbucket content

To use these tools safely:

Allowlist only the minimum set of tools the agent needs, and consider explicitly denying any tools you don’t want used.
Keep the agent’s prompt focused and clear so its behaviour stays within the intended scope.

Custom MCP servers

You can also integrate additional MCP servers (for example, Atlassian MCP for Jira or Confluence, or your own internal tools). When you do this:

Store all credentials in secure variables or via a supported third‑party secrets provider.
Don’t put secrets in repository files, container images, or directly in prompts.
Be cautious when trusting third-party MCP servers.

For more details on external MCP servers and risk considerations, refer to the following:
MCP Clients: Understanding the potential security risks - Work Life by Atlassian

Security considerations

Agentic execution can automate changes to code and PRs, call external tools, and access workspace and repository data. This introduces risks such as unintended code changes, over‑privileged access, or data exfiltration via external tools.

To reduce the risk of misuse or unexpected actions, treat agent security as a layered system: use scopes, configuration overrides, prompt design, and workflow controls together to constrain what each step can do.

Principle of least privilege

Grant only the scopes the agent needs for that step.
Preferably, use read scopes, and only add write scopes to specific, high-trust agent steps. Don’t add write scopes globally.
Use branch protections and required reviews/status checks so that write operations still go through human gates.

Tool and MCP server restrictions

By default, new tools are denied and must be explicitly allow‑listed.
Use toolPermissions to deny tools the agent should never use (for example, write operations in read‑only steps). For example, you can explicitly deny bitbucket MCP tools that are allowed by default like createPullRequest.
Only allow MCP servers that you trust and that expose the minimum required operations.

In the following example, the agent can still use other allowed tools, but is explicitly denied the ability to create pull request tasks.

Example

definitions:
  agents:
    my-agent:
      config:
        overrides:
          toolPermissions:
            tools:
              createPullRequestTask: deny
pipelines:
  default:
    - step:
        script:
          - agent: my-agent

Prompt safety and intent bounding

Explicitly state allowed operations and outputs in the prompt (for example, “only comment on the PR; do not push commits or open PRs”).
Avoid including secrets or credentials in prompts; use environment variables or secret management instead.
Be cautious when using custom Pipelines variables to override prompts at runtime. A malicious user could supply instructions that attempt to override previous safety constraints.

Step‑level isolation and separation of duties

Keep sensitive or high‑privilege actions in separate steps with distinct scopes and agents.
Use shorter max-time for high‑privilege steps to limit token lifetime.
Prefer “human‑in‑the‑loop” patterns: for example, have the agent open or update PRs instead of committing directly to protected branches.
Use different agents (and steps) for analysis vs. modification to make intent and permissions clearer. Context can be shared between steps via artifacts produced in earlier steps.

Audit and monitoring

Monitor step logs for unexpected agent actions, tool calls, or MCP usage that don’t match the intended prompt.
Treat unusual tool invocations or repeated write attempts in read‑only contexts as signals to tighten scopes, prompts, or tool permissions.

Examples

These examples show common patterns. Adjust scopes, prompts, and tool permissions to match your own risk profile.

Read-only analysis agent

definitions:
  agents:
    pr-summariser:
      prompt: |
        Summarise the discussion on the current pull request.
pipelines:
  custom:
    analyse-pr:
      - step:
          auth:
            system:
              scopes:
                - read:pullrequest:bitbucket
          script:
            - agent: pr-summariser

PR authoring agent (write-limited)

definitions:
  agents:
    release-notes-generator:
      prompt: |
        Generate release notes and open a pull request containing the notes file.
pipelines:
  custom:
    generate-release-notes:
      - step:
          auth:
            system:
              scopes:
                - write:repository:bitbucket
                - read:pullrequest:bitbucket
                - write:pullrequest:bitbucket
          script:
            - agent: release-notes-generator

We recommend combining this pattern with branch protections and required reviews so that agent‑created pull requests must be reviewed and pass checks before merge.

Quick reference: choosing scopes

Use case	Minimum scopes	Notes
Summarise PR comments	read:pullrequest:bitbucket	Agent reads comments via MCP; no write needed
Add a PR comment/ task	read:pullrequest:bitbucket, write:pullrequest:bitbucket	Allows creating/updating PR comments without giving write repository permissions
Open a PR with code changes	write:repository:bitbucket, read:pullrequest:bitbucket, write:pullrequest:bitbucket	Write to repo to push a branch; PR scopes to open the PR

Was this helpful?

It wasn't accurateIt wasn't clearIt wasn't relevant

Still need help?

The Atlassian Community is here for you.

Ask the Community