Uruchamianie GitHub Actions lokalnie za pomocą act

[Mikolaj1995]

Hej!

Przygotowałem krótkie szkolenie o narzędziu act, które pozwala uruchamiać GitHub Actions lokalnie — bez potrzeby czekania na wykonanie workflowów w chmurze. Robiłem je dla siebie, ale wyszło całkiem ciekawe i pomyślałem, że może komuś się przyda. Staram się wychodzić do ludzi, stąd też ta publikacja. 

To jest tłumaczenie, w dużej mierze wykonane maszynowo, a oryginalna anglojęzyczna wersja (mojego autorstwa) znajduje się tutaj:  na GitHubie.

Act to świetny sposób na szybsze testowanie, debugowanie i naukę Continuous Integration bez ograniczeń środowiska GitHub.

---

Część 1: Wprowadzenie i przygotowanie środowiska

1.1 Wymaganie wstępne – Docker Desktop

Narzędzie act działa na podstawie kontenerów Docker.
Jeśli nie masz jeszcze zainstalowanego Dockera, pobierz go stąd:

 Docker dla Windows

Po instalacji uruchom aplikację Docker Desktop – act nie zadziała, jeśli Docker nie będzie aktywny.

---

1.2 Instalacja act przez Winget

Otwórz PowerShell lub Wiersz polecenia i uruchom komendę:

winget install nektos.act
# Instaluje narzędzie act z oficjalnego repozytorium nektos

---

1.3 Przygotowanie struktury projektu

W katalogu głównym swojego projektu utwórz folder dla workflow'ów GitHub Actions:

mkdir -p .github/workflows
# Tworzy katalog .github/workflows, gdzie będą pliki YAML workflowów

---

1.4 Pierwsze uruchomienie act

W terminalu (będąc w katalogu projektu) wpisz:

act
# Uruchamia act po raz pierwszy i pobiera domyślny obraz Dockera

Podczas pierwszego uruchomienia pojawi się pytanie o wybór obrazu Dockera. Wybierz opcję Medium image – zawiera najczęściej używane narzędzia i jest dobrym kompromisem między funkcjonalnością a rozmiarem.

---

Część 2: Tworzenie i uruchamianie workflow'a

2.1 Tworzenie pliku workflow

Utwórz plik .github/workflows/ci.yml z następującą zawartością:

name: Podstawowy CI

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Pobierz kod
        uses: actions/checkout@v3

      - name: Powitaj użytkownika
        run: echo "Hello from act on Windows!"

  pull_request_check:
    runs-on: ubuntu-latest
    if: github.event_name == 'pull_request'
    steps:
      - name: Pobierz kod
        uses: actions/checkout@v3
      - name: Sprawdzenie PR
        run: echo "Running checks for Pull Request"

  secret_check:
    runs-on: ubuntu-latest
    steps:
      - name: Pobierz kod
        uses: actions/checkout@v3
      - name: Weryfikacja sekretu
        run: |
          echo "Klucz API (pierwsze 10 znaków): ${{ secrets.MY_API_KEY }}"
          echo "Inny sekret: ${{ secrets.ANOTHER_SECRET }}"

  env_variable_check:
    runs-on: ubuntu-latest
    steps:
      - name: Pobierz kod
        uses: actions/checkout@v3
      - name: Weryfikacja zmiennych środowiskowych
        run: |
          echo "Zmienna z CLI: ${{ env.MY_CUSTOM_VAR }}"
          echo "Zmienna z pliku: ${{ env.ANOTHER_CUSTOM_VAR }}"

---

2.2 Uruchomienie workflow'a (domyślny event push)

act
# Uruchamia workflow dla zdarzenia push (domyślnie)

Narzędzie act wykryje plik .yml i uruchomi odpowiednie job'y. Zobaczysz wynik podobny do tego, co normalnie pojawiłoby się w logach GitHub Actions.

---

2.3 Uruchamianie dla konkretnego zdarzenia (pull_request)

Aby przetestować job'y przypisane do zdarzenia pull_request, użyj:

act pull_request
# Symuluje event pull_request

W tym trybie uruchomione zostaną job'y build, pull_request_check i secret_check.

---

2.4 Lista dostępnych workflow'ów i job'ów

Aby sprawdzić, jakie workflow'y i job'y są zdefiniowane:

act -l
# Wyświetla listę wszystkich workflowów i jobów

---

2.5 Uruchamianie pojedynczego job'a

Możesz też uruchomić tylko jeden konkretny job:

act -j pull_request_check pull_request
# Uruchamia tylko pull_request_check w kontekście eventu pull_request

Jeśli spróbujesz uruchomić ten sam job z eventem push, zostanie pominięty — ponieważ w YAML jest warunek if: github.event_name == 'pull_request'.

---

Część 3: Praca z sekretami

Wiele workflow'ów korzysta z sekretów, np. kluczy API. Nigdy nie zapisuj ich bezpośrednio w repozytorium! act pozwala wczytywać je lokalnie i bezpiecznie.

3.1 Sekrety z pliku .secrets i z CLI

Utwórz plik .secrets w katalogu projektu:

# .secrets
ANOTHER_SECRET=wartosc_z_pliku

Dodaj ten plik do .gitignore, aby nie trafił do repozytorium.

Teraz możesz uruchomić job z dwoma sekretami — jeden z pliku, drugi z linii poleceń:

act -j secret_check --secret MY_API_KEY=sekret_z_cli push
# Wczytuje sekrety z .secrets oraz z parametru --secret

Wynik:

My API Key (first 10 chars): ***
Another Secret (masked): ***

act automatycznie maskuje wartości sekretów w konsoli – podobnie jak GitHub Actions.

---

Część 4: Zmienne środowiskowe

Podobnie jak sekrety, zmienne środowiskowe (env) można przekazywać przez CLI lub plik .env.

4.1 Przykład

Utwórz plik .env:

# .env
ANOTHER_CUSTOM_VAR=wartosc_z_pliku_env

Dodaj do .gitignore, a następnie uruchom job:

act -j env_variable_check push --env MY_CUSTOM_VAR=wartosc_z_cli --env-file .env
# Łączy zmienne środowiskowe z CLI i pliku

Wynik:

My Custom Variable: wartosc_z_cli
Another Custom Variable: wartosc_z_pliku_env

---

Podsumowanie

Gratulacje! Masz już działające środowisko do lokalnego testowania GitHub Actions.

Podsumowanie kluczowych komend:

• act – uruchamia workflow dla eventu push
• act pull_request – symuluje event pull_request
• act -l – pokazuje listę jobów
• act -j <job> – uruchamia konkretny job
• --secret / --env – dodaje sekrety lub zmienne środowiskowe

---

Dodatkowo: wtyczka do VS Code

Dla wygody możesz zainstalować rozszerzenie, które integruje act z VS Code:

code --install-extension sanjulaganepola.github-local-actions

Dzięki temu uruchomisz workflow'y bezpośrednio z edytora.

Zalety rozszerzenia:

• graficzny interfejs do uruchamiania workflow'ów,
• konfiguracja obrazów i ścieżek w ustawieniach VS Code,
• szybsze debugowanie.

Dokumentacja wtyczki: https://sanjulaganepola.github.io/github-local-actions-docs/

---

Jeśli spróbujesz tego szkolenia, daj znać poniżej — chętnie poznam Twoje wrażenia!