7.6 KiB

Raw Blame History

Feishu Integration

gitlink-cli feishu exports local GitLink workflow JSON to Feishu.

The stable command path is intentionally narrow:

workflow JSON -> local preview
workflow JSON -> Feishu custom bot card
workflow JSON -> weekly report
workflow JSON -> owner / contributor digest
workflow JSON -> Bitable schema / records dry-run
workflow JSON -> task candidates

Stable Commands

gitlink-cli feishu +bot-test
gitlink-cli feishu +notify
gitlink-cli feishu +weekly-report
gitlink-cli feishu +owner-digest
gitlink-cli feishu +contributor-digest
gitlink-cli feishu +bitable-schema
gitlink-cli feishu +bitable-records
gitlink-cli feishu +task-preview

Experimental commands:

gitlink-cli feishu +doc-export
gitlink-cli feishu +bitable-sync
gitlink-cli feishu +task-create

Experimental commands use Feishu self-built app OpenAPI and are not part of the stable custom-bot path.

Safety Model

Default behavior is local preview.
Real Feishu bot delivery requires --send.
--send and --dry-run cannot be used together.
Webhook URLs are redacted in command output.
Secrets and tokens are never intentionally printed.
The stable commands do not write to GitLink resources.
+bitable-schema, +bitable-records, and +task-preview are dry-run only and do not call Feishu OpenAPI.
+doc-export, +bitable-sync, and +task-create require explicit --send before attempting Open Platform writes.
Feishu card buttons are navigation-only.
GitLink write operations are not implemented.

Custom Bot Setup

Use a Feishu custom group bot for notification cards.

Recommended local setup:

.\scripts\feishu-gitlink-setup.ps1
.\scripts\feishu-gitlink-env-check.ps1 -Layer stable

The setup wizard opens Feishu / GitLink pages and stores values only in .local/feishu-gitlink.env.ps1.

Environment:

$env:FEISHU_WEBHOOK_URL="https://open.feishu.cn/open-apis/bot/v2/hook/..."
$env:FEISHU_WEBHOOK_SECRET="optional signing secret"

Preview a test card:

gitlink-cli feishu +bot-test --format json

Send a test card:

gitlink-cli feishu +bot-test --send --format table

Workflow Report Card

Generate workflow JSON:

gitlink-cli workflow +repo-report --owner Gitlink --repo gitlink-cli --format json > report.json

On Windows PowerShell, redirected files may be written with UTF-16 encoding. feishu workflow JSON readers accept UTF-8 and UTF-16 BOM files so the redirected output above can be consumed directly.

Preview a card:

gitlink-cli feishu +notify --from-workflow-json report.json --format json

Send a card:

gitlink-cli feishu +notify --from-workflow-json report.json --send --format table

Send a card with an existing Feishu document or Wiki link:

gitlink-cli feishu +notify \
  --from-workflow-json report.json \
  --doc-url "https://example.feishu.cn/wiki/..." \
  --send \
  --format table

Weekly Report

Render markdown:

gitlink-cli feishu +weekly-report --from-workflow-json report.json --format markdown

Send a weekly summary card:

gitlink-cli feishu +weekly-report --from-workflow-json report.json --send --format table

Owner and Contributor Digests

Owner digests summarize the repository state for maintainers:

gitlink-cli feishu +owner-digest --from-workflow-json report.json --format markdown
gitlink-cli feishu +owner-digest --from-workflow-json report.json --send --format table

Contributor digests summarize role-oriented follow-up work:

gitlink-cli feishu +contributor-digest --from-workflow-json report.json --format markdown
gitlink-cli feishu +contributor-digest --from-workflow-json report.json --send --format table

These digests are not Feishu-user-personalized. They do not use open_id, union_id, or personal routing.

Bitable Dry Run

Generate recommended table schemas:

gitlink-cli feishu +bitable-schema --format markdown

Generate Bitable-ready records:

gitlink-cli feishu +bitable-records --from-workflow-json report.json --format json

Default tables:

reports
issues
prs
contributors
tasks

These records are summary records derived from workflow repo-report JSON. They are not a per-issue or per-PR synchronization.

Experimental Bitable Sync

feishu +bitable-sync reuses the records produced by +bitable-records.

Preview:

gitlink-cli feishu +bitable-sync \
  --from-workflow-json report.json \
  --tables reports,issues,prs,contributors,tasks \
  --format table

Write with existing Base app and table IDs:

gitlink-cli feishu +bitable-sync \
  --from-workflow-json report.json \
  --tables reports,issues,prs,tasks \
  --send \
  --format table

The command searches by unique_key, updates when found, creates when missing, and never deletes records. If search fails, it falls back to create-only and prints diagnostics.

Task Preview and Experimental Task Create

Preview task candidates:

gitlink-cli feishu +task-preview --from-workflow-json report.json --format markdown

Attempt real Feishu task creation:

gitlink-cli feishu +task-create --from-workflow-json report.json --send --format table

+task-create is experimental and requires Feishu Task scopes. It does not create or update GitLink issues.

Role-Aware Collaboration Roadmap

The Feishu integration is designed to support two different notification modes:

Owner / maintainer: summarized digest.
Contributor: immediate personal feedback.

Owner-oriented cards should group PRs by review stage instead of sending one message for every PR event. Recommended stages:

blue: new or unreviewed
grey: active review
green: close to merge or merged
yellow: needs rebase
orange: major changes requested
red: blocked

Contributor notifications are different. A contributor should receive fast feedback when their own PR is reviewed, commented on, blocked by rebase/conflict, approved, merged, or closed.

Long-form project material should be exported to Feishu Docs / Wiki:

README summary
contribution guide
owner digest archive
milestone plan
PR stage table

Milestone and Gantt support should start as Bitable-ready records and document sections. Real Bitable writes and view creation require a separate permissioned OpenAPI design.

Detailed design:

feishu-export-design/ROLE_BASED_COLLABORATION.md

Experimental DocX / Wiki Export

feishu +doc-export is experimental because it uses Feishu self-built app credentials and writes to DocX / Wiki through OpenAPI.

Environment:

See docs/FEISHU_ENVIRONMENT.md for all Open Platform variables.