Bumps the dev group: ruff 0.17.3 -> 0.17.4, coverage 7.17.0 -> 7.17.2 (requirements-dev.in and its hash-locked requirements-dev.txt).
🤖 YouTube Auto-Post
Tự động đăng thông báo video mới của kênh YouTube lên Telegram, Bluesky, Discord, Mastodon bằng GitHub Actions. Script chỉ dùng thư viện chuẩn Python, không cài gì thêm.
Important
Chế độ bảo trì từ 1.4.2: không thêm tính năng mới, trừ vài trường hợp ở mục 9 (cập nhật phụ thuộc, vá bảo mật, lên bản Python mới).
Mục lục
- Cách hoạt động
- Cấu trúc repo
- Secrets và biến
- Lấy token Telegram, Bluesky
- Nhánh
state - Phát triển
- Release
- Bảo vệ nhánh
- Trạng thái dự án
1. Cách hoạt động
Workflow notify.yml chạy 3 lần/ngày (06:30, 14:30, 22:30 UTC)
hoặc khi bấm Run workflow. GitHub thường khởi động lịch trễ 1–2 giờ; script không phụ thuộc
vào giờ chạy chính xác.
- Đọc RSS của kênh, giữ các video có
publishedtrongLOOKBACK_HOURSgần nhất (mặc định 48h). - Bỏ các ID đã có trong state (
last_video.txttrên nhánhstate). - Với mỗi video còn lại, kiểm tra trang watch: Premiere chưa lên sóng thì bỏ qua, lần chạy sau thử lại. RSS liệt kê Premiere từ lúc upload, nên không có bước này bot sẽ đăng sớm.
- Đăng lên từng platform có secret; platform thiếu secret thì skip.
- Lưu ID vào nhánh
statekhi ít nhất một platform đăng được. Nếu một platform đã cấu hình mà lỗi, job kết thúc đỏ vànotify-ci-failure.ymlbáo lên Discord.
Nội dung bài đăng:
🎬 New Video / Video Mới
<tiêu đề>
▶️ https://www.youtube.com/watch?v=...
Mastodon thêm dòng hashtag (HASHTAGS). Bluesky đính link card kèm thumbnail, tiêu đề quá dài
được cắt về 300 ký tự.
2. Cấu trúc repo
.github/
workflows/
notify.yml # Đăng bài theo lịch, ghi state lên nhánh `state`
ci.yml # ruff, pytest + coverage, zizmor, actionlint, SonarQube Cloud, Qodana — gate `ci` là required check
release.yml # tag v* → GitHub Release từ changelog → Discord
announce-release.yml # Caller vào reusable của poli0981/.github (release tạo tay)
notify-ci-failure.yml # Caller vào reusable của poli0981/.github
dependabot.yml
zizmor.yml
scripts/
notify.py # Điều phối: RSS → lọc → kiểm tra public → đăng → state → exit code
youtube.py # Parse RSS, cửa sổ thời gian, kiểm tra Premiere
message.py # Dựng nội dung bài đăng, cắt độ dài
http_client.py # urllib + một kiểu lỗi chung (HttpError)
state.py # Đọc/ghi last_video.txt
config.py # Biến môi trường
release_notes.py # Trích entry changelog cho release.yml
platforms/ # Mỗi module: post(video) -> PostStatus
tests/ # pytest, không gọi mạng
changelog/ # Chi tiết từng phiên bản (CHANGELOG.md ở root chỉ trỏ tới đây)
requirements-dev.in # Công cụ dev; requirements-dev.txt là bản khoá theo hash của nó
sonar-project.properties # SonarQube Cloud, đọc bởi job `sonar` của ci.yml
qodana.yaml # Qodana, đọc bởi job `qodana` của ci.yml
3. Secrets và biến
Repo → Settings → Secrets and variables → Actions → New repository secret.
| Secret | Platform | Bắt buộc | Ghi chú |
|---|---|---|---|
YOUTUBE_CHANNEL_ID |
YouTube | ✅ | UC... |
TELEGRAM_BOT_TOKEN |
Telegram | ✅ | Từ BotFather |
TELEGRAM_CHAT_ID |
Telegram | ✅ | -100... |
BLUESKY_HANDLE |
Bluesky | ✅ | ten.bsky.social |
BLUESKY_APP_PASSWORD |
Bluesky | ✅ | App Password, không phải mật khẩu đăng nhập |
DISCORD_WEBHOOK_URL |
Discord | Tuỳ chọn | https://discord.com/api/webhooks/ID/TOKEN |
MASTODON_INSTANCE_URL |
Mastodon | Tuỳ chọn | Không có / cuối |
MASTODON_ACCESS_TOKEN |
Mastodon | Tuỳ chọn | Scope write:statuses |
Cách lấy token Mastodon và Discord: SETUP_NEW_PLATFORMS.md.
Biến đặt trực tiếp trong notify.yml (không phải secret):
| Biến | Mặc định | Ý nghĩa |
|---|---|---|
LOOKBACK_HOURS |
48 |
Chỉ xét video published trong khoảng này |
HASHTAGS |
#gaming #gameplay #nocommentary |
Dòng hashtag cho Mastodon; để rỗng để tắt |
4. Lấy token Telegram, Bluesky
Telegram Bot
- Nhắn
/newbotcho @BotFather, nhận Bot Token. - Tạo Channel/Group, thêm bot làm admin.
- Gửi một tin bất kỳ vào channel rồi mở
https://api.telegram.org/bot<TOKEN>/getUpdates, tìm"chat":{"id": -100xxxxxxxxxx}.
Bluesky App Password
- bsky.app → Settings → App Passwords → tạo mới.
- Handle dạng
ten.bsky.social.
Discord không cần code: có thể dùng MonitoRSS đọc thẳng RSS kênh thay cho webhook.
5. Nhánh state
main được bảo vệ (mục 8) và GITHUB_TOKEN không bypass được, nên bot không thể commit lên main.
Danh sách ID đã đăng nằm trên nhánh orphan state, chỉ có một file last_video.txt (tối đa 100
ID, cũ nhất ở trên). Workflow checkout nhánh này vào thư mục state/ và push lại sau khi chạy.
Xem state hiện tại:
git fetch origin state && git show origin/state:last_video.txt
Muốn bot đăng lại một video (hoặc bỏ qua một video): sửa file trên nhánh state và push — nhánh
này không bị ruleset chặn.
Chạy local thì đặt STATE_FILE (mặc định state/last_video.txt, thư mục state/ đã gitignore).
6. Phát triển
Cần Python 3.15, cùng bản với CI, bot và release. Code dùng cú pháp chỉ có từ 3.14
(except A, B: không ngoặc), nên Python 3.13 trở xuống không chạy được.
python -m pip install --require-hashes --only-binary :all: -r requirements-dev.txt
ruff check . && ruff format --check .
pytest --cov --cov-report=term-missing
CI chạy đúng ba lệnh trên, cộng zizmor và actionlint cho workflow, SonarQube Cloud và Qodana (dưới
đây).
Coverage đo scripts/ theo cả dòng lẫn nhánh; dưới 95 % thì pytest --cov báo lỗi. Test không gọi
mạng: mọi request đi qua http_client, test thay hàm của nó bằng hàm giả. Các hàm build_text,
select_recent, is_public_html là chỗ để thêm test khi đổi hành vi.
Công cụ dev khoá theo hash: sửa requirements-dev.in, rồi biên dịch lại requirements-dev.txt
bằng pip-tools chạy trên Python 3.14 (Dependabot đọc bản Python ở header của file khoá và chỉ
hỗ trợ tới 3.14):
pip-compile --generate-hashes --allow-unsafe --strip-extras requirements-dev.in
SonarQube Cloud phân tích trong CI, không dùng Automatic Analysis (đã tắt trong cài đặt project;
bật lại thì scan trong CI lỗi). Job sonar chạy trên mỗi PR và mỗi lần push lên main, với
sonar-project.properties và coverage từ job test. Quality gate fail
thì sonar đỏ, kéo check ci đỏ theo. Cần secret SONAR_TOKEN (Actions secrets). PR của Dependabot
không đọc được secret đó nên bỏ qua phân tích mà vẫn xanh; main được phân tích sau khi merge.
Finding nào chấp nhận thì ghi trong sonar-project.properties kèm lý do, như zizmor.yml.
Qodana (JetBrains) là ý kiến thứ hai: job qodana chạy linter Ultimate qodana-python (bộ
inspection của PyCharm Professional, profile qodana.recommended) trên mỗi PR và mỗi lần push lên
main, cấu hình ở qodana.yaml. Linter chạy native trên runner với Python 3.15 của
job, không qua Docker. Có problem nào là job đỏ (failThreshold: 0), kéo check ci đỏ theo. Kết quả
nằm trên Qodana Cloud, thành annotation trên commit và một
comment tóm tắt trong PR. Cần secret QODANA_TOKEN (project token của Qodana Cloud, cũng là licence
Ultimate); PR của Dependabot bỏ qua như với SonarQube Cloud.
Chạy thử script local (cần secret trong env):
STATE_FILE=/tmp/state.txt YOUTUBE_CHANNEL_ID=UC... TELEGRAM_BOT_TOKEN=... TELEGRAM_CHAT_ID=... python scripts/notify.py
7. Release
-
Thêm entry
## x.y.z — YYYY-MM-DDvào đầuchangelog/1.x.mdqua PR. -
Sau khi merge, tag đã ký trên
mainvà push:git tag -s v1.2.0 -m v1.2.0 && git push origin v1.2.0 -
release.ymltạo GitHub Release với nội dung entry đó rồi gọi workflow thông báo Discord.
Quy ước changelog: changelog/README.md.
8. Bảo vệ nhánh
Ruleset main (không có bypass, kể cả admin): chỉ merge qua PR bằng squash, commit phải ký,
lịch sử tuyến tính, check ci phải xanh trên bản mới nhất của main, không force-push, không xoá.
Ruleset release-tags bảo vệ tag v* khỏi xoá/ghi đè. Dependabot mở PR gộp mỗi thứ Hai.
PR của Dependabot bị tụt sau main (check ci phải chạy trên bản mới nhất) thì comment
@dependabot rebase trong PR. Đừng bấm Update branch: GitHub rebase xong để lại commit không ký
nên ruleset chặn merge, và khi đã có người push vào PR thì Dependabot thôi cập nhật nó.
Repo private cá nhân không có CodeQL; thay bằng ruff rule S, zizmor, actionlint, SonarQube Cloud
và Qodana trong CI (mục 6).
9. Trạng thái dự án
Bảo trì từ 1.4.2 (2026-11-16). Bot đã làm đủ việc của nó, nên không thêm tính năng mới. Repo chỉ thay đổi trong ba trường hợp:
- Cập nhật phụ thuộc định kỳ. Dependabot mở PR gộp mỗi thứ Hai cho GitHub Actions và công cụ dev (mục 8); CI xanh thì merge.
- Bảo mật, và tính năng thật sự cần thiết. Phụ thuộc dính CVE mức High trở lên, hoặc thứ bot chạy trên đó có lỗ hổng nghiêm trọng (như Node.js, runtime của các GitHub Action), được sửa ngay, không chờ lịch Dependabot. Tính năng mới chỉ thêm khi được đánh giá là thật sự cần thiết.
- Bản ngôn ngữ mới. Lên bản Python kế tiếp, như 3.14 → 3.15 ở 1.4.0.
Đề xuất tính năng (issue hay PR) ngoài ba trường hợp trên sẽ không được nhận. Thay đổi nào cũng vẫn đi qua PR và CI (mục 6–8), và có entry trong changelog nếu người dùng bot nhận thấy.