Skip to content

Commit

Permalink
docs: update readme guideline
Browse files Browse the repository at this point in the history
  • Loading branch information
@yanglbme
yanglbme committed Nov 27, 2021
1 parent a5ba7ed commit d83200c
Show file tree
Hide file tree
Showing 5 changed files with 94 additions and 25 deletions.
41 changes: 41 additions & 0 deletions .github/workflows/compress.yml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
name: Compress

on:
push:
branches: [main]
paths:
- "**.jpg"
- "**.jpeg"
- "**.png"
- "**.webp"
workflow_dispatch:

jobs:
compress:
runs-on: ubuntu-latest
if: github.repository == 'yanglbme/gitee-pages-action'
steps:
- name: Checkout Branch
uses: actions/checkout@v2

- name: Compress Images
id: calibre
uses: calibreapp/image-actions@main
with:
githubToken: ${{ secrets.GITHUB_TOKEN }}
compressOnly: true

- name: Commit Files
if: |
steps.calibre.outputs.markdown != ''
run: |
git config --local user.email "[email protected]"
git config --local user.name "GitHub Action"
git commit -m "chore: auto compress images" -a
- name: Push Changes
if: |
steps.calibre.outputs.markdown != ''
uses: ad-m/github-push-action@master
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
78 changes: 53 additions & 25 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,21 +31,24 @@
| ---------------- | ---------------------------- | -------- | -------- | ------------------------------- |
| `gitee-username` | Gitee 用户名 | 是 | - | `yanglbme` |
| `gitee-password` | Gitee 密码 | 是 | - | `${{ secrets.GITEE_PASSWORD }}` |
| `gitee-repo` | Gitee 仓库（严格区分大小写） | 是 | - | `doocs/advanced-java` |
| `gitee-repo` | Gitee 仓库（严格区分大小写） | 是 | - | `doocs/leetcode` |
| `branch` | 要部署的分支（分支必须存在） | 否 | `master` | `main` |
| `directory` | 要部署的分支上的目录 | 否 | | `src` |
| `https` | 是否强制使用 HTTPS | 否 | `true` | `false` |

## 示例
## 完整示例

以下是一个完整示例。
### 1. 创建 workflow

在你的 GitHub 仓库 `.github/workflows/` 文件夹下创建一个 `.yml` 文件，如 `sync.yml`，内容如下：
在你的 GitHub 项目 `.github/workflows/` 文件夹下创建一个 `.yml` 文件，如 `sync.yml`，内容如下：

```yml
name: Sync

on: page_build
on:
push:
branches: [main]
workflow_dispatch:

jobs:
build:
Expand All @@ -58,9 +61,9 @@ jobs:
SSH_PRIVATE_KEY: ${{ secrets.GITEE_RSA_PRIVATE_KEY }}
with:
# 注意替换为你的 GitHub 源仓库地址
source-repo: [email protected]:doocs/advanced-java.git
source-repo: [email protected]:doocs/leetcode.git
# 注意替换为你的 Gitee 目标仓库地址
destination-repo: [email protected]:Doocs/advanced-java.git
destination-repo: [email protected]:Doocs/leetcode.git

- name: Build Gitee Pages
uses: yanglbme/gitee-pages-action@main
Expand All @@ -70,14 +73,16 @@ jobs:
# 注意在 Settings->Secrets 配置 GITEE_PASSWORD
gitee-password: ${{ secrets.GITEE_PASSWORD }}
# 注意替换为你的 Gitee 仓库，仓库名严格区分大小写，请准确填写，否则会出错
gitee-repo: doocs/advanced-java
gitee-repo: doocs/leetcode
# 要部署的分支，默认是 master，若是其他分支，则需要指定（指定的分支必须存在）
branch: main
```
先使用 [wearerequired/git-mirror-action](https://github.com/wearerequired/git-mirror-action) 将 GitHub 仓库同步到 Gitee 仓库，再使用 [yanglbme/gitee-pages-action](https://github.com/yanglbme/gitee-pages-action) 实现 Gitee Pages 的自动部署。
**密钥的配置步骤如下（可展开看示例图）**：
### 2. 配置密钥
密钥的配置步骤如下（可展开看示例图）：
<details>
<summary>1. 在命令行终端或 Git Bash 使用命令 <code>ssh-keygen -t rsa -C "[email protected]"</code> 生成 SSH Key，注意替换为自己的邮箱。生成的 <code>id_rsa</code> 是私钥，<code>id_rsa.pub</code> 是公钥。(⚠️注意此处不要设置密码，生成的公私钥用于下面 GitHub / Gitee 的配置，以保证公私钥成对，否则从 GitHub -> Gitee 的同步将会失败。)</summary>
Expand All @@ -96,31 +101,54 @@ jobs:
<img src="https://cdn.jsdelivr.net/gh/yanglbme/gitee-pages-action@main/images/add_ssh_key_gitee.png" alt="add_ssh_key_gitee">
</details>
如果一切配置正常，并成功触发 [Gitee Pages Action](https://github.com/marketplace/actions/gitee-pages-action) ，我们会在 Gitee 公众号收到一条登录通知。这是 Gitee Pages Action 程序帮我们登录到 Gitee 官网，并为我们点击了项目的部署按钮。
### 3. 运行结果
如果一切配置正常，并成功触发 [Gitee Pages Action](https://github.com/marketplace/actions/gitee-pages-action) ，Gitee Pages Action 会打印出成功的结果。并且，我们会在 Gitee 公众号收到一条登录通知。这是 Gitee Pages Action 程序帮我们登录到 Gitee 官网，并为我们点击了项目的部署按钮。
```bash
Run yanglbme/gitee-pages-action@main
with:
gitee-username: yanglbme
gitee-password: ***
gitee-repo: doocs/leetcode
branch: main
https: true
/usr/bin/docker run --name e28490f27de0ee43bb49109a40cea0e43202d2_d4911a --label e28490 --workdir /github/workspace --rm -e INPUT_GITEE-USERNAME -e INPUT_GITEE*** INPUT_GITEE-REPO -e INPUT_BRANCH -e INPUT_DIRECTORY -e INPUT_HTTPS -e HOME -e GITHUB_JOB -e GITHUB_REF -e GITHUB_SHA -e GITHUB_REPOSITORY -e GITHUB_REPOSITORY_OWNER -e GITHUB_RUN_ID -e GITHUB_RUN_NUMBER -e GITHUB_RETENTION_DAYS -e GITHUB_RUN_ATTEMPT -e GITHUB_ACTOR -e GITHUB_WORKFLOW -e GITHUB_HEAD_REF -e GITHUB_BASE_REF -e GITHUB_EVENT_NAME -e GITHUB_SERVER_URL -e GITHUB_API_URL -e GITHUB_GRAPHQL_URL -e GITHUB_REF_NAME -e GITHUB_REF_PROTECTED -e GITHUB_REF_TYPE -e GITHUB_WORKSPACE -e GITHUB_ACTION -e GITHUB_EVENT_PATH -e GITHUB_ACTION_REPOSITORY -e GITHUB_ACTION_REF -e GITHUB_PATH -e GITHUB_ENV -e RUNNER_OS -e RUNNER_ARCH -e RUNNER_NAME -e RUNNER_TOOL_CACHE -e RUNNER_TEMP -e RUNNER_WORKSPACE -e ACTIONS_RUNTIME_URL -e ACTIONS_RUNTIME_TOKEN -e ACTIONS_CACHE_URL -e GITHUB_ACTIONS=true -e CI=true -v "/var/run/docker.sock":"/var/run/docker.sock" -v "/home/runner/work/_temp/_github_home":"/github/home" -v "/home/runner/work/_temp/_github_workflow":"/github/workflow" -v "/home/runner/work/_temp/_runner_file_commands":"/github/file_commands" -v "/home/runner/work/leetcode/leetcode":"/github/workspace" e28490:f27de0ee43bb49109a40cea0e43202d2
[2021-11-27 20:16:30] Welcome to use Gitee Pages Action ❤

📕 Getting Started Guide: https://github.com/marketplace/actions/gitee-pages-action
📣 Maintained by Yang Libin: https://github.com/yanglbme

[2021-11-27 20:16:34] Login successfully
[2021-11-27 20:16:35] Rebuild Gitee Pages successfully
[2021-11-27 20:16:35] Success, thanks for using @yanglbme/gitee-pages-action!
```

<img src="https://cdn.jsdelivr.net/gh/yanglbme/gitee-pages-action@main/images/action.png" alt="action_result">

<img src="https://cdn.jsdelivr.net/gh/yanglbme/gitee-pages-action@main/images/wechat_notification.png" alt="add_ssh_key_gitee" style="width: 750px; height: 1334px;" />
<img src="https://cdn.jsdelivr.net/gh/yanglbme/gitee-pages-action@main/images/wechat_notification.jpg" alt="add_ssh_key_gitee" style="width: 750px; height: 1334px;" />

## 错误及解决方案

| # | 错误 | 解决方案 |
| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1 | Error: Wrong username or password, login failed . | 帐号或密码错误，请检查参数 `gitee-username`、`gitee-password`是否准确配置。 |
| 2 | Error: Need captcha validation, please visit https://gitee.com/login, login to validate your account. | 需要图片验证码校验。可以手动登录 Gitee 官方，校验验证码。 |
| 3 | Error: Need phone captcha validation, please follow wechat official account "Gitee" to bind account to turn off authentication. | 需要短信验证码校验。可以关注 Gitee 微信公众号，并绑定 Gitee 帐号，接收登录提示。[#6](https://github.com/yanglbme/gitee-pages-action/issues/6) |
| 4 | Error: Do not deploy frequently, try again one minute later. | 短期内频繁部署 Gitee Pages 导致，可以稍后再触发自动部署。 |
| 5 | Error: Deploy error occurred, please check your input `gitee-repo`. | `gitee-repo` 参数格式如：`doocs/advanced-java`，并且严格区分大小写，请准确填写。[#10](https://github.com/yanglbme/gitee-pages-action/issues/10) |
| 6 | Error: Unknown error occurred in login method, resp: ... | 登录出现未知错误，请在 [issues](https://github.com/yanglbme/gitee-pages-action/issues) 区反馈。 |
| 7 | Error: Rebuild page error, status code: xxx | 更新 Pages 时状态码异常，请尝试再次触发 Action 执行。也可能为 gitee pages 未初始化，第一次需要手动部署 gitee pages。 |
| 8 | Error: HTTPSConnectionPool(host='gitee.com', port=443): Read timed out. (read timeout=6)<br><br>Error: HTTPSConnectionPool(host='gitee.com', port=443): Max retries exceeded with url: /login (Caused by ConnectTimeoutError(<urllib3.connection.HTTPSConnection object at 0x7f6c889d42e8>, 'Connection to gitee.com timed out. (connect timeout=6)')) | 网络请求出错，请尝试 Re-run jobs 。[#27](https://github.com/yanglbme/gitee-pages-action/issues/27) |
| 9 | [email protected]: Permission denied (publickey).<br>fatal: Could not read from remote repository.<br>Please make sure you have the correct access rights and the repository exists.. | SSH 公私钥配置有问题，或是使用了带密码的私钥，请参照上文提及的密钥配置步骤进行相应配置。[#29](https://github.com/yanglbme/gitee-pages-action/issues/29) |
| 10 | Hexo Gitee Pages 自动部署站点问题。 | [@No5972](https://github.com/No5972) 详细给出了一种解决方案。[#34](https://github.com/yanglbme/gitee-pages-action/issues/34) |
| ... | ... | ... |
| # | 错误 | 解决方案 |
| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1 | Error: Wrong username or password, login failed . | 帐号或密码错误，请检查参数 `gitee-username`、`gitee-password`是否准确配置。 |
| 2 | Error: Need captcha validation, please visit https://gitee.com/login, login to validate your account. | 需要图片验证码校验。可以手动登录 Gitee 官方，校验验证码。 |
| 3 | Error: Need phone captcha validation, please follow wechat official account "Gitee" to bind account to turn off authentication. | 需要短信验证码校验。可以关注 Gitee 微信公众号，并绑定 Gitee 帐号，接收登录提示。[#6](https://github.com/yanglbme/gitee-pages-action/issues/6) |
| 4 | Error: Do not deploy frequently, try again one minute later. | 短期内频繁部署 Gitee Pages 导致，可以稍后再触发自动部署。 |
| 5 | Error: Deploy error occurred, please check your input `gitee-repo`. | `gitee-repo` 参数格式如：`doocs/leetcode`，并且严格区分大小写，请准确填写。[#10](https://github.com/yanglbme/gitee-pages-action/issues/10) |
| 6 | Error: Unknown error occurred in login method, resp: ... | 登录出现未知错误，请在 [issues](https://github.com/yanglbme/gitee-pages-action/issues) 区反馈。 |
| 7 | Error: Rebuild page error, status code: xxx | 更新 Pages 时状态码异常，请尝试再次触发 Action 执行。也可能为 gitee pages 未初始化，第一次需要手动部署 gitee pages。 |
| 8 | Error: HTTPSConnectionPool(host='gitee.com', port=443): Read timed out. (read timeout=6)<br><br>Error: HTTPSConnectionPool(host='gitee.com', port=443): Max retries exceeded with url: /login (Caused by ConnectTimeoutError(<urllib3.connection.HTTPSConnection object at 0x7f6c889d42e8>, 'Connection to gitee.com timed out. (connect timeout=6)')) | 网络请求出错，请尝试 Re-run jobs 。[#27](https://github.com/yanglbme/gitee-pages-action/issues/27) |
| 9 | [email protected]: Permission denied (publickey).<br>fatal: Could not read from remote repository.<br>Please make sure you have the correct access rights and the repository exists.. | SSH 公私钥配置有问题，或是使用了带密码的私钥，请参照上文提及的密钥配置步骤进行相应配置。[#29](https://github.com/yanglbme/gitee-pages-action/issues/29) |
| 10 | Hexo Gitee Pages 自动部署站点问题。 | [@No5972](https://github.com/No5972) 详细给出了一种解决方案。[#34](https://github.com/yanglbme/gitee-pages-action/issues/34) |
| ... | ... | ... |

注：

1. `branch` 参数默认是 `master`，如果你是部署在 `gh-pages`(或者 `main`) 分支等等，务必指定 `branch: gh-pages`(或者 `branch: main`)。
1. `branch` 对应的分支，必须在仓库中实际存在，请不要随意（不）指定分支，否则可能导致 Gitee Pages 站点出现 404 无法访问的情况。
1. 示例中触发 Action 执行的事件设置为 `page_build`，你也可以根据实际情况指定为其它的触发事件。如下：
1. 对于 workflow 的触发事件，你可以根据项目实际情况，指定为其它的触发事件。比如：
```bash
on:
push:
Expand Down
Binary file added images/action.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/wechat_notification.jpg
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file removed images/wechat_notification.png
View file
Binary file not shown.

0 comments on commit d83200c

Please sign in to comment.