Rovo Dev: Advanced agentic configuration

By default, Agentic Pipelines uses a system-provided Rovo Dev configuration that is suitable for simple cases. For more advanced scenarios, you can:

provide your own rovo-config.yaml
override configuration fields directly from bitbucket-pipelines.yml
add additional MCP servers
plug-in an Atlassian MCP server by providing a user API token

This page explains the configuration options listed above.

Rovo Dev requirements

The Rovo Dev CLI requires a minimum of glibc 2.17 in the build image. The default image atlassian/default-image:5 already meets this requirement, and all major Linux-based Docker images (except Alpine Linux) are compatible.

We recommend using a non-Alpine build image for the agentic flow.

Additionally, Rovo Dev CLI requires git to be installed.

Store prompts in a file

For a complex tasks, you can store prompts in separate files instead of inlining them.

Prompt files:

Can be checked into the repository (for example, under .rovodev/prompts/)
Can be generated dynamically before executing an agentic task
Can be provided as part of a build image
Can be authored and tested locally with RovoDev CLI, and then reused in Bitbucket Pipelines.

Rovo Dev supports using ! as a prefix to load prompt fragments from files and chaining them using natural language, such as:

!./analyse-code.md and !./create-pull-request.md

For background on how prompt files and prompt libraries work in Rovo Dev, refer to the following:
Save and reuse a prompt in Rovo Dev CLI | Rovo | Atlassian Support

Prompt file definition example

image: "atlassian/default-image:5"
definitions:
  agents:
    pull-request-comment-reviewer:
      prompt: "!.rovodev/prompts/analyse-pr-comments.md"
    # if rofoDev configured to use prompts.yml
    pull-request-comment-reviewer2:
      prompt: "/prompts analyse-pr-comments"

Provide your own custom Rovo Dev config file

You can supply your own Rovo Dev configuration and have Pipelines merge it with the system base config.

You can store the config:

in your repository (for example .rovodev/config.yml)
included into the build image
generated earlier in the step script

Referencing a config file in an agent definition

For example

definitions:
  agents:
    my-agent:
      config:
        path: ".rovodev/config.yaml"   # relative to the agent’s working directory
pipelines:
  default:
    - step:
        script:
          - agent: my-agent

Overriding the config at step level

For example

pipelines:
  default:
    - step:
        script:
          - agent: my-agent
            config:
              path: "${BITBUCKET_CLONE_DIR}/.rovodev/config.yaml"

Example of rovo-config.yaml

agent:
  modelId: gpt5
mcp:
  mcpConfigPath: .rovodev/mcp.json

Key behaviors:

The config file at config.path is merged with the Pipelines system config.
If you specify mcp.mcpConfigPath, the referenced JSON is also merged with the system MCP config.

Use configuration overrides in `bitbucket-pipelines.yml`

Instead of, or in addition to, a config file, you can define config.overrides directly in your pipeline YAML. Overrides can be provided by a Dynamic Pipelines Provider to enforce specific agentic configuration.
overrides use the same object structure as the Rovo Dev config schema.

Combining `path` and `overrides` on an agent

For example

definitions:
  agents:
    my-agent:
      config:
        path: ".rovodev/config.yaml"
        overrides:
          mcp:
            mcpConfigPath: ".rovodev/mcp.json"

Overriding at step level

Step‑level overrides replace any overrides defined on the agent.

For example

pipelines:
  default:
    - step:
        script:
          - agent: my-agent
            config:
              overrides:
                toolPermissions:
                  tools:
                    createPullRequest: deny

Merge order

Configurations are merged in this order (later wins):

Pipeline system base config
User config from config.path (YAML)
User config from config.overrides (YAML)
System‑enforced overrides (for example, Bitbucket MCP injection)

Within a given config level:

Maps are merged by key
Lists are overwritten

Examples of disabling or restricting tools

You can use toolPermissions to selectively allow or deny tools.

Deny a single tool

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

You can:

deny multiple tools
configure more advanced permission models, for example, default deny and then allowlist for a specific step
definitions: agents: my-agent: config: overrides: toolPermissions: tools: createPullRequestTask: deny pipelines: default: - step: script: - agent: my-agent config: overrides: toolPermissions: tools: createPullRequestTask: allow

Add an extra MCP server

In addition to providing the Bitbucket MCP server, Rovo Dev CLI allows configuration of third-party MCP servers. This allows to extend the capabilities of an AI agent.

For more details, look at the Rovo Dev CLI documentation: Connect to an MCP server in Rovo Dev CLI | Rovo | Atlassian Support

1. Register your MCP server in `.rovodev/mcp.json`

For example

{
  "mcpServers": {
    "my-stdio-server": {
      "command": "command-to-run",
      "args": ["arg1", "arg2"],
      "env": {
        "ENV_VAR": "value"
      },
      "transport": "stdio"
    },
    "my-stdio-docker-server": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "my-docker-mcp"]
      "transport": "stdio"
    },
    "my-http-server": {
      "url": "https://example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${YOUR_API_KEY}"
      },
      "transport": "http"
    },
    "my-sse-server": {
      "url": "https://example.com/mcp/sse",
      "transport": "sse"
    }
  }
}

Supported transports

MCP supports three transport methods:

stdio: Communication via standard input/output (most common)
http: Communication via HTTP requests
sse: Communication via Server-Sent Events

2. Configure MCP in `rovo-config.yml`

For example

mcp:
  mcpConfigPath: .rovodev/mcp.json
  allowedMcpServers:
    # stdio:<command>:<args>
    - stdio:command-to-run:arg1 arg2
    - stdio:docker:run -i --rm my-docker-mcp
    # url:<url>
    - url:https://example.com/mcp
    - url:https://example.com/mcp/sse

mcpConfigPath points to a JSON file describing MCP servers.
allowedMcpServers is a list of allowed server “selectors”.
The format depends on the MCP transport:
- stdio:stdio:<command>:<args>
- http: url:<url>
- sse: url:<url>

3. No special configuration in your pipeline

For example

definitions:
  agents:
    my-agent:
      prompt: "Do something using my extra MCP tools"
      config:
        path: .rovodev/config.yml
pipelines:
  default:
    - step:
        script:
          - agent: my-agent

Configuring Atlassian MCP (Jira, Confluence, etc.)

Rovo Dev includes a built‑in Atlassian MCP that can connect to Jira and Confluence automatically.

In most cases, no extra configuration is required:

the built‑in Atlassian MCP is provided by Rovo Dev
access to Jira/Confluence is defined by the USER_API_TOKEN you provide for the agent step

Example using built‑in Atlassian MCP:

definitions:
  agents:
    jira-issues:
      prompt: "get all jira issues assigned to me"
pipelines:
  custom:
    get-jira-issues:
      - step:
          script:
            - agent: jira-issues

Configure Atlassian MCP manually

You only need to configure Atlassian MCP manually if you want the agent to use a different Atlassian user than the default USER_API_TOKEN, or you need very explicit control over the MCP configuration.

In that case, you can register the Atlassian MCP server yourself, and point Rovo Dev to your custom MCP config, while disabling the built‑in Atlassian MCP.

Create an API token https://id.atlassian.com/manage-profile/security/api-tokens.
Prepare base64 string for the ${ATLASSIAN_MCP_USER}:${ATLASSIAN_MCP_TOKEN} run in the terminal, for example, echo -n "user@example.com:$(pbpaste)" | base64 | pbcopy.
Create a repository secret with the name ATLASSIAN_MCP_AUTH.
Create the following files in your repository (see the examples below):

.rovodev/mcp.json

{
  "mcpServers": {
    "atlassian-mcp": {
      "url": "https://mcp.atlassian.com/v1/native/mcp",
      "headers": {
        "Authorization": "Basic ${ATLASSIAN_MCP_AUTH}"
      },
      "transport": "http"
    }
  }
}

.rovodev/config.yml

mcp:
  mcpConfigPath: .rovodev/mcp.json
  allowedMcpServers: 
    - url:https://mcp.atlassian.com/v1/native/mcp
# choose required tools you want to give rovo permissions to
toolPermissions:
  tools:
    getConfluenceSpaces: "allow"
# disable builtin mcp
experimental:
  disableBuiltinAtlassianMcp: true 

bitbucket-pipelines.yml (snippet)

definitions:
  agents:
    test-atlassian-mcp:
       prompt: list all available confluence spaces
       config:
         path: .rovodev/config.yml
pipelines:
 custom:
    test-atlassian-mcp:
      - step:
          script:
            - agent: test-atlassian-mcp

Give Rovo Dev CLI access to secrets

In Bitbucket Pipelines, your step environment variables are available to Rovo Dev CLI. However, for security reasons, Rovo Dev CLI automatically filters out any variables whose names suggest they contain secrets. These include:

token
key
password
secret
auth
credential

Environment variables matching these patterns are not passed through to MCP tools and commands, even though they exist in the build container. To allow Rovo Dev CLI to access specific secrets, explicitly reference them in .rovodev/config.yml or .rovodev/mcp.json using ${ENV_VAR} syntax.

Example of allowing access in bash (.rovodev/config.yml)

toolPermissions:
  bash:
    env:
      SNYK_TOKEN: ${SNYK_AUTH_TOKEN}

In the following example, the secret is configured for an MCP server (.rovodev/mcp.json):

{
  "mcpServers": {
    "snyk": {
      "command": "npx",
      "args": ["-y", "snyk@lastest", "mcp", "-t", "stdio"],
      "env": {
        "SNYK_TOKEN": "${SNYK_AUTH_TOKEN}"
      }
    }
  }
}

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

Rovo Dev: Advanced agentic configuration

Rovo Dev requirements

Store prompts in a file

Prompt file definition example

Provide your own custom Rovo Dev config file

Referencing a config file in an agent definition

Overriding the config at step level

Use configuration overrides in bitbucket-pipelines.yml

Combining path and overrides on an agent

Overriding at step level

Merge order

Examples of disabling or restricting tools

Deny a single tool

Add an extra MCP server

1. Register your MCP server in .rovodev/mcp.json

Supported transports

2. Configure MCP in rovo-config.yml

3. No special configuration in your pipeline

Configuring Atlassian MCP (Jira, Confluence, etc.)

Configure Atlassian MCP manually

Give Rovo Dev CLI access to secrets

Still need help?

Use configuration overrides in `bitbucket-pipelines.yml`

Combining `path` and `overrides` on an agent

1. Register your MCP server in `.rovodev/mcp.json`

2. Configure MCP in `rovo-config.yml`