atlassian / atlassian-connect-example-app-node

Atlassian Connect Node Example App

About

This repository contains an example Express server for building an Atlassian Connect app. This app is aimed to help you to easily add your integration in Jira.

Table of Contents

• Pre-requisites
• Getting started
• Manual Install
• Testing
• Getting help
• License

Pre-requisites

• Install Node.js.
• Install yarn (optional).
• Install Docker & Docker Compose.
• Create an ngrok account.
• Create an Atlassian development site.

Getting started

1. Install the dependencies.

   # If use Yarn (recommended)...
   yarn install
   # If use npm...
   npm install

2. Create .env file based on .env.example and set the environment variables.
3. Start the app and install it on Jira. Please be patient as it will take a few minutes for everything to be setup. When everything is set up, you should see the URL in the terminal as in the picture below.

   docker-compose up

   

At the very end, you can see the URL the index page of your app. Just open the URL and that's it, you're ready!

Note: If you are using a free version of ngrok, please open the tunneled URL first. This needs to be done to bypass the ngrok browser warning. Just visit the ngrok warning page and just click on the "Visit" button.

Manually Installing the App

The above steps automatically installs the app, however you can only install one app at a time.

1. Go to your Jira instance.
2. Enable the installation of apps that are not listed on the Atlassian Marketplace.
   1. Go to Apps > Manage your apps.
   2. Click User-installed apps > Settings.
   3. Check Enable development mode and click Apply.
3. Reload the page.
4. Install the app.
   1. Click Upload app.
   2. Paste the link to your Connect descriptor (${APP_URL}/atlassian-connect.json) and click Upload.

That's it! You're done. 🎉

Testing

We have added a basic end to end test for installing and uninstalling the app, using playwright. You can add your own test cases on top of it.

To run the end to end test, please add the values for ATLASSIAN_URL, JIRA_ADMIN_EMAIL and JIRA_ADMIN_API_TOKEN in the .env file. Then simply run yarn test:e2e in the terminal.

Getting help

If you have feedback, found a bug or need some help, please create a new issue in this repo.

License

The project is available as open source under the terms of the MIT License.