> For the complete documentation index, see [llms.txt](https://docs.release.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.release.com/guides-and-examples/common-setup-examples/app-imports-connecting-two-apps-together.md).

# App Imports: Connecting two applications

Release's App Imports functionality allows you to connect two applications with code in different repositories. You can read more about how App Imports is implemented in our [microservices architecture](/guides-and-examples/advanced-guides/microservices-architecture.md) documentation.

Here we'll show you an example of App Imports in action, using two repositories from our [awesome-release](https://github.com/awesome-release) directory:

* The [docker-create-react-app](https://github.com/awesome-release/docker-create-react-app) will act as our frontend application.
* The [rails\_postgres\_redis](https://github.com/awesome-release/rails_postgres_redis) will act as our backend, with worker process provided by [sidekiq](https://github.com/mperham/sidekiq).

### Release's matching branches heuristic

Let's take a moment to understand how Release chooses which branch to use when automatically creating an environment for connected apps with different repositories.

Release will try to match a branch in the imported repository to the name of the importing repository. If there is no match, Release will fall back to either the [`tracking_branch`](/reference-documentation/application-settings/application-template/schema-definition.md#tracking_branch) or the default branch. You can also use the [`tracking_tag`](/reference-documentation/application-settings/application-template/schema-definition.md#tracking_tag).

Here's an example to demonstrate. Say we have RepoA, RepoB, and RepoC with the following branches:

| Repository | Default Branch | Tracking Branch | Other Branches       |
| ---------- | -------------- | --------------- | -------------------- |
| RepoA      | main           | main            | feature-1, feature-2 |
| RepoB      | develop        |                 | feature-2            |
| RepoC      | v5             | bug-1           | feature-1, bug-2     |

* If an automatic environment request for RepoA on `main` is created, Release will select the `develop` default branch for RepoB and the `bug-1` tracking branch for RepoC.
* If an automatic environment request for RepoA on `feature-1` is created, Release will select the `develop` default branch for RepoB and the matching `feature-1` branch for RepoC.
* If an automatic environment request for RepoA on `feature-2` is created, Release will select the `feature-2` matching branch for RepoB and the `bug-1` tracking branch for RepoC.
* If an automatic environment request for RepoB or RepoC is created, the results will be similar depending on how the separate imported apps are designed. For instance, your frontend may always import the backend and a middleware proxy, but the backend will only import the proxy automatically, and not the frontend.

In our example, RepoA imports RepoB and RepoC, but it is not clear how RepoB or RepoC imports the others. If you're importing bi-directionally (or meshed, as in our three-way example), the same heuristic would apply to RepoB, RepoC, and RepoA.

## Fork the repositories on Github

Navigate to the [Release GitHub repository for our frontend application](https://github.com/awesome-release/docker-create-react-app).

Click the **Fork** button in the top right corner of the page to fork the repository.

![](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-3089188cf1faf7b636e0b804bd40858bc1c0e295%2Ffork.jpg?alt=media\&token=df4d9d7f-527c-4153-b196-130829bb2f70)

Do the same for the [GitHub repository for our backend application](https://github.com/awesome-release/rails_postgres_redis).

You will need to grant access to the newly forked repositories. Follow the instructions in [connect your source control provider](/getting-started/quickstart.md#connect-your-source-control-provider) to do so.

## Create the backend application

The first application we'll create will be from the `rails_postgres_redis` repository.

![](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-4e2a22b5ccaca75f94d7f6f216fd560d380d536f%2Frails_postgres_redis_service_selection.png?alt=media\&token=a241a862-fb21-42da-b975-5dbacc6a27cd)

When you've selected the repository, Release presents options for how the services should be run. The `api` service has options for both **Static** (because a `package.json` file was found) and **Docker** (because a Dockerfile was found). Since this is a Rails server, we'll pick **Docker**.

Notice that Release specifies `443` under "Public Port" for our `api` service. We'll use this later when we connect our two applications.

Next we'll name the application. You can give the application any name, but since this repository is the backend API for our example, we'll name it "backend".

![](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-346fbb13ec9289f238f98f173b8a4d97ff01d1d7%2Frails_postgres_redis_backend_name.png?alt=media\&token=6f3daf0b-5fda-436b-b597-ac901439ac86)

Click the **Generate App Template** button to move on to the next screen.

On the Application Template screen, we don't need to make any changes, so you can go ahead and click the **Save & Continue** button.

We don't need to make any changes in the Build & Runtime Configurations page either, so you can click the **Start Build & Deploy** button to finish setting up the backend.

## Create the frontend application

Now we can create an application from the `docker-create-react-app` repository.

![](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-e9a96c5983334a8684f02e4ae6ec4154830afc5f%2Fdocker-create-react-app-service-selection.png?alt=media\&token=2620a58e-496f-4940-9707-5da797f4ea41)

Select the repository and Release will present the options for how the services will be run. This repository has only one service named `app`, which is configured to run in Docker, so we select **Docker**.

![](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-0874f171fc2f8673478e5d49dd5aa674d40ad48a%2Fdocker-create-react-app-name-frontend.png?alt=media\&token=a3bb342d-0b9e-4156-89ae-bd37c340481d)

Name the app – we've named it "frontend" – then click the **Generate App Template** button.

This time, we'll modify the Application Template to connect our applications using the App Imports feature. Click **Edit** to open the Application Template.

![](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-ca66bd20adf451126ba2824646d2beeab2ff0245%2Fapp-imports-backend.png?alt=media\&token=0d962b70-1b33-473e-abb0-18a076bab69f)

At the bottom of the Application Template we've added:

```
app_imports:
- name: backend
```

This tells Release that when we create the `frontend` application, the `backend` application must be imported.

Click **Save & Continue**.

### Add the environment variable

Next we need to add an environment variable to ensure the two applications can talk to each other.

Release automatically generates environment variables in the form of `<SERVICE_NAME>_INGRESS_URL` when the service is exposed to the internet.

When we created our `backend` application, we selected **Docker** for our `api` service, and Release specified that the service is exposed on public port 443. This means we'll have an environment variable in our backend named `API_INGRESS_URL`.

When we use App Imports to connect the applications, the ingress environment variables for `backend` are shared with `frontend`. We need to add a mapping from `API_INGRESS_URL` to the correct environment variable on the frontend. We'll map to the `REACT_APP_BACKEND_API` environment variable, which can be found in the [`api.js`](https://github.com/awesome-release/docker-create-react-app/blob/main/src/api.js#L5) file of the repository.

{% hint style="info" %}
If you'd like to learn more about mapping environment variables, read the section about it in our [guide to environment variables](/reference-documentation/application-settings/default-environment-variables.md#mapping).
{% endhint %}

To add the environment variable, click the **Edit** button in the "Default Environment Variables" section.

![](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-6b7372f02bfd5bffaf0cdcc43f4301641ea0dda2%2Fenvironment-variable-mapping-frontend-backend.png?alt=media\&token=c0d8259b-981b-4154-973e-94f3ebb0c42d)

We added

```
mapping:
  REACT_APP_BACKEND_API: API_INGRESS_URL
```

Now our frontend application will receive the value of `API_INGRESS_URL` as the environment variable `REACT_APP_BACKEND_API`. Click **Save** to close the Default Environment Variables modal and click **Start Build & Deploy**.

## View the deploy

On the App Dashboard page, we can see that a deploy is in progress.

![](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-30df5cde70c3dc3e73abf5a462b1118586f1a3c4%2Fdeploy-activity.png?alt=media\&token=3df145a8-5b10-487a-bba8-15c9488006a8)

Click on `Deploy 3345` to go to the Deploy Info page where you'll see the progress.

![](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-0dd142b41b47be9664297edeef688c9381a2dec2%2Fdeploy-page-app-import.png?alt=media\&token=923d8d6d-3b79-4d26-8edb-af9a768e8464)

Notice that there are four stages to this deployment: Two for the `backend` application and two for the `frontend` application. This tells us that our App Import has worked.

When deployment is complete, you can click on the **Go To Environment** button to view the URLs and ensure that the `frontend` application can talk to the `backend` application.

![](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-9abc418ae0a1742cef7f955a192a454474df5c06%2Fsucessful-deploy.png?alt=media\&token=35dd5524-8a87-4622-8d55-4bb3f0b98509)

On the Environment Details page, we can see the environment for our backend application in the "Namespace" section, and the URL for our frontend application in the "Hostname URLs" section.

![](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-e4c0323e6ba4ed494d4d101ccda39815cdc86ea2%2Fenvironment-details-app-import.png?alt=media\&token=dfe1b991-8708-42e4-9d09-0f1580936efe)

Click on the `app` link to go to the live Release environment.

## View the live application

There isn't much to see when you first visit the live application, but what it's doing is making an API call to the backend to fetch users from the database and display them. Since we don't have any users yet, there are none to display.

![](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-93b764620e77c64b93cebdb4e7c290ae27eaecdb%2Fcreate-react-app-no-users.png?alt=media\&token=6ae55461-3975-4e51-b52b-bc821e3893ee)

Click on the **Create New Users** button to trigger a background job using Sidekiq and Redis to create users. After a short wait, the API to retrieve the users is called again and we can see that the users were successfully created.

![](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-9176f11f94a6733ccfda2d00540f281a3b58b54d%2Fcreate-react-app-users.png?alt=media\&token=fd78f695-172e-44f8-9076-0891b8e0cfdd)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.release.com/guides-and-examples/common-setup-examples/app-imports-connecting-two-apps-together.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.