# Forge 生产环境部署

## 1. 安装 Forge 环境

按照 Atlassian 官方文档安装 Node.js、Forge CLI 并完成登录：

- [Forge 入门与开发环境配置](https://developer.atlassian.com/platform/forge/getting-started/)

确认环境可用：

```powershell
node --version
forge --version
```

所有后续命令都需要在包含 `manifest.yml` 的项目根目录执行。

## 2. Forge 授权登录

执行 Forge 登录命令：

```powershell
forge login
```

根据命令提示输入 Atlassian 账户邮箱和 API Token。API Token 可以在 [Atlassian API tokens](https://id.atlassian.com/manage-profile/security/api-tokens) 页面创建。

登录完成后检查当前授权账户：

```powershell
forge whoami
```

确认返回的 Atlassian 账户正确后再继续注册或部署。

## 3. 注册应用

只有首次使用该源码注册新 Forge 应用才执行：

```powershell
forge register jsm-custom-field-plugin
```

`forge register` 会生成新的 Forge App ID，并自动写入 `manifest.yml`。不要在日常部署或升级时重复执行该命令。重复注册会生成另一个 App ID，并使项目与原 App ID 下的环境变量、存储和安装记录断开。

## 4. 检查 manifest.yml 中的 App ID

确认 `manifest.yml` 中存在正确的生产应用 App ID：

```yaml
app:
  id: ari:cloud:ecosystem::app/<app-id>
```

如果该应用已经在生产环境注册过，应将这里的值与已有生产应用的 App ID 核对一致。

## 5. 修改生产 API Base URL

将 `manifest.yml` 中 `remotes.baseUrl` 修改为真实的生产 API 地址：

```yaml
remotes:
  - key: jsm-syncer-staging
    baseUrl: https://<production-api-base-url>
    operations:
      - compute
```

`baseUrl` 不要以 `/` 结尾。保持现有 remote `key` 不变，因为后端代码通过该 key 调用远程服务。

## 6. 部署前检查

```powershell
npm install
npm run build
forge lint
```

所有检查通过后再进行生产部署。

## 7. 部署到生产环境

```powershell
forge deploy -e production
```

部署只负责将代码和 manifest 版本上传到 Forge，不会自动把应用安装到 Jira 站点。

## 8. 首次安装到生产站点

```powershell
forge install -e production
```

根据提示选择 Jira 产品和目标 Atlassian 站点。

## 9. 查看安装记录和 Installation ID

```powershell
forge install list
```

## 10. 后续升级

### manifest.yml 没有变更

如果只修改了 JavaScript、UI 或业务逻辑，且 `manifest.yml` 没有任何变更，只需要重新部署：

```powershell
forge deploy -e production
```

不需要再次执行 `forge install`。

### manifest.yml 有变更

如果修改了模块、权限 scopes、remote、egress、资源声明或其他 `manifest.yml` 配置，先部署：

```powershell
forge deploy -e production
```

再升级生产站点上的现有安装：

```powershell
forge install -e production --upgrade
```