GitHub Actions bez stałych kluczy AWS — OIDC wymaga dwóch warunków

Aby wdrażać z GitHub Actions do AWS bez stałych kluczy, utwórz dostawcę OIDC i rolę IAM, a w polityce zaufania roli ustaw dwa warunki opisane przez GitHub: aud dla odbiorcy tokenu oraz sub dla uprawnionego uruchomienia. Przy użyciu oficjalnej akcji AWS wartość aud to sts.amazonaws.com; sub musi odpowiadać właściwemu repozytorium i gałęzi albo środowisku GitHub.

Dostawca pozwala AWS rozpoznać wystawcę tokenu, lecz dopiero polityka zaufania określa, które uruchomienie może przyjąć rolę. Workflow potrzebuje też uprawnienia do pobrania tokenu i ARN roli. Poniższy przykład zakłada przesłanie pliku index.html do Amazon S3 po zmianie w gałęzi main.

Dodaj dostawcę OIDC i rolę w IAM

W konsoli AWS otwórz IAM i dodaj dostawcę tożsamości typu OpenID Connect. Jako adres dostawcy wpisz https://token.actions.githubusercontent.com, a jako odbiorcę sts.amazonaws.com. Wartość odbiorcy musi odpowiadać warunkowi aud w polityce zaufania. Nie wpisuj tu adresu repozytorium: repozytorium zostanie ograniczone w warunku sub roli.

Następnie utwórz rolę z typem zaufanej jednostki Web identity i wybierz dodanego dostawcę. Instrukcja AWS dla roli federacyjnej przewiduje wskazanie organizacji GitHub, a opcjonalnie repozytorium i gałęzi; pominięte pola repozytorium lub gałęzi otrzymują wzorzec obejmujący wszystkie wartości. Dlatego przed zapisaniem roli sprawdź gotową politykę zaufania i wpisz dokładny sub odpowiadający wdrożeniu.

Polityka zaufania określa, kto może przyjąć rolę. Osobna polityka uprawnień określa, co wolno zrobić po jej przyjęciu. Dla warunkowego przykładu z jednym plikiem nadaj roli s3:PutObject tylko dla obiektu arn:aws:s3:::BUCKET/index.html. Pozostałe uprawnienia dodawaj dopiero wtedy, gdy wymaga ich rzeczywiste polecenie wdrożeniowe; samo poprawne uwierzytelnienie przez OIDC nie nadaje dostępu do zasobnika.

Ogranicz politykę zaufania przez aud i sub

Ten przykład przyjmuje token z trwałymi identyfikatorami właściciela i repozytorium w sub. Zastąp ACCOUNT_ID identyfikatorem konta AWS, ORG i REPO nazwami z GitHub, a OWNER_ID i REPO_ID odpowiadającymi im identyfikatorami. Gałąź main musi być tą, z której wykonywane jest wdrożenie. Wartości są przykładowe; przed użyciem polityki dopasuj cały ciąg sub do formatu tokenu własnego repozytorium.

Polityka zaufania roli (JSON): {"Version":"2012-10-17","Statement":[{"Effect":"Allow","Principal":{"Federated":"arn:aws:iam::ACCOUNT_ID:oidc-provider/token.actions.githubusercontent.com"},"Action":"sts:AssumeRoleWithWebIdentity","Condition":{"StringEquals":{"token.actions.githubusercontent.com:aud":"sts.amazonaws.com","token.actions.githubusercontent.com:sub":"repo:ORG@OWNER_ID/REPO@REPO_ID:ref:refs/heads/main"}}}]}

StringEquals wymaga dokładnego dopasowania obu wartości. Warunek aud wiąże token z odbiorcą przewidzianym dla AWS STS, a sub zawęża przyjęcie roli do wskazanego repozytorium i gałęzi. Filtr gałęzi w samym workflow ogranicza jego zwykłe uruchomienia, lecz nie zastępuje granicy zapisanej w IAM. Z kolei dopasowanie aud i sub daje możliwość przyjęcia roli, a zakres działań po uwierzytelnieniu nadal wynika z jej polityki uprawnień.

Dopasuj sub do wieku repozytorium i środowiska

Format sub trzeba ustalić przed wklejeniem polityki. Dokumentacja akcji AWS podaje, że repozytoria utworzone w GitHub.com od 15 lipca 2026 roku, starsze repozytoria po włączeniu tej opcji oraz starsze repozytoria przemianowane od tej daty używają w sub trwałych identyfikatorów; wcześniejszy format opiera się na samych nazwach. Dla starszego tokenu warunek przyjmie postać repo:ORG/REPO:ref:refs/heads/main. Jeśli token zawiera identyfikatory, warunek oparty tylko na nazwach nie zostanie spełniony.

Job korzystający ze środowiska GitHub ma w sub człon environment:NAZWA zamiast ref:refs/heads/main. W takim wdrożeniu ustaw warunek dla konkretnego środowiska, uwzględniając format identyfikatorów używany przez repozytorium. Następnie w ochronie środowiska określ, które gałęzie mogą do niego wdrażać. To ważne, ponieważ warunek wskazujący środowisko sam nie zawiera nazwy gałęzi. Rozszerzanie sub do wzorca obejmującego wszystkie uruchomienia usunęłoby błąd dopasowania kosztem szerszego dostępu.

Dodaj workflow bez sekretów AWS

Zapisz poniższą zawartość w .github/workflows/deploy.yml. To zwarty zapis JSON w składni YAML; zamień ACCOUNT_ID, ROLE_NAME i BUCKET na własne wartości. Repozytorium musi zawierać index.html, a rola musi mieć prawo zapisu do wskazanego obiektu. Przykład używa aws-actions/[email protected] do pobrania krótkotrwałych poświadczeń i akcji checkout do udostępnienia pliku w jobie.

Plik workflow: {"name":"Deploy S3","on":{"push":{"branches":["main"]}},"permissions":{"id-token":"write","contents":"read"},"jobs":{"deploy":{"runs-on":"ubuntu-latest","steps":[{"uses":"actions/checkout@v6"},{"uses":"aws-actions/[email protected]","with":{"role-to-assume":"arn:aws:iam::ACCOUNT_ID:role/ROLE_NAME","aws-region":"eu-central-1"}},{"run":"aws s3 cp ./index.html s3://BUCKET/index.html"}]}}}

Uprawnienie id-token: write pozwala jobowi poprosić GitHub o token OIDC; samo nie daje prawa zapisu w AWS. Uprawnienie contents: read służy tu akcji checkout. Akcja konfigurująca poświadczenia przedstawia token usłudze AWS STS i udostępnia uzyskane poświadczenia kolejnemu krokowi. Workflow wskazuje ARN roli zamiast identyfikatora klucza dostępu i tajnego klucza AWS. Jeśli zmienisz gałąź w zdarzeniu push, zaktualizuj również warunek sub w IAM.

Sprawdź granice dostępu przed wdrożeniem

Przed pierwszym uruchomieniem porównaj wartości po obu stronach połączenia:

• Odbiorca dodany do dostawcy OIDC i warunek aud roli wskazują sts.amazonaws.com.
• Warunek sub odpowiada dokładnemu formatowi tokenu, repozytorium i gałęzi albo chronionemu środowisku.
• Job ma id-token: write, a role-to-assume wskazuje właściwą rolę i konto AWS.
• Polityka uprawnień roli obejmuje tylko operacje oraz zasoby potrzebne do wdrożenia.

W pierwszym uruchomieniu możesz użyć polecenia aws sts get-caller-identity, aby zobaczyć, jaką tożsamość AWS uzyskał job. Pomyślne przyjęcie roli potwierdzi połączenie OIDC, ale nie zastąpi sprawdzenia prawa do zapisu docelowego obiektu. Po próbie przesłania pliku warto też sprawdzić granicę zaufania: uruchomienie z innej gałęzi lub repozytorium nie powinno spełnić warunku sub tej roli.

Przeczytaj także:

• GitHub wykrywa sekrety Lovable i Supabase — klucz może zniknąć szybciej
• GitHub Actions czy GitLab CI? Darmowe minuty nie pokazują kosztu zespołu
• AI Act wymaga kompetencji AI, ale nie narzuca jednego szkolenia