Token cài đặt GitHub App: giới thiệu header ghi đè theo từng yêu cầu

GitHub đã giới thiệu một header yêu cầu tạm thời có tên X-GitHub-Stateless-S2S-Token để hỗ trợ việc triển khai dần dần định dạng token mới cho token cài đặt GitHub App. Thông qua header này, nhà phát triển có thể thử trước tác động của định dạng token mới và, nếu cần, vẫn giữ định dạng token cũ.

Nội dung chính

Header X-GitHub-Stateless-S2S-Token

Khi gửi yêu cầu POST /app/installations/:installation_id/access_tokens, bạn có thể đặt header này để ghi đè quyết định triển khai định dạng token ở phía máy chủ.

Giá trị header	Tác dụng
enabled	Trả về token stateless (định dạng JWT) bất kể tiến độ triển khai.
disabled	Trả về token stateful (opaque cũ) ngay cả khi tích hợp đã nằm trong đợt triển khai.
(không có)	Tuân theo hành vi triển khai thông thường.

Định dạng token mới (JWT tiền tố ghs_)

Token stateless mới có định dạng JWT với tiền tố ghs_, dài khoảng 520 ký tự và chứa hai dấu chấm (.). Token stateful hiện có là một chuỗi opaque ngắn hơn và không có dấu chấm.

Nhà phát triển nên kiểm tra các điểm sau để xác minh ứng dụng xử lý đúng định dạng token mới:

• Loại bỏ các giả định hardcode về độ dài token
• Cập nhật regex dùng để kiểm tra token (regex khuyến nghị: ghs_[A-Za-z0-9\._]{36,})
• Đặt cột cơ sở dữ liệu lưu token cho phép tối thiểu từ 520 ký tự trở lên
• Đảm bảo mã kiểm tra hoặc xác thực token xử lý token ghs_ như một chuỗi opaque

Cách chuẩn bị

1. Kiểm thử với enabled: Gọi endpoint bằng header opt-in và xác nhận ứng dụng chấp nhận định dạng token mới theo luồng end-to-end.
2. Kiểm thử với disabled: Xác nhận ứng dụng vẫn hoạt động với định dạng opaque cũ, để bảo đảm vẫn vận hành bình thường nếu token stateless tạm thời không khả dụng.
3. Gỡ header: Khi cả hai luồng đều đã được xác thực, hãy gỡ header. Quá trình rollout của GitHub sẽ tự động quản lý định dạng token.

Lưu ý

• Header này chỉ mang tính tạm thời và sẽ không còn được hỗ trợ vào một thời điểm sẽ được thông báo riêng trong tương lai.
• Các token cài đặt ứng dụng hiện có sẽ tiếp tục hoạt động cho đến khi hết hạn.
• Thay đổi này áp dụng cho môi trường GitHub Enterprise Cloud và Data Residency; GitHub Enterprise Server không bị ảnh hưởng.
• Các đợt triển khai trong tương lai sẽ chỉ áp dụng định dạng token mới cho token server-to-server cài đặt GitHub App (bao gồm Actions GITHUB_TOKEN).

Xem chi tiết tại blog GitHub.