docs(readme): reference the floating v1 tag in examples

ci: restrict tag triggers to full semver
- Prevent the floating v1 major tag from cutting a goreleaser release or a docker image build
2026-10-05 02:30:44 +09:00 · 2026-08-16 10:57:44 +08:00 · 2026-08-16 10:57:44 +08:00 · 2026-08-16 10:54:18 +08:00 · 2026-08-16 10:54:18 +08:00 · 2026-08-16 10:54:18 +08:00
13 changed files with 655 additions and 127 deletions
@@ -0,0 +1,15 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    commit-message:
+      prefix: "chore(ci)"
+
+  - package-ecosystem: "docker"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    commit-message:
+      prefix: "chore(docker)"
@@ -1,111 +1,126 @@
 name: telegram message
 on: [push]
 jobs:
+  # Tests the working-tree Dockerfile and entrypoint.sh; the build job below
+  # runs against the published image referenced by action.yml instead.
+  local-image:
+    name: Test local image build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: build image from working tree
+        run: docker build -t telegram-action:local .
+
+      - name: send message via local image
+        env:
+          TELEGRAM_TO: ${{ secrets.TELEGRAM_TO }}
+          TELEGRAM_TOKEN: ${{ secrets.TELEGRAM_TOKEN }}
+        run: |
+          docker run --rm \
+            -e INPUT_TO="$TELEGRAM_TO" \
+            -e INPUT_TOKEN="$TELEGRAM_TOKEN" \
+            -e INPUT_MESSAGE_THREAD_ID= \
+            -e INPUT_MESSAGE="ci: local image smoke test for ${{ github.sha }}" \
+            telegram-action:local

  build:
    name: Build
    runs-on: ubuntu-latest
    steps:
-    - uses: actions/checkout@master
-    - name: send custom message with args
-      uses: ./
-      with:
-        to: ${{ secrets.TELEGRAM_TO }}
-        token: ${{ secrets.TELEGRAM_TOKEN }}
-        args: The ${{ github.event_name }} event triggered first step.
+      - uses: actions/checkout@v7
+      - name: send message using with
+        uses: ./
+        with:
+          to: ${{ secrets.TELEGRAM_TO }}
+          token: ${{ secrets.TELEGRAM_TOKEN }}
+          message: |
+            The ${{ github.event_name }} event triggered second step.
+            show the github variable ref: ${{ github.ref }}
+            show the github variable commit: ${{ github.sha }}
+            show the github variable ref: {{ commit.ref }}
+            show the github variable commit: {{ commit.sha }}
+            Commit Message: ${{ github.event.head_commit.message }}

-    - name: send message using with
-      uses: ./
-      with:
-        to: ${{ secrets.TELEGRAM_TO }}
-        token: ${{ secrets.TELEGRAM_TOKEN }}
-        message: |
-          The ${{ github.event_name }} event triggered second step.
-          show the github variable ref: ${{ github.ref }}
-          show the github variable commit: ${{ github.sha }}
-          show the github variable ref: {{ commit.ref }}
-          show the github variable commit: {{ commit.sha }}
-          Commit Message: ${{ github.event.head_commit.message }}
+      - name: send default message
+        uses: ./
+        with:
+          to: ${{ secrets.TELEGRAM_TO }}
+          token: ${{ secrets.TELEGRAM_TOKEN }}

-    - name: send default message
-      uses: ./
-      with:
-        to: ${{ secrets.TELEGRAM_TO }}
-        token: ${{ secrets.TELEGRAM_TOKEN }}
+      - name: send photo message
+        uses: ./
+        with:
+          to: ${{ secrets.TELEGRAM_TO }}
+          token: ${{ secrets.TELEGRAM_TOKEN }}
+          message: send photo message
+          photo: "./tests/github.png"
+          document: "./tests/gophercolor.png"

-    - name: send photo message
-      uses: ./
-      with:
-        to: ${{ secrets.TELEGRAM_TO }}
-        token: ${{ secrets.TELEGRAM_TOKEN }}
-        message: send photo message
-        photo: './tests/github.png'
-        document: './tests/gophercolor.png'
+      - name: send location message
+        uses: ./
+        with:
+          to: ${{ secrets.TELEGRAM_TO }}
+          token: ${{ secrets.TELEGRAM_TOKEN }}
+          location: "24.9163213 121.1424972"
+          venue: "35.661777 139.704051 竹北體育館 新竹縣竹北市"

-    - name: send location message
-      uses: ./
-      with:
-        to: ${{ secrets.TELEGRAM_TO }}
-        token: ${{ secrets.TELEGRAM_TOKEN }}
-        location: '24.9163213 121.1424972'
-        venue: '35.661777 139.704051 竹北體育館 新竹縣竹北市'
+      - name: send custom message
+        uses: ./
+        with:
+          to: ${{ secrets.TELEGRAM_TO }}
+          token: ${{ secrets.TELEGRAM_TOKEN }}
+          message: |
+            The ${{ github.event_name }} event triggered final step.
+            echo This event is a pull request that had an assignee removed.

-    - name: send custom message
-      uses: ./
-      with:
-        to: ${{ secrets.TELEGRAM_TO }}
-        token: ${{ secrets.TELEGRAM_TOKEN }}
-        message: |
-          The ${{ github.event_name }} event triggered final step.
-          echo This event is a pull request that had an assignee removed.
+      - name: send message file
+        uses: ./
+        with:
+          to: ${{ secrets.TELEGRAM_TO }}
+          token: ${{ secrets.TELEGRAM_TOKEN }}
+          message_file: tests/message.txt

-    - name: send message file
-      uses: ./
-      with:
-        to: ${{ secrets.TELEGRAM_TO }}
-        token: ${{ secrets.TELEGRAM_TOKEN }}
-        message_file: tests/message.txt
+      # - name: send message using socks5 proxy URL
+      #   uses: appleboy/telegram-action@master
+      #   with:
+      #     to: ${{ secrets.TELEGRAM_TO }}
+      #     token: ${{ secrets.TELEGRAM_TOKEN }}
+      #     socks5: "http://222.124.154.19:23500"
+      #     message: Send message from socks5 proxy URL.

-    # - name: send message using socks5 proxy URL
-    #   uses: appleboy/telegram-action@master
-    #   with:
-    #     to: ${{ secrets.TELEGRAM_TO }}
-    #     token: ${{ secrets.TELEGRAM_TOKEN }}
-    #     socks5: "http://222.124.154.19:23500"
-    #     message: Send message from socks5 proxy URL.
+      # - name: try multiple message
+      #   uses: appleboy/telegram-action@master
+      #   with:
+      #     to: ${{ secrets.TELEGRAM_TO }}
+      #     token: ${{ secrets.TELEGRAM_TOKEN }}
+      #     format: html
+      #     message: |
+      #       ⚡️ <a href="https://github.com/aszenz/repo/commit/${{ github.event.push.after }}">Commits</a> pushed to master by <em>${{ github.event.push.pusher.name }}</em> ⚡️
+      #       ${{ github.actor }}:${{ github.event.head_commit.message }}

-    # - name: try multiple message
-    #   uses: appleboy/telegram-action@master
-    #   with:
-    #     to: ${{ secrets.TELEGRAM_TO }}
-    #     token: ${{ secrets.TELEGRAM_TOKEN }}
-    #     format: html
-    #     message: |
-    #       ⚡️ <a href="https://github.com/aszenz/repo/commit/${{ github.event.push.after }}">Commits</a> pushed to master by <em>${{ github.event.push.pusher.name }}</em> ⚡️
-    #       ${{ github.actor }}:${{ github.event.head_commit.message }}
+      - name: link preview
+        uses: ./
+        with:
+          to: ${{ secrets.TELEGRAM_TO }}
+          token: ${{ secrets.TELEGRAM_TOKEN }}
+          message: |
+            show link preview https://google.com.tw

-    - name: link preview
-      uses: ./
-      with:
-        to: ${{ secrets.TELEGRAM_TO }}
-        token: ${{ secrets.TELEGRAM_TOKEN }}
-        message: |
-          show link preview https://google.com.tw
+      - name: disable link preview
+        uses: ./
+        with:
+          to: ${{ secrets.TELEGRAM_TO }}
+          token: ${{ secrets.TELEGRAM_TOKEN }}
+          disable_web_page_preview: true
+          message: |
+            disable link preview https://google.com.tw

-    - name: disable link preview
-      uses: ./
-      with:
-        to: ${{ secrets.TELEGRAM_TO }}
-        token: ${{ secrets.TELEGRAM_TOKEN }}
-        disable_web_page_preview: true
-        message: |
-          disable link preview https://google.com.tw
-
-    - name: sending a message without notification
-      uses: ./
-      with:
-        to: ${{ secrets.TELEGRAM_TO }}
-        token: ${{ secrets.TELEGRAM_TOKEN }}
-        disable_notification: true
-        message: |
-          disable link preview https://google.com.tw
+      - name: sending a message without notification
+        uses: ./
+        with:
+          to: ${{ secrets.TELEGRAM_TO }}
+          token: ${{ secrets.TELEGRAM_TOKEN }}
+          disable_notification: true
+          message: |
+            disable link preview https://google.com.tw
@@ -0,0 +1,59 @@
+name: Docker Image
+
+on:
+  push:
+    branches:
+      - master
+    tags:
+      # full semver only; the floating major tag (v1) must not trigger builds
+      - "v[0-9]*.[0-9]*.[0-9]*"
+  pull_request:
+    branches:
+      - master
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  packages: write
+
+jobs:
+  build-docker:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Login to GitHub Container Registry
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Docker meta
+        id: docker-meta
+        uses: docker/metadata-action@v6
+        with:
+          images: |
+            ghcr.io/${{ github.repository }}
+          tags: |
+            type=raw,value=latest,enable={{is_default_branch}}
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=semver,pattern={{major}}
+
+      - name: Build and push
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ steps.docker-meta.outputs.tags }}
+          labels: ${{ steps.docker-meta.outputs.labels }}
@@ -0,0 +1,29 @@
+name: Goreleaser
+
+on:
+  push:
+    tags:
+      # full semver only; the floating major tag (v1) must not cut a release
+      - "v[0-9]*.[0-9]*.[0-9]*"
+
+permissions:
+  contents: write
+
+jobs:
+  goreleaser:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: Run GoReleaser
+        uses: goreleaser/goreleaser-action@v7
+        with:
+          # either 'goreleaser' (default) or 'goreleaser-pro'
+          distribution: goreleaser
+          version: latest
+          args: release --clean
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -0,0 +1,89 @@
+name: Trivy Security Scan
+
+on:
+  schedule:
+    # Run at 00:00 on day 1 of every 3rd month (January, April, July, October)
+    - cron: "0 0 1 */3 *"
+  workflow_dispatch: # Allow manual trigger
+  push:
+    branches:
+      - master
+  pull_request:
+    branches:
+      - master
+
+permissions:
+  contents: read
+  security-events: write # For uploading results to GitHub Security tab
+
+jobs:
+  trivy-scan:
+    name: Trivy Security Scan
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v7
+
+      - name: Run Trivy vulnerability scanner in repo mode
+        uses: aquasecurity/trivy-action@v0.36.0
+        with:
+          scan-type: "fs"
+          scan-ref: "."
+          format: "sarif"
+          output: "trivy-results.sarif"
+          severity: "CRITICAL,HIGH"
+
+      - name: Upload Trivy results to GitHub Security tab
+        uses: github/codeql-action/upload-sarif@v4
+        if: always()
+        with:
+          sarif_file: "trivy-results.sarif"
+
+      - name: Run Trivy vulnerability scanner (table output)
+        uses: aquasecurity/trivy-action@v0.36.0
+        with:
+          scan-type: "fs"
+          scan-ref: "."
+          format: "table"
+          severity: "CRITICAL,HIGH"
+          exit-code: "1"
+
+  trivy-docker:
+    name: Trivy Docker Image Scan
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v7
+
+      - name: Build Docker image
+        run: docker build -t telegram-action:latest .
+
+      - name: Run Trivy vulnerability scanner on Docker image
+        uses: aquasecurity/trivy-action@v0.36.0
+        with:
+          scan-type: "image"
+          image-ref: "telegram-action:latest"
+          format: "sarif"
+          output: "trivy-docker-results.sarif"
+          severity: "CRITICAL,HIGH"
+
+      - name: Upload Trivy Docker results to GitHub Security tab
+        uses: github/codeql-action/upload-sarif@v4
+        if: always()
+        with:
+          sarif_file: "trivy-docker-results.sarif"
+
+      # Gated at CRITICAL only: base images may carry upstream HIGHs that can
+      # only be cleared by an upstream rebuild. They remain visible in the
+      # Security tab via the SARIF upload above.
+      - name: Run Trivy vulnerability scanner on Docker image (table output)
+        uses: aquasecurity/trivy-action@v0.36.0
+        if: always()
+        with:
+          scan-type: "image"
+          image-ref: "telegram-action:latest"
+          format: "table"
+          severity: "CRITICAL"
+          exit-code: "1"
@@ -0,0 +1 @@
+.DS_Store
@@ -0,0 +1,28 @@
+builds:
+  - # If true, skip the build.
+    # Useful for library projects.
+    # Default is false
+    skip: true
+
+changelog:
+  use: github
+  groups:
+    - title: Features
+      regexp: "^.*feat[(\\w)]*:+.*$"
+      order: 0
+    - title: "Bug fixes"
+      regexp: "^.*fix[(\\w)]*:+.*$"
+      order: 1
+    - title: "Enhancements"
+      regexp: "^.*chore[(\\w)]*:+.*$"
+      order: 2
+    - title: "Refactor"
+      regexp: "^.*refactor[(\\w)]*:+.*$"
+      order: 3
+    - title: "Build process updates"
+      regexp: ^.*?(build|ci)(\(.+\))??!?:.+$
+      order: 4
+    - title: "Documentation updates"
+      regexp: ^.*?docs?(\(.+\))??!?:.+$
+      order: 4
+    - title: Others
@@ -1,7 +1,6 @@
-FROM appleboy/drone-telegram:1.4.0
+FROM ghcr.io/appleboy/drone-telegram:1.5.1

 COPY entrypoint.sh /entrypoint.sh
-RUN chmod +x /entrypoint.sh

 WORKDIR /github/workspace

@@ -1,6 +1,8 @@
 # 🚀 Telegram for GitHub Actions

-[GitHub Action](https://github.com/features/actions) for sending a Telegram notification message.
+[繁體中文](./README.zh-tw.md) | [简体中文](./README.zh-cn.md)
+
+[GitHub Action](https://github.com/features/actions) for sending Telegram notification messages.

 ![notification](./images/telegram-notification.png)

@@ -8,9 +10,9 @@

 ## Usage

-**NOTE**: If you are getting "Error: Chat not found", then you need to look at this stackoverflow's answer [here](https://stackoverflow.com/a/41291666).
+**Note**: If you receive the "Error: Chat not found" error, please refer to this StackOverflow answer [here](https://stackoverflow.com/a/41291666).

-Send custom message and see the custom variable as below.
+Send a custom message and view the custom variables below.

 ```yml
 name: telegram message
@@ -22,7 +24,7 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - name: send telegram message on push
-        uses: appleboy/telegram-action@master
+        uses: appleboy/telegram-action@v1
        with:
          to: ${{ secrets.TELEGRAM_TO }}
          token: ${{ secrets.TELEGRAM_TOKEN }}
@@ -35,11 +37,11 @@ jobs:
            See changes: https://github.com/${{ github.repository }}/commit/${{github.sha}}
 ```

-Remove `args` to send the default message.
+Remove the `message` input to send the default message.

 ```yml
 - name: send default message
-  uses: appleboy/telegram-action@master
+  uses: appleboy/telegram-action@v1
  with:
    to: ${{ secrets.TELEGRAM_TO }}
    token: ${{ secrets.TELEGRAM_TOKEN }}
@@ -49,30 +51,35 @@ Remove `args` to send the default message.

 ## Input variables

-* socks5 - optional. support socks5 proxy URL
-* photo - optional. photo message
-* document - optional. document message
-* sticker - optional. sticker message
-* audio - optional. audio message
-* voice - optional. voice message
-* location - optional. location message
-* venue - optional. venue message
-* video - optional. video message
-* debug - optional. enable debug mode
-* format - optional. `markdown` or `html`. See [MarkdownV2 style](https://core.telegram.org/bots/api#markdownv2-style)
-* message - optional. custom message
-* message_file - optional. overwrite the default message template with the contents of the specified file.
-* disable_web_page_preview - optional. disables link previews for links in this message. default is `false`.
-* disable_notification - optional. disables notifications for this message, supports sending a message without notification. default is `false`.
+| Variable                 | Description                                                                                                             |
+| ------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
+| to                       | **required**. Unique identifier for the target chat.                                                                    |
+| token                    | **required**. Telegram authorization token.                                                                             |
+| socks5                   | optional. Support socks5 proxy URL                                                                                      |
+| photo                    | optional. Photo message                                                                                                 |
+| document                 | optional. Document message                                                                                              |
+| sticker                  | optional. Sticker message                                                                                               |
+| audio                    | optional. Audio message                                                                                                 |
+| voice                    | optional. Voice message                                                                                                 |
+| location                 | optional. Location message                                                                                              |
+| venue                    | optional. Venue message                                                                                                 |
+| video                    | optional. Video message                                                                                                 |
+| debug                    | optional. Enable debug mode                                                                                             |
+| format                   | optional. `markdown` or `html`. See [MarkdownV2 style](https://core.telegram.org/bots/api#markdownv2-style)             |
+| message                  | optional. Custom message                                                                                                |
+| message_file             | optional. Overwrite the default message template with the contents of the specified file.                               |
+| message_thread_id        | optional. Unique identifier for the target message thread (topic) of the forum; for forum supergroups only.             |
+| disable_web_page_preview | optional. Disables link previews for links in this message. Default is `false`.                                         |
+| disable_notification     | optional. Disables notifications for this message, supports sending a message without notification. Default is `false`. |

 ## Example

-send photo message:
+Send photo message:

 ```yml
- uses: actions/checkout@master
+- uses: actions/checkout@v7
 - name: send photo message
-  uses: appleboy/telegram-action@master
+  uses: appleboy/telegram-action@v1
  with:
    to: ${{ secrets.TELEGRAM_TO }}
    token: ${{ secrets.TELEGRAM_TOKEN }}
@@ -81,11 +88,11 @@ send photo message:
    document: tests/gophercolor.png
 ```

-send location message:
+Send location message:

 ```yml
 - name: send location message
-  uses: appleboy/telegram-action@master
+  uses: appleboy/telegram-action@v1
  with:
    to: ${{ secrets.TELEGRAM_TO }}
    token: ${{ secrets.TELEGRAM_TOKEN }}
@@ -93,11 +100,23 @@ send location message:
    venue: '35.661777 139.704051 竹北體育館 新竹縣竹北市'
 ```

-send message using custom proxy (support `http`, `https`, and `socks5`) like `socks5://127.0.0.1:1080` or `http://222.124.154.19:23500`
+Send a message to a specific forum topic (thread):
+
+```yml
+- name: send message to forum topic
+  uses: appleboy/telegram-action@v1
+  with:
+    to: ${{ secrets.TELEGRAM_TO }}
+    token: ${{ secrets.TELEGRAM_TOKEN }}
+    message_thread_id: 42
+    message: Hello from GitHub Actions!
+```
+
+Send message using custom proxy (support `http`, `https`, and `socks5`) like `socks5://127.0.0.1:1080` or `http://222.124.154.19:23500`

 ```yml
 - name: send message using socks5 proxy URL
-  uses: appleboy/telegram-action@master
+  uses: appleboy/telegram-action@v1
  with:
    to: ${{ secrets.TELEGRAM_TO }}
    token: ${{ secrets.TELEGRAM_TOKEN }}
@@ -154,7 +173,7 @@ See the result: (get chat id like `65382999`)
 ## Template variable

 | Github Variable   | Telegram Template Variable |
-|-------------------|----------------------------|
+| ----------------- | -------------------------- |
 | GITHUB_REPOSITORY | repo                       |
 | GITHUB_ACTOR      | repo.namespace             |
 | GITHUB_SHA        | commit.sha                 |
@@ -0,0 +1,136 @@
+# 🚀 GitHub Actions 的 Telegram
+
+[GitHub Action](https://github.com/features/actions) 用于发送 Telegram 通知消息。
+
+![notification](./images/telegram-notification.png)
+
+[![Actions Status](https://github.com/appleboy/telegram-action/workflows/telegram%20message/badge.svg)](https://github.com/appleboy/telegram-action/actions)
+
+## 使用方法
+
+**注意**：如果您收到 "Error: Chat not found" 错误，请参考这个 stackoverflow 的回答 [这里](https://stackoverflow.com/a/41291666)。
+
+发送自定义消息并查看如下的自定义变量。
+
+## 输入变量
+
+| 变量                     | 描述                                                                                                    |
+| ------------------------ | ------------------------------------------------------------------------------------------------------- |
+| to                       | **必填**。目标聊天的唯一标识符                                                                          |
+| token                    | **必填**。Telegram 授权令牌                                                                             |
+| socks5                   | 可选。支持 socks5 代理 URL                                                                              |
+| photo                    | 可选。照片消息                                                                                          |
+| document                 | 可选。文档消息                                                                                          |
+| sticker                  | 可选。贴纸消息                                                                                          |
+| audio                    | 可选。音频消息                                                                                          |
+| voice                    | 可选。语音消息                                                                                          |
+| location                 | 可选。位置消息                                                                                          |
+| venue                    | 可选。场馆消息                                                                                          |
+| video                    | 可选。视频消息                                                                                          |
+| debug                    | 可选。启用调试模式                                                                                      |
+| format                   | 可选。`markdown` 或 `html`。参见 [MarkdownV2 样式](https://core.telegram.org/bots/api#markdownv2-style) |
+| message                  | 可选。自定义消息                                                                                        |
+| message_file             | 可选。用指定文件的内容覆盖默认消息模板。                                                                |
+| message_thread_id        | 可选。论坛目标消息串（主题）的唯一标识符，仅适用于论坛超级群组。                                        |
+| disable_web_page_preview | 可选。禁用此消息中链接的预览。默认值为 `false`。                                                        |
+| disable_notification     | 可选。禁用此消息的通知，支持发送无通知的消息。默认值为 `false`。                                        |
+
+## 示例
+
+发送照片消息：
+
+```yml
+- uses: actions/checkout@v7
+- name: send photo message
+  uses: appleboy/telegram-action@v1
+  with:
+    to: ${{ secrets.TELEGRAM_TO }}
+    token: ${{ secrets.TELEGRAM_TOKEN }}
+    message: send photo message
+    photo: tests/github.png
+    document: tests/gophercolor.png
+```
+
+发送位置消息：
+
+```yml
+- name: send location message
+  uses: appleboy/telegram-action@v1
+  with:
+    to: ${{ secrets.TELEGRAM_TO }}
+    token: ${{ secrets.TELEGRAM_TOKEN }}
+    location: '24.9163213 121.1424972'
+    venue: '35.661777 139.704051 竹北體育館 新竹縣竹北市'
+```
+
+使用自定义代理发送消息（支持 `http`、`https` 和 `socks5`），如 `socks5://127.0.0.1:1080` 或 `http://222.124.154.19:23500`
+
+```yml
+- name: send message using socks5 proxy URL
+  uses: appleboy/telegram-action@v1
+  with:
+    to: ${{ secrets.TELEGRAM_TO }}
+    token: ${{ secrets.TELEGRAM_TOKEN }}
+    socks5: "http://222.124.154.19:23500"
+    message: Send message from socks5 proxy URL.
+```
+
+## Secrets
+
+开始使用 [Telegram Bot API](https://core.telegram.org/bots/api)。
+
+* `token`: Telegram 授权令牌。
+* `to`: 此聊天的唯一标识符。
+
+如何从 Telegram API 获取唯一标识符：
+
+```bash
+curl https://api.telegram.org/bot<token>/getUpdates
+```
+
+查看结果：（获取聊天 ID，如 `65382999`）
+
+```json
+{
+  "ok": true,
+  "result": [
+    {
+      "update_id": 664568113,
+      "message": {
+        "message_id": 8423,
+        "from": {
+          "id": 65382999,
+          "is_bot": false,
+          "first_name": "Bo-Yi",
+          "last_name": "Wu (appleboy)",
+          "username": "appleboy46",
+          "language_code": "en"
+        },
+        "chat": {
+          "id": 65382999,
+          "first_name": "Bo-Yi",
+          "last_name": "Wu (appleboy)",
+          "username": "appleboy46",
+          "type": "private"
+        },
+        "date": 1550333434,
+        "text": "?"
+      }
+    }
+  ]
+}
+```
+
+## 模板变量
+
+| GitHub 变量       | Telegram 模板变量 |
+| ----------------- | ----------------- |
+| GITHUB_REPOSITORY | repo              |
+| GITHUB_ACTOR      | repo.namespace    |
+| GITHUB_SHA        | commit.sha        |
+| GITHUB_REF        | commit.ref        |
+| GITHUB_WORKFLOW   | github.workflow   |
+| GITHUB_ACTION     | github.action     |
+| GITHUB_EVENT_NAME | github.event.name |
+| GITHUB_EVENT_PATH | github.event.path |
+| GITHUB_WORKSPACE  | github.workspace  |
@@ -0,0 +1,136 @@
+# 🚀 Telegram 的 GitHub Actions
+
+透過 [GitHub Action](https://github.com/features/actions) 發送 Telegram 通知訊息。
+
+![通知](./images/telegram-notification.png)
+
+[![Actions 狀態](https://github.com/appleboy/telegram-action/workflows/telegram%20message/badge.svg)](https://github.com/appleboy/telegram-action/actions)
+
+## 使用方式
+
+**注意**：如果您收到 "Error: Chat not found" 錯誤，請參考此 stackoverflow 上的回答 [連結](https://stackoverflow.com/a/41291666)。
+
+發送自訂訊息並參考以下自訂變數。
+
+## 輸入變數
+
+| 變數                     | 說明                                                                                                    |
+| ------------------------ | ------------------------------------------------------------------------------------------------------- |
+| to                       | **必填**。目標聊天的唯一標識符                                                                          |
+| token                    | **必填**。Telegram 授權令牌                                                                             |
+| socks5                   | 選填。支援 socks5 代理 URL                                                                              |
+| photo                    | 選填。圖片訊息                                                                                          |
+| document                 | 選填。文件訊息                                                                                          |
+| sticker                  | 選填。貼圖訊息                                                                                          |
+| audio                    | 選填。音訊訊息                                                                                          |
+| voice                    | 選填。語音訊息                                                                                          |
+| location                 | 選填。位置訊息                                                                                          |
+| venue                    | 選填。地點訊息                                                                                          |
+| video                    | 選填。影片訊息                                                                                          |
+| debug                    | 選填。啟用除錯模式                                                                                      |
+| format                   | 選填。`markdown` 或 `html`。參見 [MarkdownV2 格式](https://core.telegram.org/bots/api#markdownv2-style) |
+| message                  | 選填。自訂訊息                                                                                          |
+| message_file             | 選填。使用指定檔案的內容覆蓋預設訊息模板                                                                |
+| message_thread_id        | 選填。論壇目標訊息串（主題）的唯一標識符，僅適用於論壇超級群組                                          |
+| disable_web_page_preview | 選填。停用此訊息中連結的預覽。預設為 `false`                                                            |
+| disable_notification     | 選填。停用此訊息的通知，支援發送無通知的訊息。預設為 `false`                                            |
+
+## 範例
+
+發送圖片訊息：
+
+```yml
+- uses: actions/checkout@v7
+- name: send photo message
+  uses: appleboy/telegram-action@v1
+  with:
+    to: ${{ secrets.TELEGRAM_TO }}
+    token: ${{ secrets.TELEGRAM_TOKEN }}
+    message: send photo message
+    photo: tests/github.png
+    document: tests/gophercolor.png
+```
+
+發送位置消息：
+
+```yml
+- name: send location message
+  uses: appleboy/telegram-action@v1
+  with:
+    to: ${{ secrets.TELEGRAM_TO }}
+    token: ${{ secrets.TELEGRAM_TOKEN }}
+    location: '24.9163213 121.1424972'
+    venue: '35.661777 139.704051 竹北體育館 新竹縣竹北市'
+```
+
+使用自定義代理發送消息（支持 `http`、`https` 和 `socks5`），如 `socks5://127.0.0.1:1080` 或 `http://222.124.154.19:23500`
+
+```yml
+- name: send message using socks5 proxy URL
+  uses: appleboy/telegram-action@v1
+  with:
+    to: ${{ secrets.TELEGRAM_TO }}
+    token: ${{ secrets.TELEGRAM_TOKEN }}
+    socks5: "http://222.124.154.19:23500"
+    message: Send message from socks5 proxy URL.
+```
+
+## Secrets
+
+開始使用 [Telegram Bot API](https://core.telegram.org/bots/api)。
+
+* `token`: Telegram 授權令牌。
+* `to`: 此聊天的唯一標識符。
+
+如何從 telegram api 獲取唯一標識符：
+
+```bash
+curl https://api.telegram.org/bot<token>/getUpdates
+```
+
+查看結果：（獲取聊天 ID，如 `65382999`）
+
+```json
+{
+  "ok": true,
+  "result": [
+    {
+      "update_id": 664568113,
+      "message": {
+        "message_id": 8423,
+        "from": {
+          "id": 65382999,
+          "is_bot": false,
+          "first_name": "Bo-Yi",
+          "last_name": "Wu (appleboy)",
+          "username": "appleboy46",
+          "language_code": "en"
+        },
+        "chat": {
+          "id": 65382999,
+          "first_name": "Bo-Yi",
+          "last_name": "Wu (appleboy)",
+          "username": "appleboy46",
+          "type": "private"
+        },
+        "date": 1550333434,
+        "text": "?"
+      }
+    }
+  ]
+}
+```
+
+## 模板變數
+
+| Github 變數       | Telegram 模板變數 |
+| ----------------- | ----------------- |
+| GITHUB_REPOSITORY | repo              |
+| GITHUB_ACTOR      | repo.namespace    |
+| GITHUB_SHA        | commit.sha        |
+| GITHUB_REF        | commit.ref        |
+| GITHUB_WORKFLOW   | github.workflow   |
+| GITHUB_ACTION     | github.action     |
+| GITHUB_EVENT_NAME | github.event.name |
+| GITHUB_EVENT_PATH | github.event.path |
+| GITHUB_WORKSPACE  | github.workspace  |
@@ -4,8 +4,10 @@ author: 'Bo-Yi Wu'
 inputs:
  to:
    description: 'telegram user'
+    required: true
  token:
    description: 'telegram token'
+    required: true
  message:
    description: 'telegram message'
  message_file:
@@ -36,9 +38,11 @@ inputs:
    description: 'disables link previews for links in this message'
  disable_notification:
    description: 'disables notifications for this message, supports sending a message without notification,'
+  message_thread_id:
+    description: 'unique identifier for the target message thread (topic) of the forum; for forum supergroups only'
 runs:
  using: 'docker'
-  image: 'Dockerfile'
+  image: 'docker://ghcr.io/appleboy/telegram-action:1.1.1'

 branding:
  icon: 'message-square'
@@ -4,6 +4,4 @@ set -eu

 export GITHUB="true"

-[ -n "$*" ] && export TELEGRAM_MESSAGE="$*"
-
 /bin/drone-telegram
Author	SHA1	Message	Date
Bo-Yi Wu	dd9f2d9fa7	docs(readme): reference the floating v1 tag in examples	2026-08-16 10:57:44 +08:00
Bo-Yi Wu	4023d256c8	ci: restrict tag triggers to full semver - Prevent the floating v1 major tag from cutting a goreleaser release or a docker image build	2026-08-16 10:57:44 +08:00
Bo-Yi Wu	214f06cfa3	chore(release): pin action image and docs to 1.1.1	2026-08-16 10:54:18 +08:00
Bo-Yi Wu	2608c6db39	fix(entrypoint): drop empty thread id workaround - drone-telegram 1.5.1 handles empty INPUT_MESSAGE_THREAD_ID itself	2026-08-16 10:54:18 +08:00
Bo-Yi Wu	c078210187	chore(docker): bump drone-telegram base image to 1.5.1 - Upstream now treats empty numeric env vars as unset	2026-08-16 10:54:18 +08:00
Bo-Yi Wu	7f612b977e	chore: ignore .DS_Store files	2026-08-16 10:33:52 +08:00
Bo-Yi Wu	c18c95644a	docs(readme): pin examples to v1.1.0 and sync input tables - Replace mutable @master references with the v1.1.0 tag - Add required to/token rows to all input tables - Add missing message_thread_id row to both Chinese translations - Reword the default-message note to reference message instead of the removed args mechanism	2026-08-16 10:33:52 +08:00
Bo-Yi Wu	6753faf1d2	feat(action): mark to and token inputs as required - Surface missing credentials before the container runs	2026-08-16 10:33:52 +08:00
Bo-Yi Wu	53d62f6c74	ci: add working-tree image test and drop dead args step - Build and smoke-test the local Dockerfile/entrypoint since the action now runs the published ghcr image instead of the working tree - Exercise the empty INPUT_MESSAGE_THREAD_ID guard in the smoke test - Remove the args step which silently sent the default message	2026-08-16 10:33:52 +08:00
Bo-Yi Wu	e9e9d8fda7	fix(entrypoint): remove dead args passthrough - Container args were never wired up in action.yml (no runs.args), so the positional-argument branch could never fire	2026-08-16 10:33:52 +08:00
Bo-Yi Wu	16657635b3	fix(action): pin prebuilt image to versioned tag - Replace the mutable latest tag with the immutable 1.1.0 image tag so released action versions stay reproducible and a bad master push cannot break existing users	2026-08-16 10:27:42 +08:00
Bo-Yi Wu	fd541f19b0	fix(entrypoint): unset empty INPUT_MESSAGE_THREAD_ID - The runner exports every declared input as an env var even when unset, and drone-telegram 1.5.0 fails to parse an empty string for the integer message.thread.id flag	2026-08-16 10:13:31 +08:00
Bo-Yi Wu	f8121d9e5a	perf(action): use prebuilt ghcr image instead of building Dockerfile - Pull ghcr.io/appleboy/telegram-action:latest at runtime instead of building the Docker image on every workflow run	2026-08-16 10:11:41 +08:00
Bo-Yi Wu	b8da483c2e	ci(goreleaser): remove unused Go setup step - goreleaser config skips builds, so the Go toolchain is never used	2026-08-16 10:10:14 +08:00
Bo-Yi Wu	724a55ccf8	chore(docker): drop redundant chmod layer - entrypoint.sh already carries the executable bit in git	2026-08-16 10:10:14 +08:00
Bo-Yi Wu	8223320a4c	chore(deps): add dependabot config for actions and docker - Enable weekly update checks for GitHub Actions and the Dockerfile base image	2026-08-16 10:10:14 +08:00
Bo-Yi Wu	ea12760348	ci(docker): publish prebuilt image to ghcr - Build and push multi-arch (amd64/arm64) image on master pushes and version tags - Generate latest and semver tags via docker metadata action - Build without pushing on pull requests for validation	2026-08-16 10:10:14 +08:00
Bo-Yi Wu	d678193671	chore(docker): bump drone-telegram base image to 1.5.0 - Upgrade the base image from 1.4.2 to 1.5.0	2026-08-16 10:00:47 +08:00
Bo-Yi WuandClaude Fable 5	d600df785a	fix(docker): bump drone-telegram base image to 1.4.2 The 1.4.0 image binary was built with Go 1.22.6, affected by stdlib CVE-2025-68121 (crypto/tls certificate validation bypass, CVSS 10.0). 1.4.2 is built with Go 1.25.13 and patched golang.org/x/crypto v0.55.0. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>	2026-08-14 22:27:40 +08:00
Bo-Yi WuandClaude Fable 5	78e5f2ccac	ci(trivy): add scheduled security scan workflow - Scan the repository filesystem for CRITICAL and HIGH vulnerabilities and upload SARIF results to the GitHub Security tab - Build the Docker image and scan it, gating the build on CRITICAL findings only - Run quarterly on a schedule, on manual dispatch, and on pushes and pull requests to the default branch Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>	2026-08-09 12:50:42 +08:00
Bo-Yi Wu	78c9ef35ff	chore(ci): bump actions/setup-go from v6 to v7 - Update actions/setup-go from v6 to v7 in workflow files	2026-07-18 09:58:01 +08:00
Bo-Yi Wu	4cd2253b24	chore(ci): update GitHub Actions dependencies to latest versions - Bump actions/checkout from v6 to v7	2026-06-23 20:07:08 +08:00
Abdullajonov BoburandGitHub	37056891d4	feat: Added support to sending message to group topic (#70 )	2026-04-08 21:22:05 +08:00
Bo-Yi WuandClaude Opus 4.6	847a2d3240	chore(ci): update GitHub Actions dependencies to latest versions Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-03-28 12:06:40 +08:00
appleboy	1b2bf60368	docs: localize README to Traditional Chinese - Fix a typo in the README.zh-tw.md file - Translate English text to Traditional Chinese in the README.zh-tw.md file Signed-off-by: appleboy <appleboy.tw@gmail.com>	2024-11-20 22:33:56 +08:00
appleboy	95f03551fd	docs: translate documentation sections to Chinese - Translate input variables section to Chinese - Translate example section to Chinese - Translate specific message sending instructions to Chinese - Translate Telegram Bot API getting started instructions to Chinese - Translate template variable section to Chinese Signed-off-by: appleboy <appleboy.tw@gmail.com>	2024-11-20 22:28:31 +08:00
appleboy	85afa0fd9a	docs: enhance internationalization and testing framework - Add links to Traditional Chinese and Simplified Chinese README files Signed-off-by: appleboy <appleboy.tw@gmail.com>	2024-11-20 22:27:23 +08:00
appleboy	84183da9cf	docs: add Chinese READMEs for GitHub Actions notifications - Add a Chinese (Simplified) README for GitHub Actions Telegram notifications - Add a Chinese (Traditional) README for GitHub Actions Telegram notifications Signed-off-by: appleboy <appleboy.tw@gmail.com>	2024-11-20 22:27:02 +08:00
appleboy	5010c012e9	docs: improve documentation consistency and clarity - Fix minor grammatical errors and improve clarity in the README.md - Capitalize the first letter of list items in the options table for consistency Signed-off-by: appleboy <appleboy.tw@gmail.com>	2024-11-20 22:26:53 +08:00
appleboy	94584eda62	docs: improve documentation formatting and API usage - Convert the list of optional parameters to a table format for better readability - Fix the table formatting in the "See the result" section Signed-off-by: appleboy <appleboy.tw@gmail.com>	2024-11-20 22:08:01 +08:00
appleboy	221e6b6849	build: switch to GitHub Container Registry for Docker images - Update Dockerfile to use the GitHub Container Registry for the drone-telegram image Signed-off-by: appleboy <appleboy.tw@gmail.com>	2024-11-16 01:40:01 +08:00
appleboy	9177cafddc	ci: implement automated release workflow with GoReleaser - Add a GitHub Actions workflow for GoReleaser - Configure GoReleaser to skip builds by default - Set up changelog groups with specific regex patterns for categorizing changes Signed-off-by: appleboy <appleboy.tw@gmail.com>	2024-10-09 23:58:44 +08:00
appleboy	65a1d3c2f9	style: refactor CI configuration for consistency and clarity - Update quotes from single to double in the CI configuration file - Remove an empty line in the jobs section - Adjust formatting for the photo and document paths Signed-off-by: appleboy <appleboy.tw@gmail.com>	2024-09-06 19:19:14 +08:00