Skip to content

AI-native knowledge base & Evernote/Obsidian alternative with instant sync & native MCP. Free on Cloudflare or self-hosted via Docker.

fix(deploy): make fork upstream sync a readable deploy mirror

tianma-ifee49d280ec69
diff --git a/.github/workflows/sync-edgeever-upstream.yml b/.github/workflows/sync-edgeever-upstream.yml
index c97103a2..dee6c717 100644
--- a/.github/workflows/sync-edgeever-upstream.yml
+++ b/.github/workflows/sync-edgeever-upstream.yml
@@ -1,18 +1,28 @@
name: Update deployed EdgeEver
+# Keeps a deployment Fork aligned with upstream EdgeEver.
+# 99.99% of forks never change application code — they only need a stable
+# mirror of the official release (or edge main) plus a Cloudflare rebuild.
+# Customized forks still merge when needed and fail closed on conflicts.
+
on:
schedule:
- cron: "17 2 * * *"
workflow_dispatch:
inputs:
channel:
- description: Update channel for this run
+ description: Update channel for this run (stable = latest formal Release, edge = upstream main)
required: true
default: stable
type: choice
options:
- stable
- edge
+ force_redeploy:
+ description: When already on the target version, push an empty commit so Cloudflare Builds runs again
+ required: false
+ default: false
+ type: boolean
permissions:
contents: write
@@ -32,6 +42,7 @@ jobs:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
UPSTREAM_REPOSITORY: tianma-if/edgeever
UPDATE_CHANNEL: ${{ inputs.channel || vars.EDGE_EVER_UPDATE_CHANNEL || 'stable' }}
+ FORCE_REDEPLOY: ${{ inputs.force_redeploy || false }}
steps:
- name: Checkout deployed repository
@@ -73,50 +84,162 @@ jobs:
esac
target_commit="$(git rev-parse "${target_ref}^{commit}")"
- if git merge-base --is-ancestor "${target_commit}" HEAD; then
+ head_commit="$(git rev-parse HEAD)"
+ target_version="$(git show "${target_commit}:package.json" | python3 -c 'import json,sys; print(json.load(sys.stdin).get("version",""))' 2>/dev/null || true)"
+ if [ -z "${target_version}" ]; then
+ target_version="unknown"
+ fi
+ head_version="$(python3 -c 'import json; print(json.load(open("package.json")).get("version",""))' 2>/dev/null || true)"
+ if [ -z "${head_version}" ]; then
+ head_version="unknown"
+ fi
+
+ # Product content diff ignores only this updater workflow so deploy
+ # forks that only differ in history or the updater file can reset.
+ content_diff="$(git diff --name-only "${target_commit}" HEAD -- ':!.github/workflows/sync-edgeever-upstream.yml' || true)"
+
+ root_commit="$(git rev-list --max-parents=0 HEAD | head -n 1)"
+ root_subject="$(git show -s --format=%s "${root_commit}")"
+ non_workflow_changes="$(git diff --name-only "${root_commit}" HEAD -- ':!.github/workflows/sync-edgeever-upstream.yml' || true)"
+ bootstrap_import=false
+ if [ "${root_subject}" = "source repo import" ] && [ -z "${non_workflow_changes}" ]; then
+ bootstrap_import=true
+ fi
+
+ update_required=false
+ align_mode=none
+ reason=""
+ republish_only=false
+
+ if [ -z "${content_diff}" ]; then
update_required=false
- bootstrap_required=false
- else
+ align_mode=none
+ if [ "${head_commit}" = "${target_commit}" ]; then
+ reason=already_on_target
+ else
+ reason=content_matches_target
+ fi
+ if [ "${FORCE_REDEPLOY}" = "true" ]; then
+ republish_only=true
+ fi
+ elif git merge-base --is-ancestor HEAD "${target_commit}" 2>/dev/null; then
+ # Strictly behind upstream target — safe fast-forward via reset.
update_required=true
- bootstrap_required=false
-
- # Cloudflare Deploy buttons create a fresh repository with a
- # synthetic `source repo import` commit instead of preserving the
- # upstream Git history. The first update must connect that import
- # history to upstream before normal merges can work. Only do this
- # automatically when the downstream repository contains no changes
- # beyond the updater workflow itself; otherwise fail closed and ask
- # the owner to resolve the customized repository manually.
- root_commit="$(git rev-list --max-parents=0 HEAD)"
- root_subject="$(git show -s --format=%s "${root_commit}")"
- non_workflow_changes="$(git diff --name-only "${root_commit}" HEAD -- ':!.github/workflows/sync-edgeever-upstream.yml')"
- if [ "${root_subject}" = "source repo import" ] && [ -z "${non_workflow_changes}" ]; then
- bootstrap_required=true
+ align_mode=reset
+ reason=behind_target
+ elif [ "${bootstrap_import}" = "true" ]; then
+ # Cloudflare import history with no app customizations.
+ update_required=true
+ align_mode=reset
+ reason=bootstrap_import
+ elif git merge-base --is-ancestor "${target_commit}" HEAD 2>/dev/null; then
+ # Target is already in history but working tree still differs
+ # (should be rare). Prefer merge to preserve any local tip commits.
+ update_required=true
+ align_mode=merge
+ reason=ahead_with_content_drift
+ else
+ # Diverged or unrelated history with real content differences.
+ # Deploy-only forks (only the updater workflow ever changed) reset;
+ # customized forks merge and fail closed on conflicts.
+ if [ -z "${non_workflow_changes}" ] || [ "${bootstrap_import}" = "true" ]; then
+ update_required=true
+ align_mode=reset
+ reason=deploy_mirror_reset
+ else
+ update_required=true
+ align_mode=merge
+ reason=customized_merge
fi
fi
{
echo "target_ref=${target_ref}"
echo "target_commit=${target_commit}"
+ echo "target_version=${target_version}"
+ echo "head_commit=${head_commit}"
+ echo "head_version=${head_version}"
echo "update_required=${update_required}"
- echo "bootstrap_required=${bootstrap_required}"
+ echo "align_mode=${align_mode}"
+ echo "reason=${reason}"
+ echo "republish_only=${republish_only}"
} >> "${GITHUB_OUTPUT}"
- - name: Merge upstream update
+ {
+ echo "### EdgeEver upstream sync"
+ echo ""
+ echo "| Field | Value |"
+ echo "| --- | --- |"
+ echo "| Channel | \`${UPDATE_CHANNEL}\` |"
+ echo "| Upstream target | \`${target_ref}\` (\`${target_commit:0:12}\`, v${target_version}) |"
+ echo "| Fork main before | \`${head_commit:0:12}\` (v${head_version}) |"
+ echo "| Decision | \`${reason}\` / align=\`${align_mode}\` / update=\`${update_required}\` / republish=\`${republish_only}\` |"
+ echo ""
+ case "${reason}" in
+ already_on_target)
+ echo "**Already on upstream target.** No git update is needed. This is success for a read-only deployment fork — not a skipped failure."
+ ;;
+ content_matches_target)
+ echo "**Application content already matches upstream target** (history tip may differ). No git update is needed for deployment."
+ ;;
+ behind_target)
+ echo "**Fork is behind upstream.** Aligning with a hard reset to the target commit (deploy-mirror path)."
+ ;;
+ bootstrap_import)
+ echo "**Cloudflare import history detected.** Resetting onto upstream target so the fork becomes a normal EdgeEver history."
+ ;;
+ deploy_mirror_reset)
+ echo "**Deploy-only fork with diverged history.** Resetting onto upstream target."
+ ;;
+ customized_merge|ahead_with_content_drift)
+ echo "**Local application changes detected.** Merging upstream target and leaving production unchanged if verification fails."
+ ;;
+ *)
+ echo "Decision reason: \`${reason}\`."
+ ;;
+ esac
+ if [ "${republish_only}" = "true" ]; then
+ echo ""
+ echo "\`force_redeploy\` is set: will push an empty commit so Cloudflare Workers Builds runs again."
+ fi
+ echo ""
+ echo "Prefer this workflow over GitHub **Sync fork**. Sync fork tracks upstream \`main\` history and can make the next stable run look like a no-op even when you expected a merge step to run."
+ } >> "${GITHUB_STEP_SUMMARY}"
+
+ echo "channel=${UPDATE_CHANNEL} target=${target_ref}@${target_commit:0:12} (v${target_version}) head=${head_commit:0:12} (v${head_version}) reason=${reason} align=${align_mode} update=${update_required} republish=${republish_only}"
+
+ - name: Align to upstream
if: steps.upstream.outputs.update_required == 'true'
env:
TARGET_COMMIT: ${{ steps.upstream.outputs.target_commit }}
TARGET_REF: ${{ steps.upstream.outputs.target_ref }}
- BOOTSTRAP_REQUIRED: ${{ steps.upstream.outputs.bootstrap_required }}
+ ALIGN_MODE: ${{ steps.upstream.outputs.align_mode }}
+ REASON: ${{ steps.upstream.outputs.reason }}
run: |
+ set -euo pipefail
git config user.name "edgeever-updater[bot]"
git config user.email "edgeever-updater[bot]@users.noreply.github.com"
- if [ "${BOOTSTRAP_REQUIRED}" = "true" ]; then
- git merge --allow-unrelated-histories --no-edit -X theirs \
- -m "chore: initialize EdgeEver history from ${TARGET_REF}" "${TARGET_COMMIT}"
- else
- git merge --no-edit -m "chore: update EdgeEver from ${TARGET_REF}" "${TARGET_COMMIT}"
- fi
+
+ case "${ALIGN_MODE}" in
+ reset)
+ git reset --hard "${TARGET_COMMIT}"
+ git clean -fd
+ echo "Reset main onto ${TARGET_REF} (${TARGET_COMMIT:0:12}) because ${REASON}."
+ ;;
+ merge)
+ if ! git merge --no-edit -m "chore: update EdgeEver from ${TARGET_REF}" "${TARGET_COMMIT}"; then
+ git merge --abort || true
+ echo "Merge from ${TARGET_REF} conflicted with local application changes." >&2
+ echo "Resolve the customized fork manually, or reset main to upstream if you do not need local code changes." >&2
+ exit 1
+ fi
+ echo "Merged ${TARGET_REF} (${TARGET_COMMIT:0:12}) because ${REASON}."
+ ;;
+ *)
+ echo "Unsupported align mode: ${ALIGN_MODE}" >&2
+ exit 1
+ ;;
+ esac
- name: Set up Bun
if: steps.upstream.outputs.update_required == 'true'
@@ -127,6 +250,7 @@ jobs:
- name: Verify update
if: steps.upstream.outputs.update_required == 'true'
run: |
+ set -euo pipefail
bun install --frozen-lockfile
bun run db:migrate:local
bun test
@@ -134,8 +258,87 @@ jobs:
bun run build
- name: Publish update
- if: steps.upstream.outputs.update_required == 'true'
- run: git push origin HEAD:main
+ id: publish
+ if: steps.upstream.outputs.update_required == 'true' || steps.upstream.outputs.republish_only == 'true'
+ env:
+ TARGET_REF: ${{ steps.upstream.outputs.target_ref }}
+ UPDATE_REQUIRED: ${{ steps.upstream.outputs.update_required }}
+ REPUBLISH_ONLY: ${{ steps.upstream.outputs.republish_only }}
+ ALIGN_MODE: ${{ steps.upstream.outputs.align_mode }}
+ run: |
+ set -euo pipefail
+ git config user.name "edgeever-updater[bot]"
+ git config user.email "edgeever-updater[bot]@users.noreply.github.com"
+
+ if [ "${REPUBLISH_ONLY}" = "true" ] && [ "${UPDATE_REQUIRED}" != "true" ]; then
+ git commit --allow-empty -m "chore: retrigger EdgeEver deployment for ${TARGET_REF}"
+ git push origin HEAD:main
+ echo "mode=empty_commit" >> "${GITHUB_OUTPUT}"
+ echo "Pushed empty commit to retrigger Cloudflare Workers Builds."
+ exit 0
+ fi
+
+ if [ "${ALIGN_MODE}" = "reset" ]; then
+ # Deploy mirrors may rewrite short import/divergent history.
+ git push --force-with-lease origin HEAD:main
+ echo "mode=force_with_lease" >> "${GITHUB_OUTPUT}"
+ echo "Published reset main for ${TARGET_REF}."
+ else
+ git push origin HEAD:main
+ echo "mode=push" >> "${GITHUB_OUTPUT}"
+ echo "Published merge for ${TARGET_REF}."
+ fi
+
+ - name: Trigger Cloudflare Deploy Hook
+ if: steps.publish.outcome == 'success'
+ env:
+ DEPLOY_HOOK_URL: ${{ secrets.EDGE_EVER_CLOUDFLARE_DEPLOY_HOOK_URL }}
+ run: |
+ set -euo pipefail
+ if [ -z "${DEPLOY_HOOK_URL:-}" ]; then
+ echo "No EDGE_EVER_CLOUDFLARE_DEPLOY_HOOK_URL secret — relying on Cloudflare Git integration for main pushes."
+ echo "Optional: add a Workers/Pages Deploy Hook secret if pushes do not start builds." >> "${GITHUB_STEP_SUMMARY}"
+ exit 0
+ fi
+ curl -fsS -X POST "${DEPLOY_HOOK_URL}" >/dev/null
+ echo "Triggered Cloudflare Deploy Hook."
+ echo "" >> "${GITHUB_STEP_SUMMARY}"
+ echo "Triggered optional Cloudflare Deploy Hook after publish." >> "${GITHUB_STEP_SUMMARY}"
+
+ - name: Final status
+ if: always() && steps.upstream.outcome == 'success'
+ env:
+ TARGET_REF: ${{ steps.upstream.outputs.target_ref }}
+ TARGET_COMMIT: ${{ steps.upstream.outputs.target_commit }}
+ TARGET_VERSION: ${{ steps.upstream.outputs.target_version }}
+ UPDATE_REQUIRED: ${{ steps.upstream.outputs.update_required }}
+ REPUBLISH_ONLY: ${{ steps.upstream.outputs.republish_only }}
+ REASON: ${{ steps.upstream.outputs.reason }}
+ ALIGN_MODE: ${{ steps.upstream.outputs.align_mode }}
+ run: |
+ set -euo pipefail
+ final_commit="$(git rev-parse HEAD)"
+ {
+ echo ""
+ echo "### Result"
+ echo ""
+ echo "| Field | Value |"
+ echo "| --- | --- |"
+ echo "| Final main | \`${final_commit:0:12}\` |"
+ echo "| Target | \`${TARGET_REF}\` / v${TARGET_VERSION} |"
+ if [ "${UPDATE_REQUIRED}" = "true" ]; then
+ echo "| Outcome | Updated and published (\`${ALIGN_MODE}\`) |"
+ echo ""
+ echo "Cloudflare Workers Builds should deploy this commit from \`main\`. Confirm the Deployment commit SHA matches \`${final_commit:0:12}\`."
+ elif [ "${REPUBLISH_ONLY}" = "true" ]; then
+ echo "| Outcome | Republished empty commit for redeploy |"
+ else
+ echo "| Outcome | Already aligned (\`${REASON}\`) — no push |"
+ echo ""
+ echo "If the live site still shows an older version while Git is current, open Cloudflare **Deployments** and retry the latest build, or re-run this workflow with **force_redeploy**."
+ fi
+ } >> "${GITHUB_STEP_SUMMARY}"
+ echo "final=${final_commit:0:12} reason=${REASON} update=${UPDATE_REQUIRED} republish=${REPUBLISH_ONLY}"
- name: Report an update failure
if: failure()
@@ -143,10 +346,11 @@ jobs:
env:
TARGET_REF: ${{ steps.upstream.outputs.target_ref || 'unknown' }}
run: |
+ set -euo pipefail
title="EdgeEver automatic update requires attention"
existing="$(gh issue list --state open --search "${title} in:title" --json number --jq '.[0].number // empty')"
if [ -z "${existing}" ]; then
gh issue create \
--title "${title}" \
- --body "The daily update from \`${UPSTREAM_REPOSITORY}\` (${TARGET_REF}) could not be merged or verified. The current production deployment was left unchanged. Open the failed **Update deployed EdgeEver** workflow run for details, then retry it manually after resolving the problem."
+ --body "The daily update from \`${UPSTREAM_REPOSITORY}\` (${TARGET_REF}) could not be aligned or verified. The current production deployment was left unchanged. Open the failed **Update deployed EdgeEver** workflow run for details (see the job summary for channel/target/reason), then retry it manually after resolving the problem."
fi
diff --git a/docs/agent-deploy-cloudflare.md b/docs/agent-deploy-cloudflare.md
index 84cd9a91..d79e3cd4 100644
--- a/docs/agent-deploy-cloudflare.md
+++ b/docs/agent-deploy-cloudflare.md
@@ -12,7 +12,7 @@ This document defines the standard operating specifications and conventions for
- Fork `tianma-if/edgeever` to the target GitHub account.
2. **Enable Workflow**
- - In the **Actions** tab of the Forked repository, enable the **Update deployed EdgeEver** automatic update workflow.
+ - In the **Actions** tab of the Forked repository, enable the **Update deployed EdgeEver** automatic update workflow (required on public forks: scheduled workflows are disabled by default).
3. **Cloudflare Project Import**
- Log into the Cloudflare **Workers & Pages** console and import the Fork repository.
@@ -42,4 +42,7 @@ This document defines the standard operating specifications and conventions for
- Verify login API using the configured `EDGE_EVER_AUTH_USERNAME` (default `admin`) and `EDGE_EVER_AUTH_PASSWORD`.
7. **Verify Upstream Update Channel**
- - Manually trigger **Update deployed EdgeEver** once in the Fork's **Actions** tab to confirm upstream synchronization and automated builds work properly.
+ - Manually trigger **Update deployed EdgeEver** once in the Fork's **Actions** tab.
+ - Open the job **Summary** and confirm it reports the upstream target (stable Release or edge `main`) and either an update publish or an explicit *already aligned* result.
+ - Confirm Cloudflare **Deployments** builds the published `main` commit when a push occurred.
+ - Do not rely on GitHub **Sync fork** for routine upgrades; use this workflow as the deploy-mirror path.
diff --git a/docs/agent-deploy-cloudflare.zh-CN.md b/docs/agent-deploy-cloudflare.zh-CN.md
index eb0f6754..ca760e7f 100644
--- a/docs/agent-deploy-cloudflare.zh-CN.md
+++ b/docs/agent-deploy-cloudflare.zh-CN.md
@@ -12,7 +12,7 @@
- Fork `tianma-if/edgeever` 到目标 GitHub 账户。
2. **启用工作流**
- - 在 Fork 仓库的 **Actions** 标签页中,启用 **Update deployed EdgeEver** 自动更新工作流。
+ - 在 Fork 仓库的 **Actions** 标签页中,启用 **Update deployed EdgeEver** 自动更新工作流(公共 Fork 上定时任务默认关闭,必须手动启用)。
3. **Cloudflare 项目导入**
- 登录 Cloudflare **Workers & Pages** 控制台,导入该 Fork 仓库。
@@ -42,4 +42,7 @@
- 使用之前配置的 `EDGE_EVER_AUTH_USERNAME`(默认 `admin`)和 `EDGE_EVER_AUTH_PASSWORD` 验证登录 API 是否可用。
7. **验证上游更新通道**
- - 在 Fork 的 **Actions** 中手动运行一次 **Update deployed EdgeEver**,确认上游同步与构建更新流程畅通。
+ - 在 Fork 的 **Actions** 中手动运行一次 **Update deployed EdgeEver**。
+ - 打开 Job **Summary**,确认已显示上游目标(stable Release 或 edge `main`),以及「已发布更新」或明确的「已对齐」结果。
+ - 若发生了 push,确认 Cloudflare **Deployments** 构建的是对应的 `main` commit。
+ - 日常升级不要依赖 GitHub **Sync fork**,请以本工作流作为部署镜像同步路径。
diff --git a/docs/cloudflare-workers-builds.md b/docs/cloudflare-workers-builds.md
index c0821d10..c440d578 100644
--- a/docs/cloudflare-workers-builds.md
+++ b/docs/cloudflare-workers-builds.md
@@ -13,9 +13,13 @@ Authorization:
## Updates and troubleshooting
- A push to `main` builds, applies D1 migrations, deploys, and verifies EdgeEver.
-- **Update deployed EdgeEver** checks the latest formal Release daily.
-- Set the GitHub Repository Variable `EDGE_EVER_UPDATE_CHANNEL=edge` to follow upstream `main`.
-- Build failure: inspect the Worker **Deployments** log.
-- Scheduled update failure: enable and run the workflow from the Fork's **Actions** tab.
-
-Legacy Cloudflare-created repositories with only a `source repo import` commit are bootstrapped on their first update. Do not use this bootstrap path after custom application changes.
+- **Update deployed EdgeEver** keeps a deployment Fork as an upstream **deploy mirror**:
+ - Default channel `stable` tracks the latest formal Release tag.
+ - Set the GitHub Repository Variable `EDGE_EVER_UPDATE_CHANNEL=edge` to follow upstream `main`.
+ - Read-only forks (no app code changes) **reset** onto the target when behind; customized forks **merge** and fail closed on conflicts.
+ - Every run writes a job **Summary** with channel, target version, decision reason, and whether a push happened. A green run that says *Already on upstream target* is success, not a silent failure.
+ - Prefer this workflow over GitHub **Sync fork**. Sync fork follows upstream `main` history and can make the next stable run a deliberate no-op.
+- Optional: repository secret `EDGE_EVER_CLOUDFLARE_DEPLOY_HOOK_URL` triggers a Cloudflare Deploy Hook after a successful push (useful when the Git integration misses a push).
+- Optional: re-run the workflow with **force_redeploy** to push an empty commit when Git is already current but Cloudflare needs another build.
+- Build failure: inspect the Worker **Deployments** log and confirm the Deployment commit SHA matches Fork `main`.
+- Scheduled update never runs: on a public Fork, enable **Update deployed EdgeEver** under **Actions** (scheduled workflows are disabled by default on forks, and may pause after long inactivity).
diff --git a/docs/cloudflare-workers-builds.zh-CN.md b/docs/cloudflare-workers-builds.zh-CN.md
index 077a1508..76c39574 100644
--- a/docs/cloudflare-workers-builds.zh-CN.md
+++ b/docs/cloudflare-workers-builds.zh-CN.md
@@ -13,9 +13,13 @@
## 更新与排错
- `main` 推送会自动构建、执行 D1 migration、部署并验证。
-- **Update deployed EdgeEver** 工作流每天检查上游正式 Release。
-- 设置 GitHub Repository Variable `EDGE_EVER_UPDATE_CHANNEL=edge` 后跟随上游 `main`。
-- 构建失败:查看 Worker 的 **Deployments** 日志。
-- 定时更新失败:在 Fork 的 **Actions** 中启用并手动运行工作流。
-
-旧的 Cloudflare 创建仓库如果只有 `source repo import` 提交,第一次更新会自动建立上游历史。已经修改过应用代码的仓库不要直接使用该初始化流程。
+- **Update deployed EdgeEver** 把部署用 Fork 当作上游的 **部署镜像** 来维护:
+ - 默认 `stable` 通道跟随最新正式 Release tag。
+ - 设置 GitHub Repository Variable `EDGE_EVER_UPDATE_CHANNEL=edge` 后跟随上游 `main`。
+ - 只读 Fork(未改应用代码)在落后时会 **reset** 到目标版本;有本地业务改动的 Fork 走 **merge**,冲突则失败并保持线上不变。
+ - 每次运行都会写 Job **Summary**:通道、目标版本、判定原因、是否 push。若 Summary 写明 *Already on upstream target* / 已对齐,绿色成功表示「已是目标版本」,不是静默故障。
+ - 请优先用本工作流,而不是 GitHub **Sync fork**。Sync fork 跟的是上游 `main` 历史,可能让下一次 stable 运行合理变为 no-op。
+- 可选:仓库 Secret `EDGE_EVER_CLOUDFLARE_DEPLOY_HOOK_URL`,在成功 push 后触发 Cloudflare Deploy Hook(Git 集成偶发未构建时有用)。
+- 可选:Git 已是最新但 Cloudflare 需要再构建时,手动运行工作流并勾选 **force_redeploy**(会推送空 commit)。
+- 构建失败:查看 Worker **Deployments** 日志,确认部署 commit SHA 与 Fork `main` 一致。
+- 定时任务从不运行:公共 Fork 需在 **Actions** 中启用 **Update deployed EdgeEver**(Fork 上 schedule 默认禁用,长期不活跃也可能被暂停)。
diff --git a/docs/deploy-cloudflare-button.md b/docs/deploy-cloudflare-button.md
index 17b5d9e4..f9d40179 100644
--- a/docs/deploy-cloudflare-button.md
+++ b/docs/deploy-cloudflare-button.md
@@ -85,16 +85,23 @@ The deploy command automatically looks up the D1 UUID by the `edgeever` database
## Advanced Configuration: Update Channels
-By default, deployments follow official stable Release tags. If you want to follow the latest `main` branch (Edge preview builds), add the following environment variable in Cloudflare under **Settings** -> **Variables and Bindings**:
+By default, **Update deployed EdgeEver** follows official stable Release tags. To follow upstream `main` (Edge preview builds), set this **GitHub Repository Variable** on the Fork (**Settings → Secrets and variables → Actions → Variables**):
```text
EDGE_EVER_UPDATE_CHANNEL=edge
```
+You can also pick `stable` / `edge` when manually running the workflow.
+
---
## Troubleshooting
- **Initial build failed**: Check the Worker **Deployments** log. Verify that the D1 binding is `DB`, its database is named exactly `edgeever`, the R2 binding is `RESOURCES`, and the Workers Builds API token has D1 read/edit permission. For an intentionally different D1 database, add the build variable `EDGE_EVER_D1_DATABASE_ID` with its UUID.
-- **Updates not syncing**: Navigate to your Fork's **Actions** tab, verify **Update deployed EdgeEver** is enabled, and try clicking **Run workflow** manually.
+- **Updates not syncing**:
+ 1. On the Fork **Actions** tab, enable **Update deployed EdgeEver** (scheduled workflows are off by default on public forks).
+ 2. Run it once with **Run workflow**. Open the job **Summary**: it states the upstream target version and whether the fork was updated, already aligned, or failed.
+ 3. A green run with *Already on upstream target* means Git already matches that channel — not a broken skip. If the live site is still old, check Cloudflare **Deployments** commit SHA, or re-run with **force_redeploy**.
+ 4. Prefer this workflow over GitHub **Sync fork** for day-to-day upgrades.
+- **Push succeeded but site unchanged**: Confirm Workers Builds ran for the new `main` SHA. Optionally add repository secret `EDGE_EVER_CLOUDFLARE_DEPLOY_HOOK_URL` so the workflow can call a Deploy Hook after publish.
- **Reset or Manual Recovery**: See the [Cloudflare Manual Deployment Guide](manual-deploy.md).
diff --git a/docs/deploy-cloudflare-button.zh-CN.md b/docs/deploy-cloudflare-button.zh-CN.md
index 2a2b58f3..fbbc7d6b 100644
--- a/docs/deploy-cloudflare-button.zh-CN.md
+++ b/docs/deploy-cloudflare-button.zh-CN.md
@@ -85,16 +85,23 @@ Deploy command: bun run deploy:cloudflare-builds
## 高级配置:更新通道设置
-部署默认自动跟随官方正式 Releases(稳定版)。若希望跟进最前沿的 `main` 分支(Edge 预览版),可前往 Cloudflare 的 **Settings** -> **Variables and Bindings** 添加如下环境变量:
+默认情况下,**Update deployed EdgeEver** 跟随官方正式 Release(稳定版)。若希望跟随上游 `main`(Edge 预览版),请在 Fork 仓库设置 **GitHub Repository Variable**(**Settings → Secrets and variables → Actions → Variables**):
```text
EDGE_EVER_UPDATE_CHANNEL=edge
```
+手动运行工作流时也可以直接选择 `stable` / `edge`。
+
---
## 常见问题与排错
- **首次构建失败**:请检查 Cloudflare 控制台中 Worker 的 **Deployments** 构建日志,确认 D1 Binding 为 `DB`、数据库名称严格为 `edgeever`、R2 Binding 为 `RESOURCES`,并确认 Workers Builds API Token 具有 D1 读取和编辑权限。如有意使用其他 D1 数据库,请添加构建变量 `EDGE_EVER_D1_DATABASE_ID` 并填入其 UUID。
-- **无法同步上游更新**:打开您 Fork 仓库的 **Actions** 标签页,确认 **Update deployed EdgeEver** 工作流是否处于已启用状态,并尝试手动点击 **Run workflow**。
+- **无法同步上游更新**:
+ 1. 打开 Fork 的 **Actions**,启用 **Update deployed EdgeEver**(公共 Fork 上定时任务默认关闭)。
+ 2. 手动 **Run workflow** 一次,打开 Job **Summary**:会写明上游目标版本,以及本次是「已更新」「已对齐」还是失败。
+ 3. 若绿色成功且 Summary 为 *Already on upstream target* / 已对齐,表示 Git 已是该通道目标版本,不是静默故障。若网站仍旧,请对照 Cloudflare **Deployments** 的 commit SHA,或勾选 **force_redeploy** 再跑一次。
+ 4. 日常升级请优先用本工作流,而不是 GitHub **Sync fork**。
+- **Git 已 push 但网站没变**:确认 Workers Builds 是否针对新的 `main` SHA 构建。可选:添加仓库 Secret `EDGE_EVER_CLOUDFLARE_DEPLOY_HOOK_URL`,让工作流在 publish 后调用 Deploy Hook。
- **需要重置或手动恢复部署**:请参阅 [手动部署指南](manual-deploy.zh-CN.md)。
diff --git a/tests/deployment-entrypoints.test.ts b/tests/deployment-entrypoints.test.ts
index 0580d30b..a7e9f4e1 100644
--- a/tests/deployment-entrypoints.test.ts
+++ b/tests/deployment-entrypoints.test.ts
@@ -165,12 +165,19 @@ describe("Cloudflare deployment entrypoints", () => {
expect(workflow).toContain("EDGE_EVER_UPDATE_CHANNEL");
expect(workflow).toContain("stable)");
expect(workflow).toContain("edge)");
+ expect(workflow).toContain("force_redeploy");
expect(workflow).toContain("bun run db:migrate:local");
expect(workflow).toContain("bun test");
expect(workflow).toContain("git push origin HEAD:main");
+ expect(workflow).toContain("git push --force-with-lease origin HEAD:main");
+ expect(workflow).toContain("git reset --hard");
expect(workflow).toContain("source repo import");
- expect(workflow).toContain("--allow-unrelated-histories");
+ expect(workflow).toContain("content_matches_target");
+ expect(workflow).toContain("already_on_target");
+ expect(workflow).toContain("GITHUB_STEP_SUMMARY");
+ expect(workflow).toContain("EDGE_EVER_CLOUDFLARE_DEPLOY_HOOK_URL");
expect(workflow).toContain("non_workflow_changes");
+ expect(workflow).toContain("Prefer this workflow over GitHub **Sync fork**");
});
test("public deployment documentation exposes only Fork and Agent paths", () => {