Buat GitHub App

Panduan ini menunjukkan cara memberi server Anda identitas GitHub-nya sendiri. Prosesnya sekitar dua menit, hanya pemilik server yang melakukannya, dan cukup sekali per server.

Anda mungkin tidak memerlukannya

Build resmi sudah menyertakan client id GitHub, sehingga Masuk dengan GitHub langsung berfungsi tanpa perlu mendaftarkan apa pun — device flow mengautentikasi hanya dengan client id, jadi aman untuk disertakan. Daftarkan app Anda sendiri ketika Anda ingin SERVER bertindak sebagai dirinya sendiri (webhook, polling PR, dan sinkronisasi tiket berjalan pada instalasi app, bukan pada kredensial seseorang), atau ketika Anda membangun dari sumber.

Untuk menghubungkan akun Anda sendiri setelahnya, lihat Siapkan integrasi GitHub.

Mengapa server Anda memerlukan app sendiri

Satu pendaftaran menghasilkan dua pekerjaan berbeda, dan app-lah yang membuat keduanya jujur:

Pekerjaan	Yang menjawabnya	Mengapa penting
Seseorang masuk	Client id app, melalui device flow	Anda mendapat kredensial milik Anda sendiri, di server, di setiap perangkat — tanpa token yang harus ditempel atau dirotasi
Server bertindak	Id app + kunci privat → token instalasi	Webhook, polling PR, dan sinkronisasi tiket tidak lagi bergantung pada masih validnya token satu orang

Perhatikan apa yang tidak ada di tabel itu: client secret. Device flow GitHub mengautentikasi hanya dengan client id — baik permintaan kode perangkat maupun polling token — sehingga tidak ada rahasia yang perlu disimpan untuk masuk.

Tanpa app Anda sendiri, yang pertama tetap berfungsi melalui client id bawaan build; yang kedua beralih ke kredensial pemilik server, sehingga pekerjaan latar belakang menumpang pada siapa pun yang melakukan onboarding lebih dulu.

Tidak ada tombol “pasang GitHub App milik Control Center”

GitHub App yang didistribusikan berarti satu client secret bersama dan satu instalasi bersama di seluruh server semua orang, sehingga akses repositori setiap ruang kerja akan melewati kredensial yang tidak dikendalikan siapa pun di ruang kerja itu. Karena itu setiap server memiliki app-nya sendiri — panduan ini menunjukkan betapa kecil biayanya.

Prasyarat

• Anda adalah pemilik server — operasi providerApps.* dibatasi hanya untuknya, dan kartu itu tidak terlihat oleh orang lain
• Akun GitHub, atau organisasi tempat Anda dapat membuat app
• Tidak ada yang perlu dapat dijangkau publik: proses masuknya adalah device flow, sehingga server tidak memerlukan port masuk, tunnel, URL callback, atau domain

Daftarkan app

1. Buka github.com/settings/apps/new (untuk organisasi: Settings → Developer settings → GitHub Apps → New GitHub App)
2. GitHub App name — apa saja; Control Center (yourname) tidak masalah. Nama ini muncul pada commit dan komentar yang dibuat server
3. Homepage URL — apa saja, mis. https://github.com/your-name
4. Callback URL — biarkan kosong. Device flow tidak memilikinya
5. Centang Enable Device Flow. Ini satu-satunya setelan yang tanpanya proses masuk tidak dapat berfungsi
6. Hapus centang Webhook → Active kecuali Anda menyambungkan webhook secara terpisah
7. Di bawah Repository permissions, berikan setidaknya:
   • Contents: Read and write
   • Metadata: Read-only (wajib)
   • Pull requests: Read and write
   • Issues: Read and write, jika Anda memakai GitHub Issues untuk tiket, dan untuk pencarian komentar percakapan PR bot (lihat Bicara ke Control Center dari PR GitHub)
   • Checks: Read-only, untuk status CI di halaman PR
8. Di bawah Where can this GitHub App be installed?, pilih yang sesuai — “Only on this account” cocok untuk server pribadi
9. Klik Create GitHub App

Kumpulkan ketiga nilainya

Di halaman app, tepat setelah pembuatan:

Nilai	Di mana
App ID	Tab General, di dekat bagian atas
Client ID	Tab General, di bawah “Client secrets”
Private key	Generate a private key — berkas .pem diunduh

Berkas kunci privat hanya diunduh sekali dan GitHub tidak pernah menampilkannya lagi. Simpan sampai Anda menempelkannya; Anda selalu dapat membuat yang baru.

Client secret bersifat opsional dan hanya memberi satu hal: jika Anda membiarkan “Expire user authorization tokens” AKTIF, dialah yang memperbarui token seseorang secara diam-diam alih-alih memintanya masuk lagi setiap delapan jam. Proses masuknya sendiri tidak pernah memakainya.

Penyiapan yang lebih sederhana adalah mematikan masa berlaku itu, dan setelah itu tidak ada rahasia yang diperlukan di mana pun. Jika Anda membiarkannya aktif, buat rahasia dan tempel di Pengaturan → Server → Single sign-on (kartu Aplikasi penyedia) — tidak ada variabel lingkungan untuk rahasia itu, dan tidak ada yang ditanam dalam build, sehingga rahasia itu tetap berada di server Anda.

Pasang di akun Anda

App yang terdaftar tetapi tidak dipasang dapat mengautentikasi orang dan tidak dapat membaca apa pun.

1. Di halaman app, buka Install App
2. Pasang di akun atau organisasi Anda
3. Pilih All repositories, atau pilih repositori yang harus dilihat server ini

Tempel ke Control Center

1. Buka Pengaturan → Server → Single sign-on dan gulir ke kartu Aplikasi penyedia
2. Pada blok GitHub, isi setiap kolom:
   • Id aplikasi — App ID numeriknya
   • Kunci privat — tempel seluruh .pem, termasuk baris BEGIN dan END
   • Id klien — dari halaman yang sama
   • Rahasia klien — hanya jika Anda membuatnya (untuk penyegaran token)
3. Klik Tes

Kunci diurai saat disimpan, sehingga tempelan yang terpotong atau salah format langsung ditolak di situ, bukan gagal pada permintaan latar belakang berjam-jam kemudian. Tes melangkah lebih jauh dan menanyakan ke GitHub di akun mana app itu dipasang — “tersimpan” dan “berfungsi” adalah dua klaim yang berbeda, dan hanya yang kedua berarti ada sesuatu yang akan berjalan.

Titik pemeriksaan: blok GitHub berbunyi “Server dapat bertindak sebagai dirinya sendiri, dan orang dapat masuk”, dan baris GitHub di bawah Pengaturan → Ruang kerja → Profil & identitas → Hosting kode kini menawarkan Masuk dengan GitHub.

Konfigurasikan dengan variabel lingkungan sebagai gantinya

Untuk instalasi headless atau berbasis skrip, server menyemai setiap kolom dari lingkungan saat pertama kali tidak memiliki nilai tersimpan:

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

Tidak ada flag baris perintah untuk ini — rahasia di baris perintah dapat dibaca oleh setiap proses di host melalui ps. Lingkungan adalah satu-satunya tempat untuk mengonfigurasinya, dan itu mengalahkan apa pun yang disertakan build. .env.template adalah daftar lengkapnya.

Untuk pengembangan lokal, .env di akar repo membawa nilai yang sama dan aplikasi desktop meneruskannya ke server yang dijalankannya. Letakkan kunci itu pada satu baris di sana: nilai .env adalah satu baris, dan \n di dalam tanda kutip ganda didekode menjadi baris baru.

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

GITHUB_APP_ID dan GITHUB_APP_PRIVATE_KEY adalah nama yang sama yang sudah dibaca broker token sandbox, sehingga host yang telah mengonfigurasi token agen fine-grained mendapat jalur masuknya gratis. Penyemaian terjadi sekali per kolom — setelah itu nilai tersimpan yang menang, sehingga penyuntingan di Pengaturan tidak dibatalkan oleh mulai ulang berikutnya.

Lakukan hal yang sama untuk Linear

Linear tidak memiliki device flow, jadi proses masuknya berupa perjalanan bolak-balik melalui browser dan memang memerlukan URL callback — kartu Aplikasi penyedia menunjukkan URL persisnya untuk didaftarkan.

1. Buat aplikasi OAuth di linear.app/settings/api/applications/new
2. Setel Callback URL ke URL yang ditampilkan kartu, persis apa adanya
3. Tempel Id klien dan Rahasia klien ke blok Linear
4. Secara opsional tambahkan Kunci API ruang kerja — itulah kredensial yang dipakai server untuk menyinkronkan tiket saat tidak ada manusia yang meminta

Pemecahan masalah

Dialog proses masuk menyebut penyedia tidak mengembalikan kode perangkat

Enable Device Flow mati pada app. Aktifkan di bawah General, lalu coba lagi.

Tes menyebut kredensial berfungsi tetapi app tidak dipasang di mana pun

Pendaftaran dan pemasangan adalah langkah terpisah. Buka Install App di halaman app, lalu pasang.

Tes menyebut kunci privat tidak dapat dibaca

Tempel seluruh berkas .pem, termasuk baris -----BEGIN dan -----END. Kunci ed25519 atau EC tidak dapat dipakai — GitHub Apps menandatangani dengan RSA.

Seorang anggota berhasil masuk tetapi tidak melihat repositori

App tidak dipasang pada akun yang memilikinya, atau pemasangannya memilih repositori yang berbeda. Proses masuk milik mereka hanya memberikan apa yang boleh dilihat app.

Panduan terkait

• Siapkan integrasi GitHub
• Bicara ke Control Center dari PR GitHub
• Hubungkan host kode
• Kelola kunci API
• Siapkan integrasi Slack