Agentic Pipelines: Step-by-step guide

By the end, you'll have:

• A working pipeline that runs automatically

• A basic understanding of agent configuration

• Confidence to move forward with more complex agentic pipelines

What is an “agentic pipeline”?

• Agent: an AI that can follow instructions, read files, and produce outputs (e.g., text, code).

• Pipeline: an automated process that runs on events (like a Bitbucket build pipeline).

• Agentic pipeline: your CI pipeline invokes an AI agent with a prompt and some inputs (e.g., code, docs) and writes back outputs (e.g., an updated README.md).

Prerequisites

• A Bitbucket account with a Standard or Premium plan.

• A user account with a Rovo Dev licence.

• Agentic Pipelines is enabled for the Bibucket workspace. Enable Agentic Pipelines in your Workspace Settings. Select Atlassian Integrations, then select Atlassian Intelligence, and then enable Agentic Pipelines.
  
  For more detailed information about enabling Rovo Dev see:

  • Add Rovo Dev Standard to your site | Rovo | Atlassian Support

  • Turn Rovo Dev features on and off | Rovo | Atlassian Support

  • Integrate Rovo Dev with Bitbucket Pipelines

Step 1 – Create a New Repository

Let’s create a fresh repository for this tutorial.

1. Log in to Bitbucket.

2. In the top navigation bar, select + Create.

3. Select Repository.

4. Fill in the details:

   • Project: Select an existing project or create a new one (for example, Learning Pipelines).

   • Repository name: my-first-agentic-pipeline

   • Access level: Private (recommended for tutorials) or Public if you prefer.

   • Include a README?: Yes (this gives us a starting README file to work with).

   • Include .gitignore?: No (we keep this example minimal; you can add one later)

5. Select Create repository.

Step 2 – Configure Rovo Dev for your Bitbucket repository

Before proceeding, configure Rovo Dev for use in your Bitbucket repository. You’ll need a user account with a Rovo Dev licence. For simplicity, this tutorial configures variables at the repository level only - no workspace-level variables or admin access required. Workspace-level variables are also possible for shared setups.

• Login with the user and create an unscoped API token Manage API tokens for your Atlassian account | Atlassian Support. Copy the value

• Add repository-level variables via Repository settings → Pipelines → Repository Variables

  • add a non-secret variable USER_EMAIL

  • add a secret variable USER_API_TOKEN with the value that you copied before

  • add a non-secret variable BILLING_SITE_URL with the url of your site where rovodev is configured, for example, https://yoursite.atlassian.net.

Step 3 – Add a Simple Application

In this step, you will create a tiny Node.js app entirely in the Bitbucket web UI.
You don't need to clone the repository or run any commands locally.

We’ll create:

• A package.json file that describes the app and lists dependencies

• An index.js file with a simple web server with 2 API endpoints

Later, your agentic pipeline will read these files and use them to keep your README.md up to date.

2.1 Create package.json

package.json is a standard Node.js file that:

• Names your project

• Declares how to run it ("start": "node index.js")

• Lists dependencies (here we use Express to make HTTP endpoints)

You’ll create this file from the Bitbucket UI:

1. In the Source view, select … menu, then select Add file.

2. In the File name field, enter:

   package.json

3. In the large text area, paste the following content:

   { "name": "my-first-agentic-pipeline", "version": "1.0.0", "description": "A minimal Node.js app with two endpoints for agentic README demos.", "main": "index.js", "scripts": { "start": "node index.js", "test": "echo \"No tests yet\" && exit 0" }, "dependencies": { "express": "^4.19.0" } }

4. Click Commit (leave the default commit message).

2.2 Create index.js with web server

Now you’ll create the main app file that defines the HTTP endpoints.

1. Still in the Source view, select Add file again.

2. In the File name field, enter:

   index.js

3. In the large text area, paste this code:

   const express = require('express'); const app = express(); // Choose a port for the server to listen on const PORT = process.env.PORT || 3000; // Endpoint 1: GET /greet // This returns a simple welcome message. app.get('/greet', (req, res) => { res.send('Hello from my simple Node.js app!'); }); // Endpoint 2: GET /greet/:name // This endpoint accepts a "name" as a URL parameter. // Example: GET /greet/Alice -> "Hello, Alice!" app.get('/greet/:name', (req, res) => { const name = req.params.name; res.send(`Hello, ${name}! Nice to meet you.`); }); // Start the server app.listen(PORT, () => { console.log(`Server is running on http://localhost:${PORT}`); });

4. Select Commit.

Step 4 – Configure Bitbucket Pipeline to Build the App

Set up a default pipeline to install dependencies and run basic checks for the Node.js app

3.1 Create bitbucket-pipelines.yml

1. In your repository, in the Source view, select Add file and create bitbucket-pipelines.yml

2. Paste the file content with:

1. Commit changes

3.2 Run the first pipeline 🚀

Open Pipelines from the left navigation menu

1. Click Run initial pipelines

2. Select Branch main

3. Select Pipeline default

4. Click Run

Wait until the pipeline is complete and confirm it's successful

Step 5 – Configure an Agentic Pipeline to Update the README

Right now, the README.md in your repository doesn’t explain what the app does or how to run it.
In this step, you’ll configure an agentic Bitbucket pipeline that uses an AI agent to update the README for you.

We’ll:

1. Add a prompt file that tells the agent what to do.

2. Register the agent and a custom pipeline in bitbucket-pipelines.yml.

3. Run the pipeline and see the README update.

4.1 Create the agent prompt file

Create a prompt file in your repo that describes how the agent should update README.md.

1. In Bitbucket, open your repo and go to Source

2. Select … , and then select Add file.

3. In the File name field, enter:

   .rovodev/prompts/readme-auto-updater.md

4. Paste this content:

   You are an AI assistant responsible for keeping README.md synchronized with the current application code and configuration. Your overall goal: - Analyze the repository. - Infer the application type (language, framework, endpoints, configuration). - Update README.md to match the current state of the app, following the template below. - Preserve useful existing content where it is still correct. --- ## Step 1: Analyze the application Use the repository contents to understand the app. At minimum: - Detect languages, frameworks, entrypoints, scripts, and versions from dependency/build files. - Identify HTTP/API endpoints (method, path, brief description, key params, typical responses). - Read configuration (ports, environment variables, external services) from common config files. ## Step 2: Update README.md using this template ### 1. Overview - 1–3 short paragraphs describing what the app does and who/what uses it. ### 2. Technology Stack - Language/Runtime, Framework/Libraries, Build tool, Notable runtime details (e.g., default port). ### 3. API Endpoints (if applicable) - METHOD PATH — one‑line purpose - Request example (curl) and typical response snippet - Note key path/query/body params ### 4. Configuration - Important environment variables (name, meaning, default/example) - Ports/URLs and noteworthy settings ### 5. Local Development - Prerequisites - Install, Run, Test commands (use repo scripts where possible) ## Step 3: Writing & preservation rules - Prefer updating existing sections; preserve License/Contributing/Security/Badges. - Clearly label any necessary assumptions. - Keep tone clear, concise, beginner‑friendly. ## Step 4: Output format - Return ONLY the final README.md content in Markdown. - Do NOT include explanations outside the README.

5. Select Commit.

4.2 Register the agent and custom pipeline in bitbucket-pipelines.yml

Now you’ll connect that prompt file to an agent and expose it as a custom pipeline.

1. Open bitbucket-pipelines.yml in Source and then in your bitbucket-pipelines.yml.

2. Select Edit.

3. Update the file so it looks like this (keeping your existing default build step):

1. Select Commit.

What this does:

• definitions.agents.update-readme-agent defines the agent and its prompt

• pipelines.custom.update-readme defines a manual pipeline that runs the update-readme-agent

Step 6 – Run the agentic pipeline

Now it's time to run our first agentic pipeline!

5.1 Run the pipeline

1. In your repository, go to Pipelines.

2. Select Run pipeline.

3. Select:

   • Branch: main (or the branch you want to update)

   • Custom pipeline: update-readme

4. Select Run.

Wait for the pipeline to complete. The Update README step should finish with a green checkmark.

5.2 What the agent does (expected output)

When this pipeline runs, the agent:

• Analyzes the repository code and configuration.

• Generates an updated README.md using the template from the prompt.

• Writes the updated README.md to a new branch.

• Commits the change on that branch.

• Creates a pull request (PR) back to your main branch.

You don’t need to do any of these steps manually—the pipeline and agent handle them for you.

5.3 Find the pull request and verify the README

1. From the pipeline run page, check the logs for a line indicating that a pull request was created.

   • There should be a link to the PR in the logs. Click it to open the PR, or

   • Go to the Pull requests tab in Bitbucket and open the most recent PR created by the agent
     (for example, something like “Update README with agent”).

2. In the pull request:

• Open the Files changed (or Diff) tab.

• Review the new README.md:

  • Confirm the overview matches what the app actually does.

  • Check that endpoints (paths, methods, parameters) are correctly described.

  • Verify configuration and run instructions are accurate (install, start, test commands).

• If needed, tweak the README directly in the PR.

When you’re happy with the changes, merge the PR to update the README on your main branch.

Conclusion

You’ve just built your first end‑to‑end agentic pipeline:

• A fresh Bitbucket repository

• A minimal Node.js app with simple HTTP endpoints

• A default Bitbucket pipeline to install dependencies and run basic checks

• A generic agent prompt that analyzes the app and rewrites the README using a clear template

• An agentic pipeline that runs the agent, updates the README, and creates a pull request with the changes

When everything is wired up correctly, you should see:

• A successful run of the update‑readme custom pipeline in Pipelines

• A new pull request with an updated README.md that better reflects your app’s code, endpoints, and configuration

From here, you can:

• Tighten or expand the prompt to match your documentation style

• Replace the “no tests yet” script with real tests in npm test

• Add a scheduled run (for example, nightly) for the agentic pipeline

• Grow your application with more endpoints or services and let the agent keep the README in sync