github-actions

## Purpose Automate build, test, and deployment workflows directly from GitHub repositories. ## When to Use - Setting up CI/CD pipelines - Automating tests on push/PR - Deploying to production - Running scheduled jobs - Automating code quality checks ## Workflow Basics ### Workflow File Location ``` .github/ └── workflows/ ├── ci.yml ├── deploy.yml └── scheduled.yml ``` ### Basic Workflow Structure ```yaml name: Workflow Name on: [push, pull_request] jobs: job-name: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - run: echo "Hello World" ``` ## Common Triggers ### Push and Pull Request ```yaml on: push: branches: [main, develop] pull_request: branches: [main] ``` ### Manual Trigger ```yaml on: workflow_dispatch: inputs: environment: description: 'Environment to deploy' required: true default: 'staging' ``` ### Scheduled (Cron) ```yaml on: schedule: - cron: '0 0 * * *' # Daily at midnight UTC ``` ### Path Filters ```yaml on: push: paths: - 'src/**' - 'package.json' ``` ## Common Jobs ### Install and Test (Node.js) ```yaml name: CI on: [push, pull_request] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: '20' cache: 'npm' - run: npm ci - run: npm test - run: npm run build ``` ### Install and Test (Python) ```yaml name: CI on: [push, pull_request] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-python@v5 with: python-version: '3.11' cache: 'pip' - run: pip install -r requirements.txt - run: pytest ``` ### Lint and Format ```yaml name: Lint on: [push, pull_request] jobs: lint: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: '20' cache: 'npm' - run: npm ci - run: npm run lint - run: npm run format:check ``` ### Build Docker Image ```yaml name: Docker Build on: [push] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: docker/setup-buildx-action@v3 - uses: docker/login-action@v3 with: registry: ghcr.io username: ${{ github.actor }} password: ${{ secrets.GITHUB_TOKEN }} - uses: docker/build-push-action@v5 with: context: . push: true tags: ghcr.io/${{ github.repository }}:latest ``` ### Deploy to Vercel ```yaml name: Deploy on: push: branches: [main] jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: amondnet/vercel-action@v25 with: vercel-token: ${{ secrets.VERCEL_TOKEN }} vercel-org-id: ${{ secrets.VERCEL_ORG_ID }} vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }} vercel-args: '--prod' ``` ### Deploy to AWS ```yaml name: Deploy to AWS on: push: branches: [main] jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: aws-actions/configure-aws-credentials@v4 with: aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }} aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }} aws-region: us-east-1 - run: npm ci - run: npm run build - run: aws s3 sync ./dist s3://my-bucket ``` ## Multi-Stage Workflows ### Test Then Deploy ```yaml name: CI/CD on: push: branches: [main] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: '20' cache: 'npm' - run: npm ci - run: npm test deploy: needs: test runs-on: ubuntu-latest if: github.ref == 'refs/heads/main' steps: - uses: actions/checkout@v4 - run: npm ci - run: npm run build - run: echo "Deploying..." ``` ### Matrix Testing ```yaml name: Test Matrix on: [push, pull_request] jobs: test: runs-on: ubuntu-latest strategy: matrix: node-version: [18, 20, 21] os: [ubuntu-latest, windows-latest, macos-latest] steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: ${{ matrix.node-version }} cache: 'npm' - run: npm ci - run: npm test ``` ## Caching ### Cache npm Dependencies ```yaml - uses: actions/setup-node@v4 with: node-version: '20' cache: 'npm' ``` ### Custom Cache ```yaml - uses: actions/cache@v4 with: path: ~/.cache/pip key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }} restore-keys: | ${{ runner.os }}-pip- ``` ### Cache Build Artifacts ```yaml - uses: actions/cache@v4 with: path: | ~/.npm dist key: ${{ runner.os }}-build-${{ github.sha }} restore-keys: | ${{ runner.os }}-build- ``` ## Secrets Management ### Using Secrets ```yaml - run: | echo "API_KEY=${{ secrets.API_KEY }}" >> .env npm run build ``` ### Required Secrets ```yaml jobs: deploy: runs-on: ubuntu-latest steps: - name: Check secrets run: | if [ -z "${{ secrets.API_KEY }}" ]; then echo "API_KEY secret is required" exit 1 fi ``` ## Environment Variables ### Setting Environment Variables ```yaml jobs: build: runs-on: ubuntu-latest env: NODE_ENV: production API_URL: https://api.example.com steps: - run: echo $NODE_ENV ``` ### From Job Output ```yaml jobs: build: runs-on: ubuntu-latest outputs: version: ${{ steps.version.outputs.version }} steps: - id: version run: echo "version=1.0.0" >> $GITHUB_OUTPUT deploy: needs: build runs-on: ubuntu-latest steps: - run: echo "Version ${{ needs.build.outputs.version }}" ``` ## Artifacts ### Upload Build Output ```yaml - uses: actions/upload-artifact@v4 with: name: build-output path: dist/ ``` ### Download Artifact ```yaml - uses: actions/download-artifact@v4 with: name: build-output path: ./dist ``` ## Common Actions ### Checkout ```yaml - uses: actions/checkout@v4 with: fetch-depth: 0 # Full history ``` ### Setup Node.js ```yaml - uses: actions/setup-node@v4 with: node-version: '20' cache: 'npm' ``` ### Setup Python ```yaml - uses: actions/setup-python@v5 with: python-version: '3.11' cache: 'pip' ``` ### Setup Docker ```yaml - uses: docker/setup-buildx-action@v3 ``` ### Setup AWS Credentials ```yaml - uses: aws-actions/configure-aws-credentials@v4 with: aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }} aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }} aws-region: us-east-1 ``` ## Conditional Execution ### Run on Specific Branch ```yaml jobs: deploy: if: github.ref == 'refs/heads/main' runs-on: ubuntu-latest steps: - run: echo "Deploying main branch" ``` ### Run on Tag ```yaml jobs: release: if: startsWith(github.ref, 'refs/tags/') runs-on: ubuntu-latest steps: - run: echo "Creating release" ``` ### Skip on Draft PR ```yaml jobs: test: if: github.event.pull_request.draft == false runs-on: ubuntu-latest steps: - run: echo "Testing PR" ``` ## Status Badges ### Workflow Status Badge ```markdown  ``` ### Custom Badge ```markdown  ``` ## Best Practices ### Workflow Design - Keep workflows simple and focused - Use matrix for testing multiple configurations - Cache dependencies to speed up builds - Use secrets for sensitive data - Set appropriate timeouts - Use specific action versions (not @latest) ### Performance - Use caching for dependencies - Parallelize independent jobs - Use self-hosted runners for large projects - Minimize artifact sizes - Use conditional execution ### Security - Pin action versions - Use OIDC for cloud authentication - Limit permissions with permissions field - Review third-party actions - Keep secrets encrypted - Use environment protection rules ## Common Patterns ### Monorepo ```yaml name: CI on: [push, pull_request] jobs: test: runs-on: ubuntu-latest strategy: matrix: package: [frontend, backend, shared] steps: - uses: actions/checkout@v4 - working-directory: ./packages/${{ matrix.package }} run: npm ci && npm test ``` ### Release Workflow ```yaml name: Release on: push: tags: - 'v*' jobs: release: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: '20' cache: 'npm' - run: npm ci - run: npm run build - uses: softprops/action-gh-release@v1 with: files: dist/* ``` ### Dependency Update ```yaml name: Dependency Update on: schedule: - cron: '0 0 * * 0' # Weekly jobs: update: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: '20' - run: npx npm-check-updates -u - run: npm install - run: npm test - uses: peter-evans/create-pull-request@v6 with: title: 'Update dependencies' body: 'Automated dependency update' ``` ## Troubleshooting ### View Workflow Logs - Go to Actions tab in repository - Click on workflow run - Expand job to see logs ### Debug Failed Workflows ```yaml - name: Debug run: |