# Deploy an application

This page walks through deploying a Pilot application to production. Deployment is a guided three-step process managed in the Pilot deployment panel. For building your application, see [Build an application](../build-an-application/index.md). Deploying a custom widget follows a different path: Pilot publishes the widget to the Widget Registry rather than through Developer Console. See [Deploy a custom widget](../deploy-a-widget/index.md).

:::callout{theme="warning"}
Deployment requires permissions at the project, organization, and enrollment levels. You need permission to create and deploy the Developer Console application, create its linked OAuth client, and obtain approval for the subdomain request. The required permissions are typically granted by project `Editor`, organization `Third-party application administrator`, and domain-approval roles; custom role configurations can differ. See the relevant sections below for details, or contact your administrator if you encounter permission errors.
:::

Before deploying, switch to the repository's default code branch. If your changes are on another code branch, merge them into the default branch first. If the panel displays **Deploy on** followed by a branch name, return to the editor and merge your changes into that branch first.

## Editor and deploy views

Pilot has two views for building and releasing your application, toggled from the top-right corner of the workspace.

![The Editor and Deploy view toggle in the top-right corner of the workspace.](../../../assets/bd3a8a391377f938c5749bf8c7843b9f75ad6b184a0538da5132ed0e6b8e6979.webp)

For an overview of editor and deploy views, see [Workspace overview](../workspace-overview/index.md#editor-and-deploy-views).

In editor view, Pilot can display seed data generated inside the Pilot container or use **Production data** when available. Check the data indicator; see [Work with data](../work-with-data/index.md). If your application appears empty in deploy view, verify that the ontology entities have been created on a branch and that the backing datasets contain data.

Your production application always uses real data from the ontology. Seed data from the Pilot container is never deployed and is not accessible in the production application.

:::callout{theme="warning"}
When you preview your application with production data on `Main`, in either editor or deploy view, you are viewing and interacting with production data. Any actions you perform in the application, such as creating or editing objects, are ontology edits that take immediate effect. When previewing on a deployment branch, ontology edits are scoped to that branch and do not propagate to `Main`.
:::

## Check deployability

Before starting the deployment process, verify that your application is ready to deploy. Select the status indicator in the top-right corner of the workspace to open the status monitoring popover. The **Deployability** status reports the result of an Ontology deployment dry run. It can also show **Invalid Ontology** if Pilot cannot load the local Ontology definition.

Check the **Ontology** tab separately for type-checking and edit-permission errors. These errors can remain even when **Deployability** shows **Deployable**. Resolve them before implementing ontology changes; see [Resolve validation errors](../ontology-tab/index.md#resolve-validation-errors).

Check dependency and development-server errors separately. A deployable ontology does not replace the CI checks required for release.

To resolve an error reported by **Deployability**, select the three-dot menu (**...**) next to the **Deployability** status and choose **Fix with Pilot**. Pilot diagnoses the issue and applies a fix automatically. If the issue persists, you can prompt Pilot in the chat panel to describe and resolve the problem.

## Start deployment

Select **Deploy** from the top-right corner of the Pilot workspace to open the deployment panel. The panel presents three steps:

1. Implement ontology entities
2. Configure application and subdomain
3. Pass all CI checks

![The deployment panel showing the three-step checklist and a live preview of the application.](../../../assets/b6757243902dfcbab356383b3643bad2ababc634d52d6f667a6bbb6398424fa0.webp)

## 1. Implement ontology entities

Ontology changes created in the Pilot container must be promoted to the main ontology before the production application can use them. Pilot uses [Global Branching](../../global-branching/overview/index.md) for this process. Global Branching lets you make ontology changes on an isolated branch, test them against real data, and merge to `Main` without affecting production until you are ready.

If your application only references deployed entities without modifications, this step may already show **All entities up to date on Main**. Code branches and Ontology deployment branches are separate; see [Work with data](../work-with-data/index.md#code-branches-and-ontology-branches).

### Create a deployment branch

In the **Implement ontology entities** step, Pilot displays which entities need to be created on a branch, including object types, action types, and link types.

Global Branching must be enabled on your enrollment. If **Create branch** is disabled with an application-access message, ask your platform administrator to enable Global Branching.

1. Select **Create branch** to generate a deployment branch containing these ontology changes.
2. Enter a branch name and confirm.

Once created, Pilot pushes ontology definitions to the branch and starts indexing. Indexing makes the object types and actions available on the branch so you can preview your application against real data in the deploy view and perform actions before merging to `Main`.

All object types edited by an action must be indexed on the branch before testing that action. External side effects have separate restrictions; see [Branching action types](../../action-types/branching-action-types/index.md).

If branch creation fails, inspect the branch-creation error, check the **Deployability** status for dry-run errors, and check the **Ontology** tab separately for type-checking or edit-permission errors. You can also try creating a new branch with a different name.

### Review and merge through Global Branching

After the branch is created, review and merge the ontology changes.

1. Select **View branch** to open Global Branching, where you can see the resources on the branch and their state.
2. Select **Create proposal** and enter a proposal name and optional description.
3. Select **Create** to submit the proposal.
4. Once checks pass, select **Merge proposal** to apply the ontology entities to `Main`.

Depending on your enrollment configuration, proposal approval may be automatic or may require manual review by a user with the appropriate permissions.

Object edits made while testing actions on the branch are not merged into `Main`.

After the merge completes, Pilot prompts you to switch back to `Main`. The **Implement ontology entities** step then shows all entities as up to date.

## 2. Configure application and subdomain

With ontology entities on `Main`, you can configure the hosted application that will serve your generated UI.

### Create the Developer Console application

In the **Configure application and subdomain** step, select **Configure application**. A dialog appears with the following fields:

1. **Developer Console application name:** Pilot suggests a name tied to your Pilot project.
2. **Organization:** Select the organization where the application will live.
3. **Subdomain:** Choose a subdomain for your application. Pilot checks availability and the resulting URL follows the pattern `<subdomain>.<enrollment>.palantirfoundry.com`.

Select **Create application** to proceed. Pilot creates the [Developer Console](../../developer-console/overview/index.md) application record and defines the application's restrictions, automatically including the relevant object types and action types. Creating a Developer Console application requires [specific permissions](../../developer-console/permissions/index.md).

### Approve the subdomain request

Subdomain registration requires approval through Control Panel. An enrollment administrator must navigate to **Control Panel > Approvals** and complete the following:

1. Review the subdomain request details, including the Foundry domain, requested subdomain, and the hosted application.
2. Select **Approve**.

Once approved, the hosted domain is registered and mapped to the Developer Console application. Back in Pilot, the **Configure application and subdomain** step confirms that the application's restrictions are up to date.

Subdomain approval timelines vary by enrollment, and on some enrollments subdomain registration may require additional security review. If you are blocked waiting for approval, contact your enrollment administrator.

## 3. Run CI checks and release

With ontology entities implemented and the Developer Console application configured, you can generate deployment files and release your application.

### Generate deployment files

In the **Pass all CI checks** step, select **Generate deployment files to enable checks**, or **Update files** if the panel reports outdated files. Pilot generates CI and environment configuration files into your repository, including:

* `.env.production`
* `ci.yml`
* `foundry.config.json`
* Additional build and settings scripts

Pilot then builds a production-ready artifact using the generated configuration. CI checks start automatically.

On a protected code branch, use **Create a branch with deployment files to enable checks** or **Update files on a branch**, then review and merge the code proposal. Commit pending changes before release.

### Failing CI checks

If CI checks fail, try the following:

1. Inspect the failed check or build output. If deployment files are missing or outdated, select the generation or **Update files** control shown in the panel.
2. Switch to editor view and prompt Pilot to fix the build error. For example, `The CI checks are failing. Can you check the build output and fix any errors?`
3. After Pilot applies a fix, save the changes and merge the code proposal if required. Switch back to the deploy view and wait for checks on the resulting commit to pass.

### Tag and release

When CI checks pass, you can tag and release the application.

1. Select **Tag and release**.
2. In the **Tag and release** dialog:
   * Confirm the **Branch** or specific commit.
   * Choose a version type: **Patch** for backward-compatible fixes, **Minor** for additive changes, **Major** for breaking changes, or **Custom** for a custom tag.
   * Select **Tag and release** to start the release.

Pilot tracks the release progress and surfaces a confirmation when the tag is created. Follow the release build to completion; creating a tag does not confirm that the hosted application is available. Use **View build** to inspect failures.

## Open your production application

After the release build succeeds and the subdomain is approved, select **View app** to open the newly deployed application at your subdomain.

The first time you visit, you are prompted with an OAuth consent screen. Select **Allow** to grant the Developer Console application access to the required ontology entities and media datasets. You then land in your production application, which operates on real data through the ontology.

Review the submission criteria for actions created by Pilot. The default criteria allow only the user who created the action to submit it. Configure the intended access in Ontology Manager before asking other users to test the application.

## After deployment

After your application is deployed, you can continue iterating in Pilot.

1. Switch to the **Editor** view and make changes through follow-up prompts, just as you did during the initial build.
2. When you are ready to release an update, switch to the **Deploy** view.
3. If your changes include new or modified ontology entities, implement the changes on a deployment branch, merge through Global Branching, and tag a new release.
4. If your changes are code-only (no ontology modifications), merge them into the default code branch, update deployment files if prompted, pass CI checks, and tag a new release.