Bỏ qua, đến phần nội dung

Đăng ký GitHub App ​

Trên dịch vụ dùng chung của PhillipCLI, GitHub App đã có sẵn và tổ chức của bạn chỉ việc cài (Kết nối GitHub). Trang này dành cho bản tự cài, nơi bạn tự đăng ký app một lần. Mất khoảng 10 phút.

Bạn cần gì ​

  • Một tài khoản GitHub tạo được app: owner của tổ chức GitHub sẽ đứng tên app, hoặc tài khoản cá nhân của bạn. Khách hàng cài app công khai từ tổ chức nào cũng được, nên app đặt ở đâu cũng được; thường chọn tổ chức của công ty.
  • Địa chỉ công khai của Tara (TARA_PUBLIC_URL). Muốn webhook chạy thì GitHub phải gọi tới được địa chỉ này qua HTTPS. Không có thì app vẫn dùng được, chỉ là webhook tắt (xem Chạy local).
  • Quyền chạy lệnh trên một máy có tara-admin và trình duyệt. Các lệnh này không cần cơ sở dữ liệu.

Đăng ký bằng một lệnh ​

  1. Chạy lệnh cài đặt. Bỏ --owner thì app được tạo trên tài khoản cá nhân của bạn.

    bash
    tara-admin github-app-setup --owner acme-corp \
      --name PhillipCLI --public-url https://tara.example.com --out-dir ./github-app
  2. Trình duyệt mở ra một trang có một nút. Đăng nhập GitHub nếu được hỏi, bấm nút, xem các cài đặt GitHub hiện ra rồi xác nhận. Terminal chờ tối đa 15 phút (--timeout). Nếu không mở được trình duyệt, lệnh in đường dẫn của trang để bạn tự mở.

  3. GitHub đưa bạn về một trang do chính lệnh phục vụ ở 127.0.0.1, báo bạn quay lại terminal. Lệnh ghi tara-github-app.env và tara-github-app.pem vào --out-dir.

  4. Nạp github-app/tara-github-app.env vào môi trường của tara-api, để tara-github-app.pem ở chỗ tara-api đọc được, rồi khởi động lại. Với bộ Compose một máy, chép PEM vào deploy/single-host/secrets/github-app.pem (chủ sở hữu uid 10001, quyền 400) và đặt TARA_GITHUB_APP_PRIVATE_KEY_FILE=/run/secrets/tara/github-app.pem; Compose gắn thư mục đó ở chế độ chỉ đọc. Với Helm, đặt PEM vào một Secret rồi khai báo githubApp.privateKey.existingSecret. Các biến được mô tả ở Tham chiếu tự cài.

--public-url mặc định lấy TARA_PUBLIC_URL nếu biến này có. --listen đổi địa chỉ cục bộ nhận redirect của GitHub (chỉ nhận địa chỉ loopback; mặc định lấy một cổng trống trên 127.0.0.1).

Hai tệp được ghi với quyền 600, chỉ mình bạn đọc được. Lệnh không ghi đè tệp đã có (và kiểm tra việc đó trước khi mở trình duyệt), cũng không in bí mật ra màn hình. Hãy giữ cả hai tệp ngoài git và chuyển vào nơi lưu bí mật của bạn.

Khi chưa có GitHub App, tara-api ghi một dòng cảnh báo lúc khởi động, để bạn biết khách hàng chưa kết nối được tổ chức GitHub.

Chạy local ​

Trên localhost, lệnh chạy được ngay. Cứ để TARA_PUBLIC_URL=http://localhost:8080 mặc định và chạy lại lệnh trên. GitHub không gửi được webhook tới localhost hay địa chỉ http thường, nên lệnh đăng ký app với webhook tắt và in một cảnh báo. Mọi thứ khác vẫn chạy. Thay đổi của installation, ví dụ thêm repo, đến Tara ở lần chuyển về setup kế tiếp hoặc lần đồng bộ hằng giờ, chứ không tức thì. Khi cần webhook, đăng ký lại với địa chỉ https.

Đăng ký làm hai bước (cách thủ công) ​

Luồng một lệnh chính là luồng manifest, tách làm hai. Dùng cách này khi trình duyệt và shell nằm trên hai máy khác nhau.

  1. Tạo trang đăng ký. Ở đây --owner cũng không bắt buộc.

    bash
    tara-admin github-app-manifest --owner acme-corp \
      --name PhillipCLI --public-url https://tara.example.com --out register-app.html
  2. Mở register-app.html trong trình duyệt đã đăng nhập GitHub, bấm nút, xem các cài đặt GitHub hiện ra rồi xác nhận.

  3. GitHub đưa bạn về địa chỉ công khai của bạn, kèm ?code=... trên thanh địa chỉ. Bạn chép mã đó. Mã dùng được một lần và hết hạn sau một giờ.

  4. Đổi mã lấy thông tin của app, rồi làm tiếp như bước 4 ở trên.

    bash
    tara-admin github-app-convert --code <code> --out-dir ./github-app

Dùng --redirect-url để GitHub đưa bạn tới nơi khác sau khi đăng ký, và bỏ --out thì trang được in ra terminal. Địa chỉ localhost hoặc http cũng làm webhook tắt ở lệnh này.

Manifest đặt những gì ​

Cài đặtGiá trị
Chế độ hiển thịCông khai, để khách hàng cài lên tổ chức của họ
Webhook URL<TARA_PUBLIC_URL>/webhooks/github; tắt khi địa chỉ là localhost hoặc http
Setup URL<TARA_PUBLIC_URL>/auth/github-app/setup
Callback URL<TARA_PUBLIC_URL>/auth/github-app/setup và <TARA_PUBLIC_URL>/auth/scm-user/callback (cái thứ hai cho nút Kết nối GitHub một cú bấm trên Bandum)
Request user authorization (OAuth) during installationBật
Redirect on updateBật
Quyền với repoContents, Issues, Pull requests: đọc và ghi; Metadata: chỉ đọc
Quyền với tổ chứcMembers: chỉ đọc
Sự kiệnOrganization, Membership, Push, Repository (GitHub luôn gửi Installation và Installation repositories)

Ngoài một nút, bản thân app không ghi vào repo: nút Create standard labels ở trang dự án (owner, admin) tạo các label status:, type:, level: bằng token installation ngắn hạn, chỉ giới hạn vào repo đó và quyền Issues: write (ph bandum labels init làm cùng việc bằng token của chính nhà phát triển); installation chưa chấp nhận quyền này thì nút trả issues_write_required. Quyền ghi để người bấm Kết nối GitHub trên Bandum ghi được kết quả kiểm thử bằng chính tài khoản của họ: token GitHub cấp lúc đó hành động thay người ấy và không bao giờ vượt quyền của app. Token Tara cấp cho Ryoma, Bandum để đồng bộ vẫn chỉ đọc, vì Tara luôn xin quyền đọc tường minh. App đăng ký từ trước với quyền chỉ đọc thì nâng Contents, Issues, Pull requests lên đọc và ghi, thêm callback URL thứ hai, bật Expire user authorization tokens; mỗi tổ chức đã cài app phải chấp nhận quyền mới. Xem docs/design/scm-user-token.md.

Đăng ký bằng tay ​

Bạn thích dùng màn hình GitHub? Tạo app ở Settings › Developer settings › GitHub Apps của tổ chức với các giá trị trên, rồi tạo private key và client secret. Sáu biến bạn tự đặt.

Kiểm tra ​

Mở Settings › GitHub trong Tara bằng tài khoản Owner hoặc Admin rồi bấm Connect GitHub. GitHub sẽ mở trang cài app của bạn. Thiếu một trong sáu biến thì tính năng tắt. Đặt thiếu một phần thì Tara từ chối khởi động, để một app cấu hình dở không chạy.

Đọc thêm ​