Agent configuration

Use agents in Bitbucket Pipelines to offload work like explaining code, reviewing pull requests, or summarizing changes to an AI assistant. This page explains how to configure those agents so they behave consistently across your pipelines.

On this page, you'll learn how to:

Choose an agent provider.

Configure prompts, either inline or from a reusable skill file.

Use the built‑in default agent and override its settings when needed.

Understand how configuration precedence works between default agents, custom agents, and step‑level overrides.

Agent provider

provider specifies which AI provider the agent uses. You can set it:

On the agent definition, or
As an override on the step

Available values: rovodev, claude and codex.

Note: When you select Claude, this integration is a third-party product. Atlassian does not control and has no liability for third-party products, see Third-Party Agents providers and Bitbucket Agentic Pipelines for more information.

If you don't specify a provider anywhere, Bitbucket Pipelines uses rovodev by default.

Example: use Claude provider in the agent definition

definitions:
  agents:
    my-agent:
      prompt: "Explain this repository"
      provider: claude
pipelines:
  default:
    - step:
        script:
          - agent: my-agent

Prompt configuration

Prompts can be provided inline or via a referenced skill (file).

Inline prompt

Use an inline prompt for short, simple instructions. Set it directly on the agent definition, or override it at the step level.

Note: The exact prompt format (for example, how you refer to files or tools) may be provider‑specific. Check the provider’s documentation if you need advanced prompt patterns.

Example: inline prompt in the agent definitions

definitions:
  agents:
    my-agent:
      prompt: "Explain this repository"

You can also override the prompt at the step level:

definitions:
  agents:
    my-agent:
      prompt: "Explain this repository"
pipelines:
  default:
    - step:
        script:
          - agent: my-agent
            prompt: "Summarise the recent changes"

Skill reference

For longer or reusable prompts, define them as skills in your repository and reference them using the /skill syntax.

Skill locations differ depending on the provider:

Claude: .claude/skills/
see Claude Code skills
Rovo Dev: .rovodev/skills or .agents/skills
see Rovo Dev CLI with Agent Skills

definitions:
  agents:
    my-agent:
      prompt: "/review-pr $BITBUCKET_PR_ID"

Agent configuration

Use agent configuration to load provider‑specific settings from a file and optionally override individual values per agent or step.

This is useful when you want a different configuration in CI compared to local development.

Config path

config.path points to a provider‑specific configuration file committed in your repository. The file is read at runtime for the selected provider and its settings are used as a base (for example, model, safety settings, and permissions).

File examples:

.claude/settings.json

.rovodev/config.yaml

definitions:
  agents:
    fix-build-agent:
      prompt: "/fix-build"
      config:
        # Default CI agent settings
        path: "./rovodev/config-ci.yml"
pipelines:
  default:
    - step:
        name: Build
        script:
          - agent: fix-build-agent
            config:
               # More specific config for build step
              path: "./rovodev/config-ci-build.yml"

Config overrides

config.overrides provides inline values that take precedence over the loaded config file and defaults. Use it to tweak a subset of settings without duplicating the full config file.

Merge behaviour:

Values are deep‑merged with existing settings.

Arrays are replaced, not concatenated.

Example: Use a shared config file and override a single field

definitions:
  agents:
    summariser:
      prompt: "Summarise recent changes"
      provider: claude  
      config:
        path: .claude/settings-ci.json
        overrides:
          model: sonnet
pipelines:
  default:
    - step:
        name: Summarise changes
        script:
          - agent: summariser
            # optionally, can also be specified on a step level
            config:
              overrides:
                # This will override deny permissions for the agent
                permissions:
                  deny: ["Read(./.env)"]

Default agent

Bitbucket Pipelines provides a built‑in default agent you can use out of the box. This is useful when you're starting out or when you only need simple agent behavior.

Use the default agent by specifying it in your step and providing a prompt:

pipelines:
  default:
    - variables:
        - name: PROMPT
          description: prompt for the default agent
    - step:
        script:
          - agent: default
            prompt: $PROMPT

Similar to custom agents, the default agent can be configured in the definitions section:

definitions:
  agents:
    default:
      provider: claude
pipelines:
  default:
    - step:
        script:
          - agent: default
            prompt: $PROMPT

Settings under definitions.agents.default are also applied to custom agents unless those settings are overridden on the custom agent or at the step level:

definitions:
  agents:
    default:
      provider: claude
    my-claude-agent:
      prompt: Hello Claude!
pipelines:
  default:
    - step:
        script:
          - agent: my-claude-agent

The default agent supports the same configuration fields as a custom agent, and any of them can be overridden on the custom agent:

definitions:
  agents:
    # by default use claude agent with specific permissions
    default:
      provider: claude
      config:
        path: ".claude/settings.json"
        overrides:
          permissions:
            deny: 
              - "Bash(curl *)"
              - "Read(./.env)"
    my-claude-agent:
      prompt: Hello Claude!
    my-claude-agent-with-opus-model:
      prompt: Hello Claude!
      config:
        overrides:
          model: opus
pipelines:
  default:
    - step:
        script:
          - agent: my-claude-agent

Configuration precedence (highest wins):

Step overrides
Custom agent
Default agent

Tool permissions

Use permissions.on-ask to control how Pipelines responds when an agent requests permission to run a tool. Pipelines approves or denies these requests automatically, without waiting for a person to respond.

MCP allow and deny rules are supported for Claude and Codex agents.

These rules apply only to permission requests received by Pipelines. Configure the agent to request permission for the tools you want Pipelines to control. Tools already approved or blocked by the agent’s own configuration may not produce a request. See the Claude configuration or Codex configuration documentation for agent-specific settings.

Configuration

Configure permissions in your agent definition in bitbucket-pipelines.yml:

permissions:
  on-ask:
    default: deny
    allow:
      - "mcp__atlassian-v2-bitbucket-tools__executeRead"
      - "mcp__atlassian-v2-bitbucket-tools__executeWrite(name:addBitbucketRepoPullRequestComment)"
    deny:
      - "mcp__atlassian-v2-bitbucket-tools__executeDestructive"

Property	Description
`default`	The response when no allow or deny rule matches. Accepts `allow` or `deny`.
`allow`	A list of MCP rules identifying requests to approve, unless a deny rule also matches.
`deny`	A list of MCP rules identifying requests to deny. Matching deny rules always take precedence.

This example approves matching Bitbucket read requests and requests to add pull request comments. It denies requests to use executeDestructive. Other requests use the default behavior unless an inherited rule matches.

If no fallback is configured or inherited, it is deny. Supplying an on-ask object without default also sets the fallback to deny.

The existing shorthand remains supported:

permissions:
  on-ask: deny

This sets the fallback while preserving any inherited allow and deny rules.

Rule matching

Rules identify an MCP server, a tool, or a tool with an argument filter.

Rule	Matches
`mcp__atlassian-v2`	All tools on the `atlassian-v2` server
`mcp__atlassian-v2__*`	All tools on the `atlassian-v2` server
`mcp__atlassian-v2__executeRead`	The server’s `executeRead` tool
`mcp__atlassian-v2__execute*`	Tools whose names start with `execute`
`mcp__atlassian-v2__executeWrite(name:create*)`	Calls to `executeWrite` whose `name` argument starts with `create`

Matching is case-sensitive and covers the entire tool name or argument value. * matches zero or more characters. Regular expressions are not supported.

Use the exact configured server identifier. The Atlassian Rovo MCP v2 integration uses two separate servers:

atlassian-v2 for Jira, Confluence and other non-Bitbucket tools.
atlassian-v2-bitbucket-tools for Bitbucket tools.

Argument filters

Use (<argument>:<pattern>) to match one top-level string argument. For the Atlassian execution wrappers, the name argument identifies the operation:

allow:
  - "mcp__atlassian-v2-bitbucket-tools__executeWrite(name:addBitbucketRepoPullRequestComment)"

Without an argument filter, a rule covers every operation exposed through that tool.

If the specified argument is missing, empty or not a string, the rule does not match. Pipelines continues checking other rules and then uses the fallback if none match.

Resolving conflicting rules

For each permission request, Pipelines evaluates the effective rules in this order:

If any deny rule matches, deny the request.
Otherwise, if any allow rule matches, approve the request.
If neither list matches, use the configured default.

A matching deny rule always takes precedence. Rule order and specificity do not change the result. A more specific allow rule cannot create an exception to a broader deny rule.

For example:

permissions:
  on-ask:
    default: deny
    allow:
      - "mcp__atlassian-v2-bitbucket-tools__executeWrite(name:addBitbucketRepoPullRequestComment)"
    deny:
      - "mcp__atlassian-v2-bitbucket-tools__executeWrite"

Adding a pull request comment through executeWrite is denied because the broader deny rule also matches.

To permit selected operations and reject unmatched requests, use default: deny with the required allow rules. Avoid adding a broader deny rule that also matches those operations.

Each permission request is evaluated independently.

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

Agent configuration

Agent provider

Prompt configuration

Inline prompt

Skill reference

Agent configuration

Config path

Config overrides

Default agent

Tool permissions

Configuration

Rule matching

Resolving conflicting rules

Related topics

Still need help?