Cipta GitHub App

Panduan ini menunjukkan cara memberikan pelayan anda identiti GitHub tersendiri. Ia mengambil masa kira-kira dua minit, hanya pemilik pelayan yang melakukannya, dan ia hanya perlu dilakukan sekali bagi setiap pelayan.

Anda mungkin tidak memerlukannya

Binaan rasmi sudah menyertakan ID klien GitHub, jadi Log masuk dengan GitHub berfungsi terus tanpa apa-apa yang perlu didaftarkan — aliran peranti mengesahkan dengan ID klien sahaja, jadi ia selamat untuk disertakan. Daftarkan apl anda sendiri apabila anda mahu PELAYAN bertindak sebagai dirinya sendiri (webhook, pengundian PR dan segerak tiket berjalan pada pemasangan apl dan bukan pada kelayakan seseorang), atau apabila anda membina daripada sumber.

Untuk menyambungkan akaun anda sendiri selepas itu, lihat Sediakan integrasi GitHub.

Mengapa pelayan anda memerlukan apl tersendiri

Dua tugasan berbeza terhasil daripada satu pendaftaran, dan apl itulah yang menjadikan kedua-duanya jujur:

Tugasan	Apa yang menjawabnya	Mengapa ia penting
Seseorang log masuk	ID klien apl, melalui aliran peranti	Anda mendapat kelayakan milik anda, pada pelayan, pada setiap peranti — tanpa token untuk ditampal atau diputar
Pelayan bertindak	ID apl + kunci peribadi → token pemasangan	Webhook, pengundian PR dan segerak tiket tidak lagi bergantung pada token seorang manusia yang masih sah

Perhatikan apa yang tidak ada dalam jadual itu: rahsia klien. Aliran peranti GitHub mengesahkan dengan ID klien sahaja — kedua-dua permintaan kod peranti dan pengundian token — jadi tiada rahsia yang perlu disimpan untuk log masuk.

Tanpa apl milik anda sendiri, yang pertama masih berfungsi melalui ID klien yang disertakan binaan; yang kedua berpaling kepada kelayakan pemilik pelayan, jadi kerja latar belakang bergantung pada sesiapa yang mula-mula mendaftar masuk.

Tiada butang “pasang GitHub App Control Center”

GitHub App yang diedarkan bermakna satu rahsia klien dikongsi dan satu pemasangan dikongsi merentas pelayan semua orang, jadi akses repositori setiap ruang kerja akan mengalir melalui kelayakan yang tiada sesiapa dalam ruang kerja itu kawal. Oleh itu setiap pelayan memiliki aplnya sendiri — panduan ini menunjukkan betapa kecilnya kosnya.

Prasyarat

• Anda ialah pemilik pelayan — operasi providerApps.* hanya dibenarkan kepadanya, dan kad itu tidak kelihatan kepada orang lain
• Akaun GitHub, atau organisasi tempat anda boleh mencipta apl
• Tiada apa-apa yang boleh dicapai secara awam: log masuk ialah aliran peranti, jadi pelayan tidak memerlukan port masuk, terowong, URL panggil balik atau domain

Daftarkan apl

1. Pergi ke github.com/settings/apps/new (untuk organisasi: Settings → Developer settings → GitHub Apps → New GitHub App)
2. GitHub App name — apa-apa sahaja; Control Center (yourname) pun boleh. Ia muncul pada commit dan komen yang dibuat oleh pelayan
3. Homepage URL — apa-apa sahaja, cth. https://github.com/your-name
4. Callback URL — biarkan kosong. Aliran peranti tidak memerlukannya
5. Tandakan Enable Device Flow. Inilah satu-satunya tetapan yang tanpanya log masuk tidak dapat berfungsi
6. Nyahpilih Webhook → Active melainkan anda menyambungkan webhook secara berasingan
7. Di bawah Repository permissions, berikan sekurang-kurangnya:
   • Contents: Read and write
   • Metadata: Read-only (mandatori)
   • Pull requests: Read and write
   • Issues: Read and write, jika anda menggunakan GitHub Issues untuk tiket, dan untuk carian komen perbualan PR oleh bot (lihat Bercakap dengan Control Center dari PR GitHub)
   • Checks: Read-only, untuk keadaan CI pada halaman PR
8. Di bawah Where can this GitHub App be installed?, pilih mana yang sesuai — “Only on this account” sesuai untuk pelayan peribadi
9. Klik Create GitHub App

Kumpulkan tiga nilai

Pada halaman apl, sejurus selepas penciptaan:

Nilai	Di mana
App ID	Tab General, berhampiran bahagian atas
Client ID	Tab General, di bawah “Client secrets”
Private key	Generate a private key — fail .pem dimuat turun

Fail kunci peribadi dimuat turun sekali sahaja dan GitHub tidak menunjukkannya lagi. Simpan ia sehingga anda menampalnya; anda sentiasa boleh menjana yang lain.

Rahsia klien adalah pilihan dan hanya membeli satu perkara: jika anda membiarkan “Expire user authorization tokens” HIDUP, inilah yang memperbaharui token seseorang secara senyap daripada memintanya log masuk semula setiap lapan jam. Log masuk itu sendiri tidak pernah menggunakannya.

Persediaan yang lebih mudah ialah mematikan tempoh luput itu, dan tiada rahsia diperlukan di mana-mana. Jika anda membiarkannya hidup, jana satu rahsia dan tampalkan dalam Tetapan → Pelayan → Daftar masuk tunggal (kad Apl penyedia) — tiada pemboleh ubah persekitaran untuknya, dan tiada yang dibakukan ke dalam binaan, jadi ia kekal pada pelayan anda.

Pasang pada akaun anda

Apl yang didaftarkan tetapi tidak dipasang boleh mengesahkan orang dan tidak membaca apa-apa.

1. Pada halaman apl, buka Install App
2. Pasangkannya pada akaun atau organisasi anda
3. Pilih All repositories, atau pilih repositori yang sepatutnya dilihat oleh pelayan ini

Tampalkan ke dalam Control Center

1. Pergi ke Tetapan → Pelayan → Daftar masuk tunggal dan tatal ke kad Apl penyedia
2. Pada blok GitHub, tetapkan setiap medan:
   • ID apl — ID Apl berangka
   • Kunci peribadi — tampalkan keseluruhan .pem, termasuk baris BEGIN dan END
   • ID klien — daripada halaman yang sama
   • Rahsia klien — hanya jika anda menjananya (untuk pembaharuan token)
3. Klik Uji

Kunci itu dihuraikan semasa ia disimpan, jadi tampalan yang terpotong atau berformat salah ditolak serta-merta dan bukannya gagal pada permintaan latar belakang berjam-jam kemudian. Uji melangkah lebih jauh dan bertanya kepada GitHub pada akaun mana apl itu dipasang — “tersimpan” dan “berfungsi” ialah dua dakwaan yang berbeza, dan hanya yang kedua bermakna sesuatu akan berjalan.

Titik semak: blok GitHub berbunyi “Pelayan boleh bertindak sebagai dirinya, dan orang boleh log masuk”, dan baris GitHub di bawah Tetapan → Ruang kerja → Profil & identiti → Hos kod kini menawarkan Log masuk dengan GitHub.

Konfigurasikannya dengan pemboleh ubah persekitaran sebaliknya

Untuk pemasangan tanpa kepala atau berskrip, pelayan menyemai setiap medan daripada persekitaran kali pertama ia tiada nilai tersimpan:

GITHUB_APP_ID=123456
GITHUB_APP_PRIVATE_KEY="$(cat control-center.private-key.pem)"
GITHUB_CLIENT_ID=Iv1.0123456789abcdef

Tiada bendera baris perintah untuk nilai-nilai ini — rahsia pada baris perintah boleh dibaca oleh setiap proses pada hos melalui ps. Persekitaran ialah satu-satunya tempat untuk mengkonfigurasinya, dan ia mengalahkan apa sahaja yang disertakan binaan. .env.template ialah senarai lengkapnya.

Untuk pembangunan setempat, .env pada akar repositori membawa nilai yang sama dan aplikasi desktop memasukkannya ke dalam pelayan yang dilancarkannya. Letakkan kunci itu pada satu baris di sana: nilai .env ialah satu baris, dan \n di dalam tanda petik berganda dinyahkod menjadi baris baharu.

GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nMIIEow…\n-----END RSA PRIVATE KEY-----"

GITHUB_APP_ID dan GITHUB_APP_PRIVATE_KEY ialah nama yang sama yang sudah dibaca oleh broker token kotak pasir, jadi hos yang mengkonfigurasi token ejen berbutir halus mendapat lorong log masuk itu secara percuma. Penyemaian berlaku sekali bagi setiap medan — selepas itu nilai tersimpan yang menang, jadi suntingan dalam Tetapan tidak dibatalkan oleh mula semula seterusnya.

Lakukan perkara yang sama untuk Linear

Linear tiada aliran peranti, jadi log masuknya ialah perjalanan pergi balik dalam penyemak imbas dan ia memang memerlukan URL panggil balik — kad Apl penyedia menunjukkan kepada anda URL sebenar yang perlu didaftarkan.

1. Cipta aplikasi OAuth di linear.app/settings/api/applications/new
2. Tetapkan Callback URL kepada URL yang ditunjukkan oleh kad itu, secara verbatim
3. Tampalkan ID klien dan Rahsia klien ke dalam blok Linear
4. Secara pilihan tambah kunci API ruang kerja — itulah kelayakan yang digunakan oleh pelayan untuk menyegerakkan tiket apabila tiada manusia yang meminta

Penyelesaian masalah

Dialog log masuk mengatakan penyedia tidak mengembalikan kod peranti

Enable Device Flow dimatikan pada apl. Hidupkannya di bawah General dan cuba lagi.

Uji mengatakan kelayakan berfungsi tetapi apl tidak dipasang di mana-mana

Pendaftaran dan pemasangan ialah langkah yang berasingan. Buka Install App pada halaman apl dan pasangkannya.

Uji mengatakan kunci peribadi tidak dapat dibaca

Tampalkan keseluruhan fail .pem, termasuk baris -----BEGIN dan -----END. Kunci ed25519 atau EC tidak boleh digunakan — GitHub Apps menandatangani dengan RSA.

Seorang ahli telah log masuk tetapi tidak melihat sebarang repositori

Apl itu tidak dipasang pada akaun yang memiliki repositori tersebut, atau pemasangannya memilih repositori yang berbeza. Log masuk ahli itu sendiri hanya memberikan apa yang dibenarkan untuk dilihat oleh apl.

Panduan berkaitan

• Sediakan integrasi GitHub
• Bercakap dengan Control Center dari PR GitHub
• Sambungkan hos kod
• Urus kunci API
• Sediakan integrasi Slack