Act ile GitHub Actions İş Akışlarınızı Yerelde Test Ederek Hızlandırın

GitHub Actions, modern yazılım geliştirme süreçlerinin vazgeçilmez bir parçası haline gelmiştir. Otomatik testlerden dağıtıma kadar birçok görevi otomatize ederek geliştiricilerin hayatını kolaylaştırır. Ancak, her değişiklikte iş akışının GitHub sunucularında çalışmasını beklemek, özellikle hata ayıklama aşamasında zaman kaybına ve verimsizliğe yol açabilir. İşte tam bu noktada Act devreye giriyor. Act, GitHub Actions iş akışlarınızı yerel makinenizde çalıştırmanıza olanak tanıyan güçlü bir araçtır. Bu makalede, Act’in ne olduğunu, nasıl kurulduğunu, nasıl kullanılacağını ve geliştirme sürecinize nasıl entegre ederek verimliliğinizi artırabileceğinizi detaylı bir şekilde inceleyeceğiz.

Giriş: GitHub Actions ve Yerel Test İhtiyacı

GitHub Actions Nedir?

GitHub Actions, doğrudan GitHub deponuzda yazılım geliştirme yaşam döngüsünü otomatikleştirmek için kullanabileceğiniz bir sürekli entegrasyon ve sürekli teslimat (CI/CD) platformudur. Kodunuzu derlemek, test etmek, paketlemek, yayınlamak veya dağıtmak gibi görevleri otomatize etmenizi sağlar. YAML dosyaları aracılığıyla tanımlanan iş akışları (workflows), belirli olaylar (push, pull request vb.) tetiklendiğinde otomatik olarak çalışır. Bu otomasyon, geliştirme hızını artırırken insan hatalarını azaltır ve kod kalitesini yükseltir.

Neden Yerel Test Gereklidir?

GitHub Actions’ın sunduğu tüm avantajlara rağmen, iş akışlarını her seferinde uzak sunucularda çalıştırmanın bazı dezavantajları vardır:

Yavaş Geri Bildirim Döngüsü: Küçük bir değişiklik veya hata ayıklama için bile, iş akışının sunucularda tamamlanmasını beklemek zaman alıcıdır. Bu durum, özellikle karmaşık iş akışlarında veya sık yapılan değişikliklerde geliştirme hızını düşürür.
Maliyet: GitHub Actions, belirli bir kullanım limitinin üzerinde ücretlendirme yapabilir. Her deneme çalıştırması bu limite dahil olur ve gereksiz maliyetlere yol açabilir.
Çevrimdışı Çalışma Zorluğu: İnternet bağlantısı olmadan iş akışlarınızı test etmek mümkün değildir.
Hata Ayıklama Zorluğu: Uzak sunuculardaki hataları ayıklamak, yerel ortamda hata ayıklamaktan daha zordur çünkü daha az kontrol ve daha sınırlı hata ayıklama araçlarına sahip olursunuz.

Act’in Sunduğu Çözüm

Act, bu sorunlara çözüm sunmak için tasarlanmıştır. GitHub Actions iş akışlarınızı yerel makinenizde, tıpkı GitHub’ın kendi runner’ları gibi Docker kapsayıcıları içinde çalıştırır. Bu sayede:

Anında geri bildirim alırsınız.
GitHub Actions dakikalarınızı harcamazsınız.
İnternet bağlantısına ihtiyaç duymadan çalışabilirsiniz.
Hataları yerel ortamda, tanıdık araçlarla kolayca ayıklayabilirsiniz.

Act Nedir ve Nasıl Çalışır?

Act’in Temel Amacı

Act, GitHub Actions iş akışlarınızı yerel makinenizde simüle etmeyi amaçlar. Bunu yaparken, her bir iş (job) için ayrı bir Docker kapsayıcısı oluşturur ve bu kapsayıcı içinde iş akışınızdaki adımları (steps) sırayla çalıştırır. Kapsayıcılar, GitHub Actions’ın sağladığı sanal ortamları taklit eder, böylece iş akışınızın uzakta çalışıyormuş gibi davranmasını sağlar.

Act Nasıl Kurulur?

Act’i kurmak oldukça basittir. Öncelikle makinenizde Docker kurulu ve çalışır durumda olmalıdır. Act, iş akışlarını çalıştırmak için Docker’ı kullanır.

macOS için Kurulum (Homebrew ile):

brew install act

Linux için Kurulum (Manuel):

curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

Windows için Kurulum (Chocolatey veya Scoop ile):

Chocolatey ile:

choco install act

Scoop ile:

scoop install act

Kurulumdan sonra, terminalinizde act --version komutunu çalıştırarak kurulumun başarılı olup olmadığını kontrol edebilirsiniz.

Act'in Bağımlılıkları (Docker)

Act, her bir GitHub Actions işini izole edilmiş bir ortamda çalıştırmak için Docker'a güvenir. İş akışınızdaki her adım, belirli bir Docker imajı içinde çalıştırılır. Act, varsayılan olarak catthehacker/ubuntu:act-latest gibi hafif imajları kullanır, ancak isterseniz kendi özel imajlarınızı da belirleyebilirsiniz. Bu, iş akışınızın bağımlılıklarını ve ortamını yerel olarak tam olarak kontrol etmenizi sağlar.

Act ile İlk İş Akışınızı Çalıştırma

Basit Bir Workflow Oluşturma

Şimdi Act ile basit bir GitHub Actions iş akışını nasıl çalıştıracağımıza bakalım. Projenizin kök dizininde .github/workflows/ klasörü altında main.yml adında bir dosya oluşturalım:

# .github/workflows/main.yml
name: Basit Yerel Test

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Merhaba Dünya Adımı
        run: echo "Merhaba, Act ile yerel test yapıyorum!"
      - name: Tarihi Yazdır
        run: date
      - name: Dizin İçeriğini Listele
        run: ls -la

`act` Komutunun Temelleri

Bu iş akışını yerel olarak çalıştırmak için terminalinizde projenizin kök dizinindeyken basitçe act komutunu çalıştırın:

act

Act, ilk çalıştırmada size hangi Docker imajını kullanmak istediğinizi sorabilir (örneğin, micro, medium, large). Genellikle micro veya medium yeterli olacaktır. Act, iş akışınızdaki adımları sırayla çalıştıracak ve çıktıyı terminalinize yazdıracaktır. İşlem tamamlandığında, iş akışınızın başarılı olup olmadığını ve her adımın çıktısını görebilirsiniz.

Ortam Değişkenleri ve Girişler

GitHub Actions iş akışları genellikle ortam değişkenleri (environment variables) ve girişler (inputs) kullanır. Act, bunları yerel olarak da destekler:

Ortam Değişkenleri:

İş akışınızda tanımlanan ortam değişkenleri Act tarafından otomatik olarak algılanır. Ayrıca, Act komutunu çalıştırırken de ortam değişkenleri tanımlayabilirsiniz:

act -e .env --secret MY_SECRET=myvalue

Veya bir .env dosyası oluşturarak:

# .env dosyası
MY_VARIABLE=MerhabaAct
ANOTHER_VAR=TestDeğeri

# .github/workflows/env_test.yml
name: Ortam Değişkeni Testi

on: [push]

jobs:
  env_job:
    runs-on: ubuntu-latest
    steps:
      - name: Ortam Değişkenini Yazdır
        run: echo "MY_VARIABLE değeri: $MY_VARIABLE"

act -e .env komutu ile çalıştırın.

Girişler (Inputs):

Eğer iş akışınız workflow_dispatch ile tetikleniyorsa ve girişler bekliyorsa, bunları Act ile sağlayabilirsiniz:

# .github/workflows/input_test.yml
name: Giriş Testi

on:
  workflow_dispatch:
    inputs:
      name:
        description: 'Adınız'
        required: true
        default: 'Dünya'

jobs:
  greet:
    runs-on: ubuntu-latest
    steps:
      - name: Selamlama
        run: echo "Merhaba, ${{ github.event.inputs.name }}!"

act workflow_dispatch -i name=ActKullanıcısı

Gelişmiş Act Kullanımı ve İpuçları

Belirli İşleri Çalıştırma

Bazen tüm iş akışını değil, sadece belirli bir işi (job) çalıştırmak isteyebilirsiniz. Act bunu -j veya --job bayrağı ile sağlar:

act -j build # Sadece 'build' isimli işi çalıştırır

Matrix Stratejileri ile Çalışma

GitHub Actions'ın matrix stratejileri, birden fazla konfigürasyonda işleri çalıştırmak için kullanılır (örneğin, farklı Node.js versiyonları veya işletim sistemleri). Act, matrix stratejilerini yerel olarak da destekler. Act, her bir matrix kombinasyonu için ayrı bir Docker kapsayıcısı başlatır.

# .github/workflows/matrix_test.yml
name: Matrix Testi

on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [16.x, 18.x]
    steps:
      - uses: actions/checkout@v4
      - name: Node.js ${{ matrix.node-version }} Kurulumu
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
      - name: Node.js Versiyonunu Yazdır
        run: node -v

Bu iş akışını act ile çalıştırdığınızda, Act her iki Node.js versiyonu için de ayrı ayrı işleri çalıştıracaktır.

Secret Yönetimi

GitHub Actions iş akışları genellikle hassas bilgileri (API anahtarları, parolalar vb.) saklamak için secret'ları kullanır. Act, bu secret'ları yerel olarak yönetmek için birkaç yol sunar:

Komut Satırı Argümanı: Tek seferlik secret'lar için --secret veya -s bayrağını kullanın:
```
act --secret MY_API_KEY=my_super_secret_key
```
.secrets Dosyası: Birden fazla secret'ı yönetmek için projenizin kök dizininde .secrets adında bir dosya oluşturabilirsiniz. Her satıra SECRET_ADI=değer formatında yazın:
```
# .secrets dosyası
MY_API_KEY=my_super_secret_key
DB_PASSWORD=secure_password
```
Ardından act komutunu çalıştırdığınızda Act bu dosyayı otomatik olarak okuyacaktır. Bu dosyayı asla versiyon kontrolüne (git) eklemeyin!

Özel Runner'lar ve Docker İmajları

Varsayılan olarak Act, catthehacker/ubuntu:act-latest gibi hafif Docker imajlarını kullanır. Ancak, iş akışınız belirli araçlara veya daha spesifik bir ortama ihtiyaç duyuyorsa, Act'in kullanacağı imajı belirtebilirsiniz:

--container-architecture: Farklı işlemci mimarilerine sahip makineler için (örneğin Apple M1/M2 çipleri için arm64) doğru Docker imajını seçmek için kullanılır:
```
act --container-architecture arm64
```
--pull: Her zaman en güncel Docker imajını çekmek için kullanılır.
.actrc Dosyası: Act'in varsayılan davranışlarını yapılandırmak için projenizin kök dizininde .actrc adında bir dosya oluşturabilirsiniz. Örneğin, varsayılan imajı veya mimariyi belirtebilirsiniz:
```
# .actrc dosyası
-P ubuntu-latest=catthehacker/ubuntu:full-latest
--container-architecture arm64
```

Act'in Avantajları ve En İyi Uygulamalar

Hızlı Geri Bildirim Döngüsü

Act'in en büyük avantajı, iş akışlarınızı anında yerel olarak test edebilmenizdir. Bir değişiklik yaptığınızda, GitHub'a push yapıp uzak sunucuların çalışmasını beklemek yerine, saniyeler içinde Act ile test edebilir ve hataları hızla düzeltebilirsiniz. Bu, geliştirme sürecini önemli ölçüde hızlandırır.

Maliyet Tasarrufu

GitHub Actions, belirli bir kullanım limitinin üzerinde ücretlidir. Act kullanarak iş akışlarınızı yerel olarak test etmek, gereksiz uzak çalıştırmaları önler ve dolayısıyla GitHub Actions dakikalarınızdan tasarruf etmenizi sağlar. Bu, özellikle büyük ekipler ve sık CI/CD kullanan projeler için önemli bir maliyet avantajı sunar.

Çevrimdışı Geliştirme Yeteneği

İnternet bağlantınız olmasa bile Act ile iş akışlarınızı test edebilirsiniz (Docker imajları önceden çekilmişse). Bu, seyahat ederken veya bağlantı sorunları yaşarken bile üretken kalmanızı sağlar.

En İyi Uygulama İpuçları

Küçük ve Modüler İş Akışları: İş akışlarınızı küçük, odaklanmış işlere bölün. Bu, hem Act ile test etmeyi kolaylaştırır hem de genel olarak daha sürdürülebilir CI/CD süreçleri oluşturur.
.actrc Dosyasını Kullanın: Sık kullandığınız Act ayarlarını (örneğin varsayılan Docker imajı, mimari) .actrc dosyasına kaydederek komutları basitleştirin.
.secrets Dosyasını Dikkatli Kullanın: Hassas bilgileri yönetmek için .secrets dosyasını kullanırken, bu dosyanın asla versiyon kontrolüne eklenmediğinden emin olun (.gitignore'a ekleyin).
GitHub Actions Ortamını Taklit Edin: Mümkün olduğunca GitHub Actions ortamına yakın bir ortam kullanmaya çalışın. Gerekirse, Act'in kullanacağı Docker imajını GitHub'ın kullandığı imajlara daha yakın olanlarla değiştirin.
Act'i Geliştirme Akışınıza Entegre Edin: Act'i düzenli olarak kullanarak yerel test alışkanlığı edinin. Bu, hataları erken yakalamanıza ve daha temiz kod geliştirmenize yardımcı olacaktır.

Potansiyel Zorluklar ve Çözümler

Ortam Farklılıkları

Act, GitHub Actions ortamını mümkün olduğunca taklit etse de, yerel Docker ortamınız ile GitHub'ın barındırılan runner'ları arasında küçük farklılıklar olabilir. Örneğin, bazı araçlar yerel Docker imajınızda önceden yüklü olmayabilirken, GitHub runner'larında mevcuttur.
Çözüm: İş akışınızda kullanılan tüm bağımlılıkların ve araçların açıkça kurulduğundan emin olun. Gerekirse, .actrc dosyasında daha kapsamlı bir Docker imajı (örneğin catthehacker/ubuntu:full-latest) belirtin veya kendi özel Docker imajınızı oluşturun.

Docker ve Bağımlılık Sorunları

Act, Docker'a sıkı sıkıya bağlıdır. Docker'ın düzgün çalışmaması (örneğin, Docker Desktop'ın başlatılmaması, yeterli kaynak olmaması) Act'in de çalışmamasına neden olacaktır.
Çözüm: Act'i çalıştırmadan önce Docker'ın çalıştığından ve yeterli sistem kaynağına sahip olduğundan emin olun. Docker loglarını kontrol ederek olası sorunları tespit edebilirsiniz.

Act'in Sınırlamaları

Act, çoğu GitHub Actions özelliğini desteklese de, bazı özellikler tam olarak desteklenmeyebilir veya farklı davranabilir:

github.token: GitHub API'sine erişim sağlayan github.token yerel ortamda doğrudan çalışmayabilir. Act, bu tür durumlarda bir uyarı verebilir. GitHub API'si ile etkileşime giren adımları yerel olarak test etmek için genellikle manuel olarak bir Personal Access Token (PAT) sağlamanız gerekebilir.
Self-hosted Runner'lar: Act, GitHub'ın barındırdığı runner'ları taklit eder, ancak kendi kendine barındırılan (self-hosted) runner'ların tam olarak aynı ortamını sağlamaz.
Olay Tetikleyicileri: Act, push, pull_request, workflow_dispatch gibi yaygın olayları desteklerken, bazı daha karmaşık veya özel tetikleyiciler (örneğin, repository_dispatch'in tüm detayları) tam olarak simüle edilemeyebilir.

Çözüm: Act'in sınırlamalarını bilmek ve kritik son testleri her zaman uzak GitHub Actions ortamında da yapmak önemlidir. Act, hızlı geri bildirim için harika bir araçtır, ancak nihai doğrulama her zaman gerçek CI/CD ortamında yapılmalıdır.

Sonuç

Act, GitHub Actions ile çalışan her geliştiricinin araç kutusunda bulunması gereken güçlü bir yardımcıdır. İş akışlarınızı yerel olarak test etme yeteneği, geliştirme sürecinizi önemli ölçüde hızlandırır, hata ayıklamayı kolaylaştırır ve maliyetlerden tasarruf etmenizi sağlar. Yavaş geri bildirim döngülerine son vererek, daha hızlı yineleme yapabilir ve daha verimli bir şekilde çalışabilirsiniz. Act'i geliştirme akışınıza entegre ederek, hem bireysel verimliliğinizi hem de ekip olarak CI/CD süreçlerinizin kalitesini artırabilirsiniz. Unutmayın, Act bir simülasyon aracıdır ve nihai doğrulama her zaman gerçek GitHub Actions ortamında yapılmalıdır, ancak geliştirme ve hata ayıklama aşamasında size paha biçilmez bir avantaj sağlayacaktır.

SSS (Sık Sorulan Sorular)

Act tüm GitHub Actions özelliklerini destekler mi?

Act, GitHub Actions'ın çoğu temel özelliğini (işler, adımlar, eylemler, ortam değişkenleri, secret'lar, matrix stratejileri) destekler. Ancak, github.token ile GitHub API'si etkileşimleri veya bazı özel olay tetikleyicileri gibi belirli gelişmiş özelliklerde sınırlamaları olabilir. Genel olarak, çoğu iş akışı Act ile yerel olarak test edilebilir.

Act kullanmak için Docker bilmek şart mı?

Act'i kullanmak için Docker'ın temel çalışma prensiplerini bilmek faydalı olsa da, şart değildir. Act, Docker'ı arka planda otomatik olarak yönetir. Sadece Docker'ın sisteminizde kurulu ve çalışır durumda olduğundan emin olmanız yeterlidir. Daha gelişmiş senaryolarda (özel imajlar, sorun giderme) Docker bilgisi işinize yarayacaktır.

Act ile secret'larımı nasıl güvenli bir şekilde yönetirim?

Secret'ları yönetmek için --secret komut satırı bayrağını veya .secrets dosyasını kullanabilirsiniz. .secrets dosyasını kullanırken, bu dosyanın hassas bilgiler içerdiğini ve asla git deponuza eklenmemesi gerektiğini (.gitignore'a ekleyin) unutmayın. Bu yöntemler, secret'larınızı yerel ortamda güvenli bir şekilde kullanmanızı sağlar.

Act, CI/CD sürecimi tamamen yerel ortama taşır mı?

Hayır, Act CI/CD sürecinizi tamamen yerel ortama taşımaz. Act, iş akışlarınızı geliştirme ve hata ayıklama aşamasında hızlandırmak için bir yerel test aracıdır. Nihai entegrasyon ve dağıtım süreçleri hala GitHub Actions'ın uzak sunucularında veya kendi kendine barındırılan runner'larınızda gerçekleşmelidir. Act, bu süreçlerin daha sorunsuz ve hatasız ilerlemesine yardımcı olur.

Act ile GitHub Actions İş Akışlarınızı Yerelde Test Ederek Hızlandırın