OpenTag ile kodlama ajanı nasıl kurulur?
OpenTag kurulumunu bir VPS üzerinde yaparak Slack ve GitHub bildirimlerini kodlama ajanıyla birleştirin. TLS ingress, webhook imza doğrulaması ve token kapsamlarını yapılandırın.
OpenTag bir ajandan bahsettiğinizde ne yapar
OpenTag, bir Slack dizisindeki veya GitHub issue kaydındaki @mention ifadesini, kendi makinenizde çalışan bir kodlama ajanı görevine dönüştürür. Birisi bir issue üzerinde @opentag investigate this yorumunu yapar. Bir dinleyici platform olayını alır, imzasını kontrol eder, mention ifadesini ilişkili bir proje ile eşleştirir, yerel bir checkout üzerinde kodlama ajanını başlatır ve sonucu aynı dizide paylaşır.
Proje MIT lisanslıdır ve amplifthq/opentag adresinde bulunur. Ekim 2026 itibarıyla en yeni etiketli sürüm, 17 Ağustos 2026 tarihinde yayınlanan v0.10.0 sürümüdür. CLI, bir npm paketi olarak dağıtılır. Burada 0.10.0 sürümü latest etiketini, 0.11.0 sürümü ise next etiketini taşır; ancak v0.10.0 README dosyası hala 0.9.0 sürümünü dokümante edilmiş kararlı sürüm olarak belirttiğinden, bu kılavuz 0.9.0 sürümünü temel alır. Aşağıdaki her komut bu sürümü sabitler. OpenTag, 0.10.0 ile eklenen isteğe bağlı self-hosted Control Plane için bir adet resmi container imajı yayınlar. Bu imaj ghcr.io/amplifthq/opentag-control-plane olup linux/amd64 için derlenmiş ve kaynak SHA ile etiketlenmiştir. Herhangi bir latest etiketi bulunmadığından, imajı sha256 özeti ile sabitlemeniz gerekir. Bu kılavuz Control Plane kullanmadığından, burada sabitlediğiniz şey npm sürümüdür.
GitHub tarafı nedeniyle bu proje bir dizüstü bilgisayar projesi yerine bir VPS projesi haline gelir. GitHub, depo olaylarını bir kez kaydettiğiniz bir URL'ye HTTP isteği göndererek iletir; bu nedenle ilgili URL'nin yarın da aynı adreste yanıt verebiliyor olması gerekir.
Dört hareketli parça
Dinleyici (listener) platform olaylarını alır; her platformun kendi dinleyicisi bulunur. GitHub dinleyicisi, 3050 numaralı port üzerinde /github/webhooks yolunda bir HTTP uç noktasıdır. Slack Events API dinleyicisi ise 3040 numaralı port üzerinde /slack/events yolundadır. Slack ayrıca Socket Mode ile çalışabilir; bu modda uygulama giden bir WebSocket açar ve herhangi bir gelen port bağlantısına ihtiyaç duymaz.
Dağıtıcı (dispatcher) koordinatör görevi görür. Varsayılan olarak 3030 numaralı portu dinler, çalışma durumunu OPENTAG_DATABASE_PATH ile belirlenen yerel bir veritabanı dosyasında tutar ve her çalışma için bir denetim izi (audit trail) kaydeder. Kutunun dışındaki hiçbir şeyin bu porta erişmemesi gerekir.
Çalıştırıcı (runner) yerel bir arka plan servisidir (daemon). İş kuyruğunu düzenli olarak kontrol eder, bir çalışma talebini üstlenir, üzerinde bir kiralama (lease) tutar ve çalışma devam ettiği sürece varsayılan olarak her 15 saniyede bir sinyal (heartbeat) gönderir. Proje hedefi eksik olan veya kendi yapılandırmasındaki izin verilenler listesinde (allowlist) bulunmayan hiçbir çalışma talebini kabul etmez; bu kontrol, bir GitHub olayının aracınızı (agent) yetkilendirmediğiniz bir depoya yönlendirmesini engeller.
Executor, kodlama aracısının kendisidir. OpenTag, onu standart girdi ve çıktı üzerinden çalışan bir JSON-RPC protokolü olan ACP (agent client protocol) aracılığıyla başlatır. Böylece aracı, OpenTag’in sağladığı çalışma dizininde alt süreç olarak çalışır. Yerleşik adlar arasında echo, codex, claude-code, cursor, opencode, hermes ve openclaw bulunur. Örnek yapılandırmayla birlikte gelen executor olan echo ile başlayın. Bu, bir model kodunuza müdahale etmeden önce tüm akışın çalıştığını doğrular. İstem okuyan, araçları çağıran ve işlemin ne zaman tamamlandığına karar veren döngü hâlâ anlaşılması zor bir bileşense, önce küçük bir aracı döngüsünü kendiniz yazmanız bu işlem hattındaki hata türlerini çok daha kolay anlamanızı sağlar.
Sıralama asla değişmez: platform olayı, imza kontrolü, çalışma kaydı, talep, araç ve iş parçacığında (thread) yanıt.
Neden bir dizüstü bilgisayar ve tünel yeterli değildir
GitHub kurulum kılavuzu, ngrok http 3050 komutunu çalıştırmanızı ve tünel ana bilgisayarını depo webhook'una yapıştırmanızı söyler. Bu, ilk on dakika için işe yarar. Sorun artık adres değildir: ngrok'un ücretsiz planı her hesaba bir adet kararlı geliştirme alan adı verir ve ngrok http her yeniden başlatmada bunu yeniden kullanır. Sorun tünelin kendisidir. Tünel, yalnızca açık olan bir dizüstü bilgisayarda aracı süreç çalıştığı sürece yanıt verir ve bilgisayar uyku moduna geçtiğinde varlığı sona erer. GitHub, payload URL'sine denemeler yapmaya devam eder; bu nedenle webhook ayarlarındaki Recent Deliveries sekmesi, süreç sessiz kaldığı sürece hatalarla dolar. Kimse bir hafta boyunca durumu fark etmez, çünkü hiçbir şey yapmayan bir webhook, kimsenin bahsetmediği bir bot ile tamamen aynı görünür.
Bir VPS, bozulan kısımları düzeltir. DNS adı size ait olduğu için, bir kez yapıştırdığınız payload URL'si bir tünel sağlayıcısına bağımlı kalmadan doğru kalır. Makine uyku moduna girmez, bu nedenle saat 02:00'de gelen bir yorum yanıt alır. Önce sunucuyu düzgün bir şekilde hazırlayın: yeni bir VPS'te ilk on dakika kılavuzu, bu rehberin varsaydığı oturum açma kullanıcısını ve güvenlik duvarını kapsar.
Slack bir istisnadır. Socket Mode ile dışa doğru bağlantı kurar ve genel bir URL'ye ihtiyaç duymaz, bu nedenle yalnızca Slack kullanılan bir dağıtım kapalı kalabilir. GitHub'ın buna eşdeğer bir özelliği yoktur. Depo webhook'ları gelen HTTP istekleridir; bu da genel bir uç nokta, yani TLS (transport layer security) ve imza kontrolü gerektirir.
Ubuntu üzerinde sabitlenmiş bir sürümden OpenTag kurulumu
OpenTag v0.9.0, Node.js 22 veya daha yeni bir sürüm gerektirir; v0.10.0 sürümü ile bu gereksinim 22.14 seviyesine yükselmiştir. Ubuntu 24.04 kendi depolarında Node 18 ile geldiğinden, kurulumu NodeSource üzerinden yapın.
curl -fsSL https://deb.nodesource.com/setup_22.x -o nodesource_setup.sh
sudo -E bash nodesource_setup.sh
sudo apt install -y nodejs
node -vnode -v komutu v22 veya daha yüksek bir sürüm çıktısı vermelidir. Node 20 üzerinde kurulum sırasında EBADENGINE uyarısı alınır ve CLI başlatıldığında hata verebilir.
Servis için özel bir kullanıcı hesabı oluşturun. Ajan bu kullanıcının yetkileriyle çalışacağından, kendi oturumunuzu veya root hesabını kullanmamalısınız. VPS üzerinde en düşük yetkili kullanıcılar bölümü, bu ayrımın neden gerekli olduğunu açıklar.
sudo adduser --disabled-password --gecos "" opentag
sudo loginctl enable-linger opentag
sudo npm install -g @opentag/cli@0.9.0
command -v opentagcommand -v opentag komutu /usr/bin/opentag gibi bir yol çıktısı vermelidir. Linux üzerinde linger ayarı önemlidir: OpenTag arka plan servisini systemd aracılığıyla kurar; linger ayarı yapılmamış bir kullanıcı servisi, SSH oturumunuz kapandığı anda durur.
Kurulumu bu kullanıcı ile çalıştırın.
sudo -iu opentag opentag setupKurulum altı soru sorar: CLI dili, yerel dinleme adresi, kodlama ajanı, üzerinde çalışılacak yerel proje, kaydedilecek platform kimlik bilgileri ve çalışma modu. Dinleme adresini 127.0.0.1 olarak bırakın; nginx TLS termination işlemini yapıp trafiği buraya yönlendireceği için dinleyicilerin dışarıdan erişilebilir olması gerekmez. GitHub için ayrıca owner/repo formatında depo bilgisi, pull request açma izni, webhook portu (varsayılan 3050) ve token bilgisi istenir. Son aşamada arka plan servisi modunu seçin. Eğer halihazırda bir yapılandırmanız varsa ve servisi sorularla uğraşmadan kurmak istiyorsanız opentag setup --service komutunu kullanın.
Yapılandırma /home/opentag/.config/opentag/config.json dizinine, çalışma zamanı durumu ise /home/opentag/.local/state/opentag dizinine kaydedilir. Kurulum dosyayı oluşturduktan sonra bu anahtarları manuel olarak kontrol etmekte fayda vardır.
{
"runnerId": "runner_local",
"dispatcherUrl": "http://localhost:3030",
"runnerToken": "...",
"approvalMode": "ask",
"repositories": []
}Eski paylaşımlı pairingToken yerine, runner kapsamlı bearer token olan runnerToken kullanımını tercih edin. Yapılandırma dosyası, değerleri ortam değişkenlerinden veya diskteki bir dosyadan okuyan gizli referanslarla değiştirmediğiniz sürece kimlik bilgilerini düz metin olarak tutar. Her iki durumda da bu dosya sunucudaki en hassas veridir: dosya izinlerini 600 yapın, sahibi opentag olsun ve dosyayı asla bir git deposu içinde tutmayın. Konuyla ilgili daha geniş açıklama yapay zeka ajanlarında gizli bilgileri koruma bölümündedir.
Herhangi bir dış erişim vermeden önce kurulumu doğrulayın.
sudo -iu opentag opentag doctor
sudo -iu opentag opentag statusopentag doctor komutu dağıtıcıyı, bağlamaları, check-out işlemlerini ve yürütücüleri kontrol eder. opentag status komutu yapılandırmayı ve çalışma zamanı durumunu yazdırır; çalıştırmalar mevcut olduğunda tek bir çalıştırma ile sınırlandırılabilir. Bir platformu bu sunucuya yönlendirmeden önce doctor raporundaki tüm hataları giderin.
TLS'i öne alın ve yalnızca iki yol açın
nginx, TLS termination işlemini gerçekleştirir ve yalnızca iki yolu iletir. Diğer tüm istekler 404 hatası döndürür; böylece sunucuyu tarayan bir saldırgan, arka planda neyin çalıştığına dair bilgi edinemez.
/etc/nginx/sites-available/opentag üzerinde düz bir port 80 sunucu bloğu oluşturun ve aşağıdaki iki konumu ekleyin, ardından Certbot'un TLS kısmını yapılandırmasına izin verin.
sudo apt install -y nginx certbot python3-certbot-nginx
sudo ln -s /etc/nginx/sites-available/opentag /etc/nginx/sites-enabled/opentag
sudo nginx -t && sudo systemctl reload nginx
sudo certbot --nginx -d opentag.example.comnginx -t, syntax is ok ve test is successful çıktılarını verir; bu komut, bir yazım hatası ile siteyi devre dışı bırakacak bir yeniden yükleme işlemi arasındaki tek korumadır. Ubuntu 24.04 üzerinde nginx ile Certbot rehberi, yenileme işlemlerini ve ACME (otomatik sertifika yönetimi ortamı) doğrulamasının başarısız olma nedenlerini ele alır. Tamamlanmış blok şu şekildedir.
server {
listen 443 ssl;
server_name opentag.example.com;
ssl_certificate /etc/letsencrypt/live/opentag.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/opentag.example.com/privkey.pem;
client_max_body_size 2m;
location = /github/webhooks {
proxy_pass http://127.0.0.1:3050;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto https;
}
location = /slack/events {
proxy_pass http://127.0.0.1:3040;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto https;
}
location / {
return 404;
}
}location = /github/webhooks içindeki = tam eşleşme sağlar ve porttan sonra hiçbir şey içermeyen proxy_pass, orijinal URI'yi olduğu gibi iletir. = ifadesini kaldırırsanız, /github/webhooks/ altındaki her yol da iletilir; bu ise dinleyicinin ihtiyaç duyduğundan daha geniş bir saldırı yüzeyi oluşturur.
Güvenlik duvarı kısıtlı tutulmalıdır.
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw status3030, 3040 ve 3050 numaralı portlar asla dışarıya açılmaz. Bu servislerin tüm arayüzler yerine yalnızca loopback (yerel) adresine bağlı olduğunu doğrulayın.
sudo ss -tlnpHer OpenTag satırı 127.0.0.1:3030 veya benzeri bir değer içermelidir. 0.0.0.0:3050 ifadesini içeren bir satır, dinleyicinin tüm internete açık olduğunu ve yalnızca ufw tarafından engellendiğini gösterir; bu durum, tek bir güvenlik duvarı hatasıyla servisin dışarıya sızmasına neden olabilir. ufw güvenlik duvarı temelleri, varsayılan engelleme kuralının gerçekte ne işe yaradığını açıklar.
Ön kapıyı doğrulamak için iki kontrol yeterlidir. curl -I https://opentag.example.com/ komutu nginx'ten 404 yanıtını döndürür; bu, sertifikanın geçerli olduğunu ve tüm istekleri yakalayan (catch-all) bloğun kapalı olduğunu kanıtlar. İmza içermeyen /slack/events veya /github/webhooks istekleri asla 200 kodu döndürmemelidir.
Her imzayı doğrulayın, çünkü URL herkese açıktır
Herkes payload URL'sini bulabilir. Bu URL; depo ayarlarınızda, tarayıcı geçmişinizde veya bir destek kaydına yapıştırılmış ekran görüntüsünde yer alır. İmza, gerçek bir GitHub teslimatını, birinin elle yazdığı bir istekten ayıran tek unsurdur.
GitHub, her teslimatı webhook gizli anahtarı ile imzalar ve sonucu x-hub-signature-256 başlığında gönderir. OpenTag, bu başlığı platforms.github.webhookSecret ile karşılaştırarak doğrular. Projenin güvenlik notları kuralı doğrudan belirtir: /github/webhooks üzerinde imzalanmamış kaynak etkinliklerini kabul etmeyin. Slack, her isteği SLACK_SIGNING_SECRET ile imzalar ve bir zaman damgası ekler; böylece ele geçirilen bir gövde, saatler sonra tekrar oynatılamaz.
Bunu atlamak küçük bir risk değildir. Doğrulanmamış bir uç nokta, @opentag içeren elle yazılmış bir issue_comment payload'unu kabul eder ve OpenTag, bir yabancının talimatlarıyla, sizin token'ınızla, sizin checkout dizininizde bir kodlama aracısı çalıştırır. Yanıt, sahte payload'un belirttiği herhangi bir iş parçacığına gider.
OpenTag bunun üzerine iki katman ekler. Kaynak teslimatları teslimat kimliği ile izlenir, bu nedenle aynı etkinliğin tekrar gönderilmesi ikinci bir çalıştırmayı başlatmaz. Runner çağrıları idempotency anahtarlarını kabul eder, bu nedenle bir isteğin tekrar oynatılması, başka bir denetim etkinliği eklemeden başarı döndürür.
Hız sınırları yapılandırılabilir ve açık tutulmalıdır. OPENTAG_RATE_LIMIT_WINDOW_MS ve OPENTAG_RATE_LIMIT_MAX_REQUESTS istek hızını sınırlandırır, OPENTAG_MAX_REQUEST_BODY_BYTES gövde boyutunu sınırlar ve boyutu aşan bir payload 413 request_body_too_large ile reddedilir. OPENTAG_RATE_LIMIT_DISABLED=true yerel geliştirme için mevcuttur ve genel kullanıma açık bir sunucuda yeri yoktur. Aynı notlardan bir kural daha: genel bir aktarma URL'si HTTPS kullanmalıdır ve CLI, düz HTTP kullanımına yalnızca localhost için izin verir.
Bot gerçekte hangi token kapsamlarına ihtiyaç duyar?
GitHub üzerinde OpenTag, bir GitHub App yerine kapsamı daraltılmış (fine-grained) bir kişisel erişim token'ı kullanır. Dokümantasyon, App yolunun planlandığını ancak güncel CLI kurulumunda varsayılan olmadığını belirtir; bu durumun gözden kaçan bir sonucu vardır: bot, token'ı oluşturan kişi adına yorum yapar. Token'ı, her triyaj yanıtında adının görünmesinden rahatsız olmayacağınız bir hesap altında oluşturun.
Kapsamı kurulum kılavuzunda belirtildiği kadar dar tutun. Only select repositories seçeneğini tercih edin ve tek bir depo seçin. Issues: Read and write ve Pull requests: Read and write izinlerini verin. Bir mention'ı okumak ve başlıkta yanıt vermek için bu kadarı yeterlidir.
Eksik olan şeye dikkat edin: kod üzerinde yazma erişimi. preparePullRequestBranch değeri true olarak ayarlanmadığı sürece OpenTag branch push etmez; ayrıca kod yazan token ile yorum yazan token'ın aynı olmaması için ayrı bir githubApplyToken mevcuttur. Bunları birbirinden ayırın ve okuma-yorum yapma yolu birkaç hafta boyunca sorunsuz çalışana kadar yazma yetkisine sahip token'ı aktif etmeyin.
Kaçınılması gereken yapılandırma, All repositories genelinde Contents: Read and write yetkisine sahip bir token'dır. Bu depolardan herhangi birine yorum yapabilen herkes, artık commit haklarına sahip bir ajanı yönlendirebilir ve denetim izi (audit trail), işlemin token sahibi tarafından yapıldığını gösterir. Kapsamı, ajan güven kazandıktan sonra her seferinde tek bir depo olacak şekilde genişletin.
Slack üzerinde bot kapsamları app_mentions:read, chat:write, reactions:write ve channels:history şeklindedir. Özel kanallar ayrıca groups:history iznine ve message.groups olayına aboneliğe ihtiyaç duyar. Socket Mode, connections:write yetkisine sahip, xapp- ile başlayan uygulama seviyesinde bir token gerektirir. channels:history, botun eklendiği genel kanallardaki mesaj geçmişini okur; bu nedenle botu her yere değil, sadece istenen kanallara ekleyin.
Bir sorunun uçtan uca rotalanması
Webhook ilk adımdır. Depoda Settings, ardından Webhooks ve son olarak Add webhook yolunu izleyin. Payload URL kısmına https://opentag.example.com/github/webhooks, içerik türüne application/json girin ve secret olarak kurulumun oluşturduğu değeri kullanın. Yalnızca Issue comments ve Pull request review comments seçeneklerine abone olun, başka hiçbir şeyi seçmeyin.
GitHub, kaydettiğiniz anda bir ping gönderimi yapar. Recent Deliveries kısmını açın ve isteğin sunucuya ulaşıp ulaşmadığını kontrol edin. Burada görülen 502 hatası, nginx'in dinleyiciye ulaşamadığı anlamına gelir; bu GitHub ile ilgili değil, yerel bir sorundur.
Şimdi kullanmaya başlayın. Bir hatayı tanımlayan bir issue açın ve şu yorumu yapın:
@opentag triage this. Reproduce the report against the current main branch, then reply with the file and function most likely responsible, plus the test you would write first.Sırasıyla gerçekleşmesi gerekenler şunlardır: Recent Deliveries, 2xx yanıtıyla issue_comment gönderimini kaydeder. Dispatcher bir çalışma (run) kaydeder. Runner bunu üstlenir ve heartbeat göndermeye başlar. Executor checkout işlemini açar ve çalışmaya başlar. Yanıt, aynı issue dizisinde bir yorum olarak gelir. sudo -iu opentag opentag status, çalışma devam ederken durumu gösterir, böylece tahmin yürütmek yerine süreci izleyebilirsiniz.
İlk gerçek çalışmadan önce approvalMode değerini ask olarak ayarlayın. ask modunda çalışma duraklar ve durumu değiştirecek herhangi bir işlem yapmadan önce bir kullanıcıdan onay bekler. auto ve autonomous modları da mevcuttur ve bir ay boyunca transkriptleri okuduğunuz bir depoda, ilerleyen aşamalarda kullanmak için makul seçeneklerdir.
Slack tarafında aynı çalışma kanalda /bind owner/repo ile başlar, ardından bir mention gelir. Bot ayrıca /help, /status, /doctor, /stop ve /unbind confirm yanıtlarını da verir. Bağlamaları (bindings) kimin değiştirebileceğini OPENTAG_SLACK_BINDING_ADMIN_USER_IDS ile kısıtlayın; bu, Slack kullanıcı kimliklerinden oluşan virgülle ayrılmış bir listedir, çünkü bağlama, herkese açık bir kanalın sunucunuzdaki bir checkout ile eşleştirilmesidir.
Triage iyi bir ilk rotadır çünkü okuma yapar ancak yazma yapmaz ve yanıtın doğruluğunu değerlendirmek kolaydır. Review bir sonraki adımdır; burada ajan bir issue yerine bir diff üzerinde yorum yapar: kendi kendine barındırılan bir pull request inceleme ajanı, pull request'lere yönlendirilmiş aynı mimaridir. Ajanın çalışırken kendi sistemlerinize erişmesini istiyorsanız, bu bir VPS üzerinde MCP sunucuları kurmanın işidir. Web araması, triage'ın sürekli talep ettiği diğer bir yetenektir ve ajanı kendi SearXNG örneğinize bağlamak, bu aramaları kendi donanımınızda tutmanızı sağlar; bunun bedeli ise yabancı bir metnin ajana ulaştığı bir kanal daha eklemektir.
Ajan herkesin önünde hatalı bir yanıt verdiğinde ne olur?
Yanıt hatalı olacaktır. Asıl soru bunun maliyetinin ne olduğudur.
Herkese açık bir konuda verilen hatalı bir yanıt, ekibinizin tanıdığı bir isim altında yapılan bir yorumdur ve GitHub, gönderildiği anda abone olan herkese e-posta ile iletir. Yorumu silmek e-postayı geri çağırmaz. Aynı durum Slack bildirimleri için de geçerlidir. Yanıtın özelde doğru olmasından ziyade, genelde hatalı olma ihtimalini planlayın.
Hasarı sınırlayan dört seçenek mevcuttur ve bunlar yazdığınız herhangi bir istemden daha önemlidir.
askmodunda çalıştırın; böylece ajan öneride bulunur, bir kişi onaylar ve hatalı bir planın maliyeti yalnızca bir tıklama olur.preparePullRequestBranchdeğerini varsayılan olan false olarak bırakın; böylece kötü bir çalıştırmanın en kötü sonucu, hatalı bir dal (branch) yerine hatalı bir yorum olur.- Başlangıç için bir depo ve bir kanal bağlayın. Çalıştırıcı, proje hedefi yerel izin listesinin dışında kalan hiçbir çalıştırmayı kabul etmez; bu sayede bağlı olmayan bir depo, ajanı kendi içine çekemez.
- Yorum yapma token'ını herhangi bir uygulama (apply) token'ından ayrı tutun; böylece yazma erişimini iptal etmek, triyaj (triage) yetkisini de beraberinde götürmez.
Slack, yanlış giden bir çalıştırma için /stop komutuna sahiptir. Her çalıştırma ayrıca, onu başlatan bahsetmeyi ve ajanın ne yaptığını içeren bir denetim kaydı bırakır; sonrasında nerede hata yapıldığını anlamak için okuyacağınız şey budur.
Sosyal boyut, yapılandırma kadar önemlidir. Botu, insanların bir makine beklediği ve hatalı olabileceğini bildiği bir kanala yerleştirin. Bir insanın incelediği varsayılan kırk kişilik bir kanalda verilen kendinden emin ve hatalı bir yanıtın maliyeti, triyaj ile kazanılan zamandan daha fazladır. Kanal açıklamasına botun sahibinin kim olduğunu ve çıktısını kimin kontrol ettiğini yazın.
Yedeklemeler, yükseltmeler ve sürüm sabitleme
Her şey iki dizinde tutulur: /home/opentag/.config/opentag/config.json ve /home/opentag/.local/state/opentag. İlki kimlik bilgilerinizi, ikincisi ise çalışma geçmişini ve veritabanı dosyasını içerir. Her ikisini de 600 modunda yedekleyin ve sunucu dışında saklayın. Bunların kaybedilmesi, sunucuyu yeniden kurmak anlamına gelmez; yalnızca token'ların ve bağlantıların yeniden oluşturulmasını gerektirir.
Yükseltmeler, sürüm numarasını artırma ve yeniden başlatma işleminden ibarettir.
sudo npm install -g @opentag/cli@0.9.0
sudo -iu opentag opentag service stop
sudo -iu opentag opentag service start
sudo -iu opentag opentag doctor@latest sürümünü takip etmek yerine sürümü sabitleyin. Bu yazılım, canlı bir token ile deponuz üzerinde bir kodlama ajanı çalıştırır; bu nedenle gece yayınlanan bir sürüm, incelenmemiş bir değişiklik anlamına gelir. Güvenlik politikası, düzeltmelerin en son sürüme ve mevcut main dalına yönelik olduğunu, eski sürümlerin ise geriye dönük yamalar almayabileceğini belirtir. Sabitlenmiş bir 0.9.0 sürümü, v0.10.0 sürümünün zaten bir gerisindedir; bu nedenle sabitleme, değişiklik günlüğünü okuyup bilinçli bir şekilde ilerlemek anlamına gelir. Bu, sonsuza kadar v0.9.0 sürümünde kalmak demek değildir. Temmuz 2026'ya kadar olan geçmiş, ayda birkaç sürüm yayınlandığını göstermektedir ve v0.10.0 sürümü 17 Ağustos'ta yayınlanmıştır; bu, her yükseltme öncesinde sürüm notlarını okumak için iyi bir nedendir. v0.10.0 ayrıca GitHub çekme isteği (pull request) çalıştırmaları için yönetilen tamamlamayı varsayılan hale getirir ve OPENTAG_GITHUB_DEFAULT_COMPLETION=compat eski davranışı geri yükler.
Bundan sonraki notları dikkatlice okuyun. Ekim 2026 itibarıyla main üzerindeki değişiklik günlüğünün yayınlanmamış bölümü, GitHub'ı bir kaynak uygulama olarak ve bu kılavuzun dayandığı gömülü SQLite dağıtıcısını kaldıran, kasıtlı olarak bozucu bir 1.0 öncesi sıfırlamayı tanımlamaktadır. Henüz hiçbir etiketli sürüm bunu içermemektedir, ancak bir sürüm bunu içerdiğinde, yukarıdaki GitHub webhook yolu bu yükseltmeden sağ çıkamayacaktır.
FAQ
OpenTag çalıştırmak için VPS mi gerekir, yoksa dizüstü bilgisayar yeterli midir?
Sadece Slack için dizüstü bilgisayar yeterlidir; çünkü Socket Mode giden bir WebSocket açar ve gelen bir port gerektirmez. GitHub ise farklıdır. Depo web kancaları (repository webhooks), bir kez kaydettiğiniz bir URL'ye gelen HTTP üzerinden teslimat yapar; bu nedenle adresin sabit kalması ve siz uyurken de yanıt verebilmesi gerekir. Ücretsiz bir ngrok hesabı artık yeniden başlatmalarda aynı geliştirme alan adını korur, bu yüzden adres sabit kalır. Ancak tünel sabit değildir; çünkü yalnızca dizüstü bilgisayar açıkken ve aracı (agent) çalışırken yanıt verir. Bilgisayar kapalı olduğunda GitHub'ın teslimatları başarısız olur; bu durum depo içerisindeki Recent Deliveries sekmesinde hata kayıtları olarak görünür ve iş parçacığında (thread) sessizliğe neden olur. Sabit bir DNS adına ve sertifikaya sahip bir VPS bu sorunu ortadan kaldırır.
OpenTag hangi GitHub izinlerine ihtiyaç duyar?
Only select repositories (Yalnızca seçili depolar) ile sınırlandırılmış, Issues: Read and write (Sorunlar: Okuma ve yazma) ve Pull requests: Read and write (Çekme istekleri: Okuma ve yazma) yetkilerine sahip ince ayarlı bir kişisel erişim belirteci (personal access token) yeterlidir. Bu, bir bahsetmeyi okumak ve iş parçacığında yanıt vermek için gerekenleri kapsar. OpenTag'in dalları (branches) push etmesi için preparePullRequestBranch değerini true yapmadığınız sürece kod üzerinde yazma erişimine gerek yoktur. Ayrıca kod yazma belirtecinin yorum yapma belirtecinden ayrı tutulması için ayrı bir githubApplyToken mevcuttur. Tüm depolar üzerinde yazma yetkisi olan bir belirteçten kaçının; çünkü bu depolardan herhangi birine yorum yapabilen herkes, commit atabilen bir aracıya yön verebilir.
Hatalı giden bir çalışmayı nasıl durdurabilirim?
Slack'te tam olarak bunun için bir /stop komutu bulunur. Sunucuda opentag status neyin çalıştığını gösterir ve opentag service stop, tek bir çalışmadan ziyade tüm işlem hattını (pipeline) sonlandıran daemon sürecini durdurur. Her ikisine de ihtiyaç duymamak için approvalMode değerini ask olarak ayarlayın; böylece çalışmalar herhangi bir değişiklik yapmadan önce bir insanın onayını bekler. Ayrıca preparePullRequestBranch değerini false bırakın; böylece hatalı bir çalışma dal oluşturmak yerine bir yorum üretir.
İş parçacığı sessiz kalırken web kancam neden 502 hatası döndürüyor?
502 hatası OpenTag'den değil nginx'ten kaynaklanır ve proxy'nin dinleyiciye (listener) ulaşamadığı anlamına gelir. /var/log/nginx/error.log komutu connect() failed (111: Connection refused) while connecting to upstream çıktısını verecektir. Ya dinleyici durdurulmuştur ya da proxy_pass satırında belirtilenden farklı bir porttadır. sudo ss -tlnp komutunu çalıştırın ve GitHub için 127.0.0.1:3050, Slack için 127.0.0.1:3040 portunda bir şeyin dinleme yaptığını doğrulayın, ardından bağlamalar ve yürütücüler için opentag doctor komutunu çalıştırın.