GitHub App oluşturma

Bu kılavuz, sunucunuza kendi GitHub kimliğini nasıl kazandıracağınızı gösterir. Yaklaşık iki dakika sürer, bunu yalnızca sunucu sahibi yapar ve sunucu başına yalnızca bir kez yapılması gerekir.

Buna ihtiyacınız olmayabilir

Resmî bir derleme zaten bir GitHub istemci id’siyle gelir, bu nedenle GitHub ile oturum açma hiçbir şey kaydetmeden kutudan çıktığı gibi çalışır — bir cihaz akışı yalnızca istemci id ile kimlik doğrular, dolayısıyla dağıtılması güvenlidir. Kendi uygulamanızı, SUNUCUnun kendisi olarak hareket etmesini istediğinizde (webhook’lar, PR yoklaması ve bilet eşitlemesi bir kişinin kimlik bilgisi yerine bir uygulama kurulumu üzerinde çalışır) ya da kaynaktan derleme yaptığınızda kaydedin.

Kendi hesabınızı sonradan bağlamak için GitHub entegrasyonunu kurma sayfasına bakın.

Sunucunuzun neden kendi uygulamasına ihtiyacı var

Tek bir kayıttan iki farklı iş çıkar ve ikisini de dürüst kılan şey uygulamadır:

İş	Bunu ne yanıtlar	Neden önemli
Bir kişi oturum açıyor	Uygulamanın istemci id’si, cihaz akışı üzerinden	Sunucuda, her cihazda size ait bir kimlik bilgisi edinirsiniz — yapıştıracak ya da döndürecek belirteç yok
Sunucu hareket ediyor	Uygulamanın id’si + özel anahtar → kurulum belirteci	Webhook’lar, PR yoklaması ve bilet eşitlemesi artık bir insanın belirtecinin hâlâ geçerli olmasına bağlı kalmaz

Bu tabloda olmayan şeye dikkat edin: bir istemci gizli anahtarı. GitHub’ın cihaz akışı — hem cihaz kodu isteği hem de belirteç yoklaması — yalnızca istemci id ile kimlik doğrular, dolayısıyla oturum açmak için saklanacak bir gizli anahtar yoktur.

Kendi uygulamanız olmadan da birincisi, derlemenin getirdiği istemci id üzerinden çalışır; ikincisi sunucu sahibinin kimlik bilgisine geri düşer, böylece arka plan işi ilk kurulumu yapan kişinin üzerine biner.

“Control Center’ın GitHub App’ini kur” diye bir düğme yok

Dağıtılmış bir GitHub App, herkesin sunucusu genelinde paylaşılan tek bir istemci gizli anahtarı ve tek bir kurulum anlamına gelirdi; böylece her çalışma alanının depo erişimi, o çalışma alanındaki hiç kimsenin denetlemediği kimlik bilgilerinden geçerdi. Bu nedenle her sunucu kendi uygulamasına sahiptir — bu kılavuz, bunun ne kadar az maliyetli olduğuyla ilgilidir.

Önkoşullar

• Siz sunucu sahibisiniz — providerApps.* işlemleri ona kapılıdır ve kart herkese görünmez
• Bir GitHub hesabı ya da uygulama oluşturabileceğiniz bir organizasyon
• Genel erişime açık hiçbir şey: oturum açma bir cihaz akışıdır, dolayısıyla sunucunun gelen bağlantı noktasına, tünele, geri çağırma URL’sine veya alan adına ihtiyacı yok

Uygulamayı kaydetme

1. github.com/settings/apps/new adresine gidin (bir organizasyon için: Settings → Developer settings → GitHub Apps → New GitHub App)
2. GitHub App name — herhangi bir şey; Control Center (yourname) olur. Sunucunun yaptığı commit’lerde ve yorumlarda görünür
3. Homepage URL — herhangi bir şey, örneğin https://github.com/your-name
4. Callback URL — boş bırakın. Cihaz akışında yoktur
5. Enable Device Flow’u işaretleyin. Oturum açmanın onsuz çalışamayacağı tek ayar budur
6. Webhook’ları ayrıca bağlamıyorsanız Webhook → Active işaretini kaldırın
7. Repository permissions altında en az şunları verin:
   • Contents: Read and write
   • Metadata: Read-only (zorunlu)
   • Pull requests: Read and write
   • Issues: Read and write — biletler için GitHub Issues kullanıyorsanız ve botun PR konuşması yorum araması için (bkz. Bir GitHub PR’dan Control Center ile konuşma)
   • Checks: Read-only — PR sayfasındaki CI durumu için
8. Where can this GitHub App be installed? altında uygun olanı seçin — kişisel bir sunucu için “Only on this account” doğrudur
9. Create GitHub App’e tıklayın

Üç değeri toplama

Uygulamanın sayfasında, oluşturduktan hemen sonra:

Değer	Yeri
App ID	General sekmesi, üst tarafta
Client ID	General sekmesi, “Client secrets” altında
Private key	Generate a private key — bir .pem indirilir

Özel anahtar dosyası bir kez indirilir ve GitHub onu bir daha göstermez. Yapıştırana kadar saklayın; her zaman yenisini oluşturabilirsiniz.

Bir istemci gizli anahtarı isteğe bağlıdır ve tam olarak tek bir şey sağlar: “Expire user authorization tokens” ayarını AÇIK bırakırsanız, her sekiz saatte bir yeniden oturum açmasını istemek yerine birinin belirtecini sessizce yenileyen şey odur. Oturum açmanın kendisi onu hiç kullanmaz.

Daha basit kurulum, bu süre sonunu KAPALI bırakmaktır; o zaman hiçbir yerde gizli anahtar gerekmez. Açık bırakırsanız bir gizli anahtar oluşturun ve Ayarlar → Sunucu → Tek oturum açma (Sağlayıcı uygulamaları kartı) bölümüne yapıştırın — bunun için bir ortam değişkeni yoktur ve hiçbiri derlemeye gömülmez, böylece sunucunuzda kalır.

Hesabınıza kurma

Kayıtlı olup kurulmamış bir uygulama kişilerin kimliğini doğrulayabilir ama hiçbir şey okuyamaz.

1. Uygulamanın sayfasında Install App’i açın
2. Hesabınıza ya da organizasyonunuza kurun
3. All repositories’i seçin ya da bu sunucunun görmesi gereken depoları seçin

Control Center’a yapıştırma

1. Ayarlar → Sunucu → Tek oturum açma bölümüne gidin ve Sağlayıcı uygulamaları kartına kaydırın
2. GitHub bloğunda her alanı ayarlayın:
   • Uygulama id — sayısal App ID
   • Özel anahtar — .pem dosyasının tamamını, BEGIN ve END satırları dahil yapıştırın
   • İstemci id — aynı sayfadan
   • İstemci gizli anahtarı — yalnızca bir tane oluşturduysanız (belirteç yenileme için)
3. Test’e tıklayın

Anahtar kaydedilirken ayrıştırılır, böylece kesilmiş ya da yanlış biçimde bir yapıştırma, saatler sonra arka plandaki bir istekte başarısız olmak yerine oracıkta reddedilir. Test daha ileri gider ve GitHub’a uygulamanın hangi hesaplara kurulu olduğunu sorar — “kaydedildi” ile “çalışıyor” farklı iddialardır ve yalnızca ikincisi bir şeyin çalışacağı anlamına gelir.

Kontrol noktası: GitHub bloğu “Sunucu kendisi olarak hareket edebilir ve kişiler oturum açabilir.” yazar ve Ayarlar → Çalışma alanı → Profil ve kimlik → Kod barındırma altındaki GitHub satırı artık GitHub ile oturum aç seçeneğini sunar.

Bunun yerine ortam değişkenleriyle yapılandırma

Headless ya da betikli bir kurulumda sunucu, kayıtlı bir değeri olmadığı ilk seferde her alanı ortamdan tohumlar:

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

Bunlar için komut satırı bayrağı yoktur — komut satırındaki bir gizli anahtar, ana makinedeki her süreç tarafından ps ile okunabilir. Bunları yapılandırmanın tek yeri ortamdır ve ortam, derlemenin getirdiği her şeyden üstündür. .env.template tam listedir.

Yerel geliştirme için depo kökündeki .env aynı değerleri taşır ve masaüstü uygulaması bunları başlattığı sunucuya aktarır. Anahtarı orada tek satıra koyun: bir .env değeri tek satırdır ve çift tırnak içindeki \n, yeni satıra çözülür.

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

GITHUB_APP_ID ve GITHUB_APP_PRIVATE_KEY, sandbox belirteç aracısının zaten okuduğu adların aynısıdır; bu nedenle ince taneli ajan belirteçleri yapılandırmış bir ana makine oturum açma şeridini bedavaya alır. Tohumlama alan başına bir kez olur — ondan sonra kayıtlı değer kazanır, böylece Ayarlar’da yapılan düzenlemeler sonraki yeniden başlatmada geri alınmaz.

Aynısını Linear için yapma

Linear’da cihaz akışı yoktur, dolayısıyla oturum açması tarayıcıda gidiş dönüştür ve bir geri çağırma URL’sine ihtiyaç duyar — Sağlayıcı uygulamaları kartı, kaydetmeniz gereken tam URL’yi gösterir.

1. linear.app/settings/api/applications/new adresinde bir OAuth uygulaması oluşturun
2. Callback URL’yi kartın gösterdiği URL’nin aynısı olarak ayarlayın
3. İstemci id ve İstemci gizli anahtarı değerlerini Linear bloğuna yapıştırın
4. İsteğe bağlı olarak bir çalışma alanı API anahtarı ekleyin — hiçbir insan istemediğinde sunucunun biletleri eşitlemek için kullandığı kimlik bilgisi budur

Sorun giderme

Oturum açma iletişim kutusu sağlayıcının cihaz kodu döndürmediğini söylüyor

Uygulamada Enable Device Flow kapalı. General altında açın ve yeniden deneyin.

Test, kimlik bilgilerinin çalıştığını ama uygulamanın hiçbir yere kurulmadığını söylüyor

Kayıt ve kurulum ayrı adımlardır. Uygulamanın sayfasında Install App’i açın ve kurun.

Test, özel anahtarın okunamadığını söylüyor

.pem dosyasının tamamını, -----BEGIN ve -----END satırları dahil yapıştırın. ed25519 ya da EC anahtarı kullanılamaz — GitHub Apps RSA ile imzalar.

Bir üye oturum açtı ama hiçbir depo göremiyor

Uygulama, bu depoları sahiplenen hesaba kurulu değildir ya da kurulumu farklı depoları seçer. Üyenin kendi oturum açması yalnızca uygulamanın görmesine izin verilen kadarını sağlar.

İlgili kılavuzlar

• GitHub entegrasyonunu kurma
• Bir GitHub PR’dan Control Center ile konuşma
• Bir kod barındırıcısı bağlama
• API anahtarlarını yönetme
• Slack entegrasyonunu kurma