Part 1: Build a Bitbucket hello world app (EAP)

This tutorial will walk you through creating a sample Forge app for Bitbucket. There are three parts to the tutorial:

1. This page: describes creating, changing, and installing a simple hello world app. The focus is on learning the CLI commands needed to work with apps.

2. Call a Bitbucket API: describes how to make API calls to the Bitbucket REST API.

3. Change the frontend with the UI kit: describes how to use UI kit components.

We recommend you work through all three parts to get a good understanding of how to develop apps with Forge.

Before you begin

To complete this tutorial, you need to do complete Getting started before working through this page.

Set up a team space

For Bitbucket apps you need to join or create a shared Bitbucket team workspace (as Forge apps are not supported on personal workspaces). If you don't have a Bitbucket workspace, see the references below for related instructions:

1. Creating a Bitbucket Cloud account.
2. Join or create a workspace.

A free Bitbucket team space can have up to 5 users.

Create your app

Create an app based on the blank template. We do not have templates for Bitbucket app yet. You can view the completed app code in the Bitbucket Forge Hello World repository.

1. Navigate to the directory where you want to create the app. A new subdirectory with the app’s name will be created there.

2. Create your app by running:

   1
   2
   forge create
   

3. Enter a name for your app (up to 50 characters). For example, hello-world-app.

4. Select the Show All category.

5. Select the Blank template.

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

   1
   2
   cd hello-world-app
   

7. Create a file named package.json with the following contents:

   1
   2
   {
     "name": "bitbucket-forge-hello-world-app",
     "version": "1.0.0",
     "main": "index.jsx",
     "license": "SEE LICENSE IN /LICENSE",
     "private": true,
     "dependencies": {
       "@forge/api": "^2.18.4",
       "@forge/ui": "^1.9.0"
     }
   }
   

8. Create a file named index.jsx in the src folder with the following contents:

   1
   2
   import ForgeUI, { render, Fragment, Text } from "@forge/ui";
   
   const App = () => {
     return (
       <Fragment>
         <Text>Hello world!</Text>
       </Fragment>
     );
   };
   
   export const run = render(<App />);
   

9. Add the following contents to the manifest.yml file:

   1
   2
   modules:
     'bitbucket:repoCodeOverviewCard':
       - key: hello-world-app-hello-world-panel
         function: main
         title: My Forge app
     function:
       - key: main
         handler: index.run
   

Repository code overview card

The app we'll create will display a card panel on all Bitbucket repository source pages and will have a function that provides the contents of the panel.

Our app uses Node.js and has the following structure:

1
2
hello-world-app
|-- src
|   `-- index.jsx
|-- manifest.yml
|-- package.json
|-- package-lock.json
`-- README.md

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

• index.jsx: Where you write the behavior of the app.
• manifest.yml: Describes your app. This file contains the name and ID of the app, the app permissions, and the modules the app uses.
• package.json: The app’s Node.js metadata. See the Node documentationfor more information.
• package-lock.json: Records the version of the app’s dependencies.
• README.md: Information about the app. We recommend updating this as you change the behavior of the app.

Change the panel title

This app displays content in a Bitbucket repository card panel using the bitbucket:repoCodeOverviewCard module. Bitbucket shows the title of the bitbucket:repoCodeOverviewCard as the panel's heading. Let's change the title to include your name.

1. In the app’s top-level directory, open the manifest.yml file.

2. Find the title entry under the bitbucket:repoCodeOverviewCard module.

3. Change the value of title to Forge app for <your name>. For example, Forge app for Mia.

4. In the permissions section, add or remove scopes as needed. For example, add the read:repository:bitbucket scope.

   1
   2
   permissions:
     scopes:
       - "read:repository:bitbucket"
   

Your manifest.yml file should look like the following, with your values for the title and app ID:

1
2
modules:
  'bitbucket:repoCodeOverviewCard':
    - key: hello-world-app-hello-world-panel
      function: main
      title: Forge app for Mia
  function:
    - key: main
      handler: index.run
permissions:
  scopes:
    - "read:repository:bitbucket"
app:
  id: '<your app id>'

Install your app

To use your app, it must be installed onto a 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.

1. Navigate to the app's top-level directory and install the dependencies, e.g. by running the below if you have nvm setup (example .nvmrc here):

   1
   2
   nvm use
   

   1
   2
   nvm install
   

2. Deploy your app by running:

   1
   2
   forge deploy
   

3. Install your app by running:

   1
   2
   forge install -p bitbucket
   

4. Enter the URL for your workspace. For example, https://bitbucket.org/example-workspace/.

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.

View your app

With your app installed, it’s time to see the app on a repository.

1. Create a new Bitbucket repository if you haven't already. See Creating a repository for more information.
2. Navigate to the source page in the repository. Your app should appear in the bottom of the Repository details pane on the right:

Deploy app changes

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 allows you to speed up development by avoiding the need to redeploy each code change, and by seeing each invocation as it executes. The Forge tunnel works similarly to hot reloading, so any changes you make to your app code can be viewed on your Atlassian site or Bitbucket workspace without losing the current app state. You don’t need to run any other commands; you only need to refresh the page.

To use the forge tunnel command, Docker must be set up and running. To learn about Docker, visit the Docker getting started guides. If you don't want to run Docker, you can redeploy your app after each code change with the forge deploy command.

1. Once Docker is set up, you can start tunneling by running:

   1
   2
   forge tunnel
   

   You should see output similar to:

   1
   2
   Running your app locally with Docker. The tunnel displays your usage from everywhere
   the app in the development environment is installed.
   Press Ctrl+C to cancel.
   
   Checking Docker image... 100%
   Your Docker image is up to date.
   
   Listening for requests on local port 37363...
   
   Reloading code...
   App code reloaded.
   

   You can now automatically deploy changes to your codebase and install packages, while tunneling. These changes appear on the Atlassian site or Bitbucket workspace where your app is installed.

2. When you are ready to close the tunnel, press Control + C.

Next step

In the next tutorial, you'll learn how to make API calls to Bitbucket using Forge. This tutorial uses the forge tunnel, so make sure you are familiar with using this command.