Building Bitbucket Apps on the Atlassian Forge Platform

Have you ever considered the need for additional features or capabilities that are specifically designed to meet your requirements while working on Atlassian’s Bitbucket platform? These custom-made features can greatly enhance your team’s productivity. If you haven’t thought about it before, now is the time to do so! With the Atlassian Forge Platform, adding these tailored functionalities is possible.

In this blog, we will explore the features and advantages of using the Forge platform and provide you with a detailed, step-by-step guide on how to build Bitbucket apps using Forge.

The Forge Platform

Forge is Atlassian’s serverless app development platform, designed to enable customers and marketplace vendors to build secure, reliable, and scalable apps for Atlassian cloud tools.

Forge takes care of server management, security, and scalability, allowing developers to focus on building the app itself. This not only saves time and effort but also ensures that apps can seamlessly integrate with Atlassian products without any compatibility issues.

Forge is typically made of the following three main components:

1. A serverless Function-as-a-Service (FaaS) that is hosted on the Atlassian platform has API authentication built-in.
2. A declarative UI language (Forge UI), responsible for fast coding and building intuitive UI.
3. A DevOps toolchain, allowing for the creation, testing, and deployment of apps in different environments such as development, staging, and production.

Forge simplifies the process of building and deploying apps for Atlassian products such as:

• Bitbucket
• Jira
• Jira Service Management
• Compass
• Confluence

Building Bitbucket Apps on Forge

Bitbucket is a popular Git repository management platform by Atlassian. With Forge being integrated into Bitbucket, you can build custom apps and seamlessly integrate them into your Bitbucket Cloud instance.

Atlassian Forge provides a variety of Bitbucket apps, each designed for a specific purpose. In general, there are two types of apps available:

1. Custom UI Apps that utilize UI Kit 2 for creating personalized user interfaces.
2. Triggers and Validators that are automated and activated upon specific Forge Events such as when a pull request is created.

Steps to Build Custom Forge Apps For Bitbucket

Step 1: Set up a development environment

To start building Bitbucket apps on Forge, you need to set up a local development environment.

1. Download and Install Docker. Forge requires Docker version 17.03 or later. It’s recommended to use the latest Docker Desktop WSL 2 backend.
2. Set up Node.js by downloading and installing the LTS installer from Node.js.
3. Install the Forge CLI globally by running:

npm install -g @forge/cli

Verify that the CLI is installed correctly by running:

forge — version

4. Login with an Atlassian API token by creating or using an existing Atlassian API from here. The CLI uses your token when running commands. Start the process by running :

forge login

Now follow the steps and provide the required information such as the email address associated with your Atlassian account and your Atlassian API token.

Step 2: Create a new app

Using the Forge CLI, create a new app with the specified template. You can choose from various templates, including custom UI, Triggers and Validators, etc.

We will follow the following steps to create a UI App as follows :

1. Execute the following :

forge create

2. Enter a name for your app (up to 50 characters). For example, my-first app.

3. Select the UI kit 2 (Preview) category.

4. Select the Bitbucket product.

5. Select the bitbucket-repository-code-overview-card template.

6. Change to the app subdirectory to see the app files by running :

cd my-first-app

Note: When you create a new app, Forge will prompt you to set a default environment. In this tutorial, we use the development environment as our default.

Step 3: Develop your app

Next, start developing your Bitbucket app by writing custom code and configuring the desired functionality. Forge provides a rich set of APIs and libraries to interact with Bitbucket, making it easy to retrieve data, perform actions, and integrate seamlessly with the platform.

Before we start making any changes to the app, let's understand the project structure and different artifacts that come with the bitbucket-repository-code-overview-card template that uses Node.js :

my-first-app
├── README.md
├── manifest.yml
├── package-lock.json
├── package.json
└── src
    ├── frontend
    │   └── index.jsx
    ├── index.js
    └── resolvers
        └── index.js

Let’s have a look at what these files are:

• manifest.yml: Describes your app. This file contains the name and ID of the app, the app permissions, and the modules the app uses. To learn more about the manifest.yml file, see Forge manifest documentation.
• package.json: The app’s Node.js metadata. See the Node documentation for more information.
• package-lock.json: Records the version of the app’s dependencies.
• README.md: Information about the app. It’s recommend updating this as you change the behavior of the app.
• src/frontend/index.jsx: Where you write the application with which the user interacts directly.
• src/resolvers/index.js: Where you write the resolver function definitions. To learn more about resolvers, see the Custom UI Resolver documentation.

Now make the following changes to change the title of the app to your name :

1. In the app’s top-level directory, open the manifest.ymlfile.
2. Find the title entry under the bitbucket:repoCodeOverviewCard module.
3. Change the value of titleto Forge app for <your name>. For example, Forge app for Chirag Gangwal.

Step 4: Deploy your app

Once you have implemented the desired features, it is crucial to thoroughly test your app to ensure it works as expected. Forge provides a local development environment where you can test your app in isolation that you must have selected while creating the app.

Now let’s test our app by deploying it to the target Bitbucket workspace. The forge deploy command builds, compiles, and deploys your code; it’ll also report any compilation errors. The forge install command then installs the deployed app onto a Bitbucket workspace with the required API access.

1. Navigate to the app’s top-level directory and deploy your app by running:

forge deploy

2. Install your app by running:

forge install

3. Select Bitbucket using the arrow keys and press the enter key.

4. Enter the URL for your workspace. For Ex. https://bitbucket.org/cloudwerxai/

5. Once the successful installation message appears, your app is installed and ready to use on the specified workspace. You can always delete your app from the workspace by running the forge uninstall command.

6. You can now view the app on a repository by navigating to the source page in the repository. Your app should appear at the bottom of the Repository details pane on the right:

Note: Forge apps are not supported on personal workspaces. If you install an app to a personal workspace, you will get an insufficient permissions error.

7. Once your app is installed, it will automatically pick up all minor app deployments so you don’t need to run the forge install command again. Minor deployments are changes that don't modify app permissions in the manifest.yml file. You can deploy the changes onto your developer site or Bitbucket workspace by using one of two methods:

• Manually, by running the forge deploy command.
• Automatically, by running the forge tunnel command.

Tunneling uses ngrok and Forge CLI to expose your local server to the internet and test your app in a real Bitbucket environment.

Note: To use the forge tunnel command, Docker must be set up and running. If you don’t want to run Docker, you can redeploy your app after each code change with the forge deploy command.

Step 5: Distribute or Publish Your App

Forge provides seamless integration with the Atlassian Marketplace, allowing you to easily manage your app listing, pricing, and distribution.
So once your app is ready, you can either share it with internal users or publish it to the Atlassian Marketplace, making it available to users worldwide.

Note: Apps that require publishing must be submitted for review to Atlassian Marketplace to ensure compliance with their security and quality guidelines. Once approved, you can deploy your app, making it available for installation by Bitbucket users globally.

Conclusion

With the Atlassian Forge Platform, building Bitbucket apps has become intuitive and efficient. It eliminates the complexity of infrastructure management, ensures compatibility with Bitbucket, and provides a secure and scalable environment for developers. Whether you’re extending Bitbucket’s capabilities at the repository level, managing accounts, or offering powerful global features, Forge equips you with the necessary tools and resources.

Explore the diverse array of app types, choose the one that best suits your needs, and unleash your creativity with Bitbucket app development on the Atlassian Forge Platform. Happy coding!

🍕Connect with me on Linkedin: https://www.linkedin.com/in/chiraggangwal/
🍕If you found this blog helpful, check my other blogs as well: https://medium.com/@chiraggangwal

Special Note: If you found our information valuable and would like to hear more about how Cloudwerx can help take you and your business to the next level, we’d love to hear from you. Get in touch with us at
🌐www.cloudwerx.co or 📧 hello@cloudwerx.co.