85 lines
4.2 KiB
Markdown
85 lines
4.2 KiB
Markdown
---
|
||
title: Gitea 与 Actions 使用指南
|
||
lifecycle: active
|
||
evidence: documented
|
||
last_reviewed: 2026-09-16
|
||
last_verified: null
|
||
---
|
||
|
||
# Gitea 与 Actions
|
||
|
||
Gitea 托管 homelab 的代码、文档、issue 和 PR；Actions 执行仓库声明的 CI workflow。
|
||
入口为 <https://git.ddupan.top>，人类登录使用 [Authelia](authelia.md)。
|
||
|
||
本页依据现有服务 README、runner README、仓库 workflow 和官方使用文档整理。
|
||
本轮没有重新验证登录或运行示例；下面的操作是使用指南，不是本轮执行记录。
|
||
|
||
## 登录并找到项目
|
||
|
||
1. 打开 Gitea，选择已配置的 Authelia/OIDC 登录入口。
|
||
2. 在 Authelia 完成认证，返回 Gitea；应用权限由 Gitea 账号和仓库授权决定。
|
||
3. 打开目标仓库：Code 看源码，Issues 看动态工作，Pull Requests 看待合并改动，Actions 看 CI。
|
||
|
||
登录成功但看不到仓库时，先确认当前账号与仓库权限；OIDC 登录本身不会赋予所有项目的管理权。
|
||
已有账号应沿用原账号关联，遇到关联问题交由管理员处理，不另建同名账号规避。
|
||
|
||
## 创建与修改仓库
|
||
|
||
通过页面的 New Repository 创建仓库，选择所属用户或组织、名称及可见性。
|
||
仓库里的 Clone 按钮提供当前准确的 HTTPS/SSH 地址，复制该地址到 Git 客户端即可。
|
||
浏览器的 OIDC 会话不直接充当 Git 命令行凭据；客户端使用自己的凭据管理或已登记 SSH key。
|
||
|
||
日常修改先建分支、提交并推送，再开 PR 合并到 main。PR 应说明最终行为与验证结果，
|
||
不要把本机未提交的其他工作一并带入。基础设施仓库默认以中文维护 commit、PR 和文档。
|
||
|
||
## 第一个 CI workflow
|
||
|
||
在可信的测试仓库中启用 Repository Actions，再添加 `.gitea/workflows/hello.yaml`：
|
||
|
||
```yaml
|
||
name: Hello
|
||
on: [push]
|
||
jobs:
|
||
hello:
|
||
runs-on: [self-hosted, pod]
|
||
steps:
|
||
- name: Check execution
|
||
run: echo 'homelab CI is running'
|
||
```
|
||
|
||
推送该文件后，进入 Actions，打开本次运行和 hello job。
|
||
预期看到输出 `homelab CI is running` 且 job 成功；示例不需要检出源码或读取秘密。
|
||
若仓库设置没有 Actions 开关，先确认自己的管理权限。
|
||
workflow 路径、启用方式与事件规则见 [Gitea 官方入门](https://docs.gitea.com/usage/actions/quickstart/)。
|
||
|
||
维护者于 2026-09-16 说明：动态 `pod` 已上线测试，系统总并发量为 4；
|
||
纯 `self-hosted` runner 准备退役，新 workflow 使用明确的动态环境 labels。
|
||
本例据此采用 `[self-hosted, pod]`，本轮未实际运行示例。
|
||
若任务排队，除 runner 在线状态和 labels 外，也要考虑系统并发容量，不能把入队当作执行成功。
|
||
|
||
## 选择 runner
|
||
|
||
| 需求 | 使用入口 |
|
||
|---|---|
|
||
| 动态 Pod：已上线测试 | `[self-hosted, pod]`；系统总并发 4，不是每个仓库各有 4 个名额 |
|
||
| 动态 VM：正在工作 | `[self-hosted, vm]`；系统总并发 1，具体可用范围和进度以项目文档为准 |
|
||
| 旧常驻 runner：准备退役 | 纯 `self-hosted`，不再作为新 workflow 的默认示例；已有 workflow 需按需求迁移到明确的 Pod/VM 接口 |
|
||
|
||
上述阶段与容量由维护者于 2026-09-16 提供。实现与后续变化见
|
||
[Dynamic Runner](gitea-dynamic-runner.md) 及其项目文档。
|
||
|
||
常驻 runner 使用 privileged DinD，README 明确限定可信 workflow；不要为不可信代码开放它。
|
||
动态 runner 提供环境及获取自身 SPIFFE 身份的能力；登录下游、请求 token 和凭据清理由 workflow 负责。
|
||
|
||
## 遇到问题先看哪里
|
||
|
||
- 没有触发：看 Actions 是否启用、文件是否位于正确路径、事件是否匹配此次推送。
|
||
- 一直排队：看仓库可用 runner、在线状态和 labels；动态 runner 的问题回到其项目文档。
|
||
- job 失败：打开具体 step 的日志，从第一个失败步骤排查，不只看最终退出码。
|
||
- Git 命令失败但网页能登录：分别检查 Git 使用的身份、凭据方式和仓库权限。
|
||
|
||
服务部署与升级恢复以 homelab-infra `apps/gitea/README.md` 为入口；常驻 runner 以
|
||
`platform/gitea-runner/README.md` 为入口。本页不复制 token、密码或部署命令。
|
||
|
||
来源文件的固定版本与工作区差异见[来源追溯](../sources.md#gitea)。
|