Δημιουργία της GitHub App

Αυτός ο οδηγός δείχνει πώς να δώσετε στον διακομιστή σας τη δική του ταυτότητα GitHub. Διαρκεί περίπου δύο λεπτά, το κάνει μόνο ο ιδιοκτήτης του διακομιστή και χρειάζεται να γίνει μία μόνο φορά ανά διακομιστή.

Μια επίσημη έκδοση φέρνει ήδη ένα client id του GitHub, οπότε η Σύνδεση με GitHub λειτουργεί αμέσως, χωρίς καμία καταχώριση — μια ροή με κωδικό συσκευής αυθεντικοποιείται μόνο με το client id, οπότε είναι ασφαλές να διανέμεται. Καταχωρίστε τη δική σας εφαρμογή όταν θέλετε ο ίδιος ο διακομιστής να ενεργεί ως ο εαυτός του (webhooks, περιοδικός έλεγχος PR και συγχρονισμός εισιτηρίων να εκτελούνται σε μια εγκατάσταση εφαρμογής αντί στα διαπιστευτήρια ενός ατόμου), ή όταν κάνετε build από πηγαίο κώδικα.

Για να συνδέσετε τον δικό σας λογαριασμό στη συνέχεια, δείτε Ρύθμιση ενσωμάτωσης GitHub.

Γιατί ο διακομιστής σας χρειάζεται τη δική του εφαρμογή

Από μία καταχώριση προκύπτουν δύο διαφορετικές δουλειές, και η εφαρμογή είναι αυτό που κάνει και τις δύο ειλικρινείς:

Δουλειά	Τι την απαντά	Γιατί έχει σημασία
Ένα άτομο συνδέεται	Το client id της εφαρμογής, μέσω της ροής με κωδικό συσκευής	Παίρνετε ένα διαπιστευτήριο που είναι δικό σας, στον διακομιστή, σε κάθε συσκευή — χωρίς token για επικόλληση ή ανανέωση
Ο διακομιστής ενεργεί	Το id της εφαρμογής + το ιδιωτικό κλειδί → token εγκατάστασης	Τα webhooks, ο περιοδικός έλεγχος PR και ο συγχρονισμός εισιτηρίων σταματούν να εξαρτώνται από το αν το token ενός ανθρώπου είναι ακόμη έγκυρο

Προσέξτε τι δεν υπάρχει σε αυτόν τον πίνακα: ένα μυστικό πελάτη. Η ροή με κωδικό συσκευής του GitHub αυθεντικοποιείται μόνο με το client id — τόσο το αίτημα του κωδικού συσκευής όσο και ο περιοδικός έλεγχος του token — οπότε δεν υπάρχει μυστικό να κρατήσετε για τη σύνδεση.

Χωρίς δική σας εφαρμογή, το πρώτο λειτουργεί ακόμη μέσω του client id που φέρνει η έκδοση· το δεύτερο πέφτει στο διαπιστευτήριο του ιδιοκτήτη του διακομιστή, οπότε η εργασία παρασκηνίου βασίζεται σε όποιον ολοκλήρωσε πρώτος την αρχική διαμόρφωση.

Προϋποθέσεις

Είστε ο ιδιοκτήτης του διακομιστή — οι λειτουργίες providerApps.* είναι περιορισμένες σε αυτόν, και η κάρτα είναι αόρατη σε όλους τους άλλους
Ένας λογαριασμός GitHub, ή ένας οργανισμός στον οποίο μπορείτε να δημιουργήσετε εφαρμογές
Τίποτα δημόσια προσβάσιμο: η σύνδεση είναι ροή με κωδικό συσκευής, οπότε ο διακομιστής δεν χρειάζεται εισερχόμενη θύρα, σήραγγα, URL επιστροφής ή τομέα

Καταχωρίστε την εφαρμογή

Μεταβείτε στο github.com/settings/apps/new (για οργανισμό: Settings → Developer settings → GitHub Apps → New GitHub App)
GitHub App name — ό,τι θέλετε· το Control Center (yourname) είναι εντάξει. Εμφανίζεται στα commits και στα σχόλια που κάνει ο διακομιστής
Homepage URL — ό,τι θέλετε, π.χ. https://github.com/your-name
Callback URL — αφήστε το κενό. Η ροή με κωδικό συσκευής δεν έχει
Επιλέξτε Enable Device Flow. Αυτή είναι η μοναδική ρύθμιση χωρίς την οποία η σύνδεση δεν μπορεί να λειτουργήσει
Αποεπιλέξτε Webhook → Active, εκτός αν ρυθμίζετε τα webhooks ξεχωριστά
Στο Repository permissions, παραχωρήστε τουλάχιστον:
- Contents: Read and write
- Metadata: Read-only (υποχρεωτικό)
- Pull requests: Read and write
- Issues: Read and write, αν χρησιμοποιείτε τα GitHub Issues για εισιτήρια, και για την αναζήτηση σχολίων του bot στις συνομιλίες PR (δείτε Συνομιλία με το Control Center από GitHub PR)
- Checks: Read-only, για την κατάσταση του CI στη σελίδα PR
Στο Where can this GitHub App be installed?, επιλέξτε ό,τι ταιριάζει — το «Only on this account» είναι το σωστό για προσωπικό διακομιστή
Πατήστε Create GitHub App

Συλλέξτε τις τρεις τιμές

Στη σελίδα της εφαρμογής, αμέσως μετά τη δημιουργία:

Τιμή	Πού
App ID	Στην καρτέλα General, κοντά στην κορυφή
Client ID	Στην καρτέλα General, στο «Client secrets»
Private key	Generate a private key — κατεβαίνει ένα `.pem`

Το αρχείο του ιδιωτικού κλειδιού κατεβαίνει μία φορά και το GitHub δεν το ξαναδείχνει ποτέ. Κρατήστε το μέχρι να το επικολλήσετε· μπορείτε πάντα να δημιουργήσετε άλλο.

Ένα μυστικό πελάτη είναι προαιρετικό και προσφέρει ακριβώς ένα πράγμα: αν αφήσετε ενεργή την επιλογή «Expire user authorization tokens», είναι αυτό που ανανεώνει σιωπηλά το token κάποιου αντί να του ζητά να συνδεθεί ξανά κάθε οκτώ ώρες. Η ίδια η σύνδεση δεν το χρησιμοποιεί ποτέ.

Η απλούστερη ρύθμιση είναι να απενεργοποιήσετε αυτή τη λήξη, και τότε δεν χρειάζεται μυστικό πουθενά. Αν την κρατήσετε ενεργή, δημιουργήστε ένα μυστικό και επικολλήστε το στις Ρυθμίσεις → Διακομιστής → Ενιαία σύνδεση (κάρτα Εφαρμογές παρόχων) — δεν υπάρχει μεταβλητή περιβάλλοντος για αυτό, και καμία δεν είναι ενσωματωμένη σε κάποια έκδοση, οπότε παραμένει στον διακομιστή σας.

Εγκαταστήστε τη στον λογαριασμό σας

Μια εφαρμογή που έχει καταχωριστεί αλλά δεν έχει εγκατασταθεί μπορεί να αυθεντικοποιεί ανθρώπους και δεν μπορεί να διαβάσει τίποτα.

Στη σελίδα της εφαρμογής, ανοίξτε Install App
Εγκαταστήστε τη στον λογαριασμό ή στον οργανισμό σας
Επιλέξτε All repositories, ή τα αποθετήρια που πρέπει να βλέπει αυτός ο διακομιστής

Επικολλήστε τη στο Control Center

Μεταβείτε στις Ρυθμίσεις → Διακομιστής → Ενιαία σύνδεση και κυλήστε στην κάρτα Εφαρμογές παρόχων
Στο μπλοκ GitHub, ορίστε κάθε πεδίο:
- ID εφαρμογής — το αριθμητικό App ID
- Ιδιωτικό κλειδί — επικολλήστε ολόκληρο το .pem, μαζί με τις γραμμές BEGIN και END
- Client id — από την ίδια σελίδα
- Μυστικό πελάτη — μόνο αν δημιουργήσατε ένα (για την ανανέωση του token)
Πατήστε Δοκιμή

Το κλειδί αναλύεται τη στιγμή που αποθηκεύεται, οπότε μια κολοβωμένη ή λανθασμένης μορφής επικόλληση απορρίπτεται εκεί και τότε, αντί να αποτύχει σε ένα αίτημα παρασκηνίου ώρες αργότερα. Η Δοκιμή πάει παραπέρα και ρωτά το GitHub σε ποιους λογαριασμούς είναι εγκατεστημένη η εφαρμογή — το «αποθηκεύτηκε» και το «λειτουργεί» είναι διαφορετικοί ισχυρισμοί, και μόνο ο δεύτερος σημαίνει ότι κάτι θα εκτελεστεί.

Σημείο ελέγχου: το μπλοκ GitHub γράφει «Ο διακομιστής μπορεί να ενεργεί ως ο εαυτός του και οι άνθρωποι μπορούν να συνδεθούν.», και η γραμμή GitHub στις Ρυθμίσεις → Χώρος εργασίας → Προφίλ και ταυτότητα → Φιλοξενία κώδικα προσφέρει πλέον Σύνδεση με GitHub.

Διαμορφώστε τη με μεταβλητές περιβάλλοντος

Για εγκατάσταση headless ή μέσω σεναρίου, ο διακομιστής αρχικοποιεί κάθε πεδίο από το περιβάλλον την πρώτη φορά που δεν έχει αποθηκευμένη τιμή:

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

Δεν υπάρχουν σημαίες γραμμής εντολών για αυτά — ένα μυστικό στη γραμμή εντολών είναι αναγνώσιμο από κάθε διεργασία του κεντρικού υπολογιστή μέσω του ps. Το περιβάλλον είναι το μόνο σημείο για τη διαμόρφωσή τους και υπερισχύει ό,τι φέρνει η έκδοση. Το .env.template είναι η πλήρης λίστα.

Για τοπική ανάπτυξη, το .env στη ρίζα του αποθετηρίου φέρει τις ίδιες τιμές και η εφαρμογή επιφάνειας εργασίας τις περνά στον διακομιστή που εκκινεί. Βάλτε το κλειδί σε μία γραμμή εκεί: μια τιμή του .env είναι μία γραμμή, και το \n μέσα σε διπλά εισαγωγικά αποκωδικοποιείται σε αλλαγή γραμμής.

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

Το GITHUB_APP_ID και το GITHUB_APP_PRIVATE_KEY είναι τα ίδια ονόματα που διαβάζει ήδη ο μεσίτης token του sandbox, οπότε ένας κεντρικός υπολογιστής που έχει ρυθμίσει εκλεπτυσμένα token πρακτόρων παίρνει δωρεάν τη διαδρομή σύνδεσης. Η αρχικοποίηση γίνεται μία φορά ανά πεδίο — μετά κερδίζει η αποθηκευμένη τιμή, οπότε μια αλλαγή στις Ρυθμίσεις δεν αναιρείται από την επόμενη επανεκκίνηση.

Κάντε το ίδιο για το Linear

Το Linear δεν έχει ροή με κωδικό συσκευής, οπότε η σύνδεσή του γίνεται μέσω περιηγητή και χρειάζεται όντως URL επιστροφής — η κάρτα Εφαρμογές παρόχων σας δείχνει το ακριβές που πρέπει να καταχωρίσετε.

Δημιουργήστε μια εφαρμογή OAuth στο linear.app/settings/api/applications/new
Ορίστε το Callback URL στο URL που δείχνει η κάρτα, αυτολεξεί
Επικολλήστε το Client ID και το Client secret στο μπλοκ Linear
Προαιρετικά προσθέστε ένα Κλειδί API του χώρου εργασίας — αυτό είναι το διαπιστευτήριο που χρησιμοποιεί ο διακομιστής για τον συγχρονισμό εισιτηρίων όταν δεν το ζήτησε άνθρωπος

Αντιμετώπιση προβλημάτων

Το παράθυρο σύνδεσης λέει ότι ο πάροχος δεν επέστρεψε κωδικό συσκευής

Το Enable Device Flow είναι απενεργοποιημένο στην εφαρμογή. Ενεργοποιήστε το στο General και δοκιμάστε ξανά.

Η δοκιμή λέει ότι τα διαπιστευτήρια λειτουργούν αλλά η εφαρμογή δεν είναι εγκατεστημένη πουθενά

Η καταχώριση και η εγκατάσταση είναι ξεχωριστά βήματα. Ανοίξτε Install App στη σελίδα της εφαρμογής και εγκαταστήστε την.

Η δοκιμή λέει ότι δεν ήταν δυνατή η ανάγνωση του ιδιωτικού κλειδιού

Επικολλήστε ολόκληρο το αρχείο .pem, μαζί με τις γραμμές -----BEGIN και -----END. Ένα κλειδί ed25519 ή EC δεν μπορεί να χρησιμοποιηθεί — οι GitHub Apps υπογράφουν με RSA.

Ένα μέλος συνδέθηκε αλλά δεν βλέπει αποθετήρια

Η εφαρμογή δεν είναι εγκατεστημένη στον λογαριασμό που τα κατέχει, ή η εγκατάστασή της επιλέγει άλλα αποθετήρια. Η δική του σύνδεση παραχωρεί μόνο ό,τι επιτρέπεται να βλέπει η εφαρμογή.