diff --git a/wiki/docs/en/onboarding/hands-on-labs/learn-github-actions/CICD.md b/wiki/docs/en/onboarding/hands-on-labs/learn-github-actions/CICD.md new file mode 100644 index 0000000..a2559c1 --- /dev/null +++ b/wiki/docs/en/onboarding/hands-on-labs/learn-github-actions/CICD.md @@ -0,0 +1,380 @@ +# Optimizing CI/CD Workflows with GitHub Actions + +Optimizing CI/CD workflows is essential to improve efficiency, reduce execution times, and ensure pipeline stability. This detailed guide explores various techniques to accelerate your workflows, optimize CI/CD pipelines, manage dependency versions, and troubleshoot issues using GitHub Actions' integrated debugging tools. + +--- + +## 1. Speeding Up Workflows: Caching Dependencies and Reusing Workflows + +### 1.1. Caching Dependencies + +Caching dependencies is an efficient way to reduce the time spent installing libraries and modules in your CI/CD workflows. GitHub Actions offers a built-in **`cache`** action, which allows storing files like build dependencies or intermediate results for reuse in subsequent runs. + +#### Example: Caching Node.js Dependencies + +```yaml +name: CI with Cache + +on: [push] + +jobs: + build: + runs-on: ubuntu-latest + + steps: + # Step 1: Check out source code + - name: Checkout repository + uses: actions/checkout@v2 + + # Step 2: Cache npm dependencies + - name: Cache Node.js modules + uses: actions/cache@v2 + with: + path: node_modules + key: ${{ runner.os }}-node-${{ hashFiles('package-lock.json') }} + restore-keys: | + ${{ runner.os }}-node- + + # Step 3: Install dependencies + - name: Install dependencies + run: npm install + + # Step 4: Build project + - name: Build project + run: npm run build +``` + +#### Explanation of Steps: +- **`actions/cache@v2`**: This action caches Node.js modules located in the `node_modules` directory. The cache is based on the checksum (hash) of the `package-lock.json` file. If no changes are detected in this file, the cache is restored, reducing dependency installation time. +- **`restore-keys`**: This option allows partial cache restoration if the exact key is not found. + +### 1.2. Reusing Workflows + +Reusing workflows enables centralization of common pipeline parts into a reusable file, simplifying the management of complex workflows. You can call one workflow from another to avoid code duplication. + +In our projects, we use a dedicated repository for reusable workflows. You can check out [**cedille-workflows**](https://github.com/ClubCedille/cedille-workflows), which contains examples of workflows ready for reuse in different projects. This repository centralizes common workflow definitions, such as Docker image building, deployments, and dependency management. + +Here is the updated section with an example illustrating the use of variables in a reusable workflow: + +```markdown +#### Example: Calling a Reusable Workflow + +In this case, we have one workflow that performs tests and another that handles deployments. These workflows are reused from a central file. + +```yaml +# .github/workflows/reusable-tests.yml +name: Reusable Test Workflow + +on: workflow_call + +jobs: + tests: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v2 + + - name: Install dependencies + run: npm install + + - name: Run tests + run: npm test +``` + +```yaml +# .github/workflows/deploy.yml +name: Deployment Pipeline + +on: + push: + branches: + - main + +jobs: + call-tests: + uses: ./.github/workflows/reusable-tests.yml + + deploy: + needs: call-tests + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v2 + + - name: Deploy to production + run: ./deploy.sh +``` + +#### Example: Reusable Workflow with Variables + +You can also define **input variables** in a reusable workflow for greater flexibility. Here is an example that builds and pushes a Docker image to the GitHub Container Registry (GHCR) using input variables: + +```yaml +# .github/workflows/build-push-ghcr.yml +name: Reusable workflow to build and push docker container to GitHub Container Registry + +on: + workflow_call: + inputs: + container-name: + required: true + type: string + context: + required: false + type: string + default: '.' + file: + required: false + type: string + default: 'Dockerfile' + +env: + REGISTRY: ghcr.io/clubcedille + +jobs: + build-and-push: + runs-on: ubuntu-latest + steps: + - name: Check Out Repo + uses: actions/checkout@v4 + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + + - name: Log in to the Container Registry + uses: docker/login-action@v1 + with: + registry: ${{ env.REGISTRY }} + username: ${{ github.actor }} + password: ${{ secrets.GITHUB_TOKEN }} + + - name: Build and push Docker image + uses: docker/build-push-action@v2 + with: + context: ${{ inputs.context }} + file: ${{ inputs.file }} + push: true + tags: ${{ env.REGISTRY }}/${{ inputs.container-name }}:latest +``` + +#### Example of Using the Reusable Workflow: + +This workflow can now be called from another workflow, while passing customized variables to adapt its behavior: + +```yaml +# .github/workflows/deploy-with-docker.yml +name: Deployment with Docker + +on: + push: + branches: + - main + +jobs: + deploy: + uses: ./.github/workflows/build-push-ghcr.yml + with: + container-name: my-app + context: ./my-app-directory +``` + +#### Explanation: +- **`workflow_call`**: Enables reusing the workflow by calling workflows defined elsewhere. Input variables allow customization of the reusable workflow’s behavior. +- **Input Variables (`inputs`)**: Variables like `container-name`, `context`, and `file` set specific values for each workflow call. This enables building and pushing different Docker images without altering the base workflow. +- **Reducing Duplication**: Using variables in reusable workflows centralizes common tasks while adapting their execution to specific needs, simplifying CI/CD pipeline maintenance. + +--- + +## 2. Pipeline Optimization Strategies (Job Matrix, Dependent Jobs) + +### 2.1. Job Matrix + +The **job matrix** is a powerful GitHub Actions feature that allows multiple configuration combinations to run in parallel. This is particularly useful for testing your application on various language versions, environments, or operating systems. + +#### Example: Job Matrix with Node.js + +```yaml +name: Node.js CI + +on: + push: + branches: + - main + +jobs: + test: + runs-on: ubuntu-latest + + strategy: + matrix: + node-version: [12, 14, 16] + os: [ubuntu-latest, windows-latest, macos-latest] + + steps: + - name: Checkout repository + uses: actions/checkout@v2 + + - name: Set up Node.js ${{ matrix.node-version }} + uses: actions/setup-node@v2 + with: + node-version: ${{ matrix.node-version }} + + - name: Install dependencies + run: npm install + + - name: Run tests + run: npm test +``` + +#### Explanation: +- **`matrix.node-version`** and **`matrix.os`**: These two matrices enable testing on different Node.js versions (`12`, `14`, `16`) and across various operating systems (`ubuntu`, `windows`, `macos`). +- **Parallel Execution**: GitHub Actions executes all matrix combinations in parallel, significantly reducing the total execution time for multi-environment testing. + +### 2.2. Dependent Jobs + +Dependent jobs allow defining dependencies between jobs, meaning a job can wait for another to complete successfully before starting. + +#### Example: Dependent Jobs + +```yaml +name: Build and Deploy + +on: + push: + branches: + - main + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v2 + + - name: Build application + run: npm run build + + test: + runs-on: ubuntu-latest + needs: build + steps: + - name: Run tests + run: npm test + + deploy: + runs-on: ubuntu-latest + needs: test + steps: + - name: Deploy to production + run: ./deploy.sh +``` + +#### Explanation: +- **`needs`**: The `needs` instruction defines a dependency between jobs. In this example, the `test` job only starts after the `build` job succeeds, and the `deploy` job waits for `test` to complete. + +--- + +## 3. Managing Dependency and Action Versions + +Properly managing dependency and action versions in your workflows ensures stability and prevents errors due to unexpected changes in the libraries or actions used. + +### 3.1. Managing Action Versions + +When using an action in a GitHub Actions workflow, it is essential to specify a specific version to ensure your workflow remains stable, even if the action is updated in the future. + +#### Example: Using a Specific Action Version + +```yaml +jobs: + build: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v2.3.4 # Use a specific version +``` + +### 3.2. Managing Dependency Versions + +Locking the versions of dependencies used in your project (for example, in `package-lock.json` + + or `requirements.txt`) is also recommended. This ensures that each workflow execution uses the same library versions, minimizing errors from untested updates. + +#### Example: Locked Dependencies in `package-lock.json` + +```yaml +jobs: + build: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v2 + + - name: Install dependencies + run: npm ci # Install dependencies with locked versions in package-lock.json +``` + +--- + +## 4. Debugging GitHub Actions Workflows + +When a workflow fails or behaves unexpectedly, having the right tools to diagnose and resolve the issue quickly is essential. + +### 4.1. Enabling Detailed Logs + +GitHub Actions allows enabling detailed logs to help diagnose errors. This can be useful if a job fails without providing enough information in the standard logs. + +#### Enable Detailed Logs + +1. Go to the workflow run page. +2. Click on the failed job to view the logs. +3. Use the **Rerun jobs with debug logging** option to rerun the job with more detailed logs. + +### 4.2. Using `ACTIONS_STEP_DEBUG` + +You can also enable debug mode by setting a special environment variable `ACTIONS_STEP_DEBUG`. + +#### Example: Enable Debug Mode in the Workflow + +```yaml +jobs: + debug-job: + runs-on: ubuntu-latest + + steps: + - name: Enable step debug logging + run: echo "ACTIONS_STEP_DEBUG=true" >> $GITHUB_ENV + + - name: Checkout repository + uses: actions/checkout@v2 +``` + +### 4.3. Adding Custom Debugging Messages + +In certain situations, you may need to add debugging messages to your workflows to inspect values or verify checkpoints. You can use `core.debug` for this. + +#### Example: Adding Debugging Messages + +```yaml +jobs: + build: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v2 + + - name: Debug message + run: | + echo "DEBUG: Current directory is $(pwd)" + echo "DEBUG: Branch is ${{ github.ref }}" +``` + +--- + +## Conclusion + +Optimizing your CI/CD workflows in GitHub Actions is crucial for fast, stable, and efficient executions. Caching dependencies, reusing workflows, using job matrices, and managing dependencies are all essential strategies for improving performance. Additionally, with built-in debugging tools, you can quickly identify and fix issues in your workflows. These best practices enable you to maintain robust and high-performance pipelines while minimizing errors and interruptions. \ No newline at end of file diff --git a/wiki/docs/en/onboarding/hands-on-labs/learn-github-actions/deployment.md b/wiki/docs/en/onboarding/hands-on-labs/learn-github-actions/deployment.md new file mode 100644 index 0000000..f1e532c --- /dev/null +++ b/wiki/docs/en/onboarding/hands-on-labs/learn-github-actions/deployment.md @@ -0,0 +1,373 @@ +# Continuous Deployment with GitHub Actions + +Continuous Deployment (CD) involves automating the deployment of new versions of an application directly into production environments after passing testing and validation stages. GitHub Actions allows setting up CD pipelines for cloud platforms like AWS, Azure, or Google Cloud Platform (GCP). + +--- + +## 1. Deploying an Application on Cloud Platforms (AWS, Azure, GCP) + +GitHub Actions can be used to automate application deployment on popular cloud services such as **AWS**, **Microsoft Azure**, and **Google Cloud Platform (GCP)**. Each cloud provider has its own tools and services for managing application deployment. + +### 1.1 Deployment on AWS + +AWS offers several services for hosting applications, including **Elastic Beanstalk**, **ECS (Elastic Container Service)**, and **S3**. With GitHub Actions, you can configure workflows to automatically deploy your applications to these services. + +#### Example Workflow for Deploying on AWS Elastic Beanstalk + +Elastic Beanstalk simplifies deployment and management of applications on AWS. Here is an example workflow for deploying a Node.js application to Elastic Beanstalk. + +```yaml +name: Deploy to AWS Elastic Beanstalk + +on: + push: + branches: + - main + +jobs: + deploy: + runs-on: ubuntu-latest + + steps: + # Step 1: Checkout repository + - name: Checkout repository + uses: actions/checkout@v2 + + # Step 2: Configure AWS credentials + - name: Configure AWS Credentials + uses: aws-actions/configure-aws-credentials@v1 + with: + aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }} + aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }} + aws-region: us-east-1 + + # Step 3: Deploy to Elastic Beanstalk + - name: Deploy to Elastic Beanstalk + run: | + zip -r app.zip . # Zip the application + aws elasticbeanstalk create-application-version --application-name MyApp --version-label latest --source-bundle S3Bucket=my-app-bucket,S3Key=app.zip + aws elasticbeanstalk update-environment --environment-name MyApp-env --version-label latest +``` + +### 1.2 Deployment on Microsoft Azure + +Azure offers several services for hosting applications, such as **Azure App Service** and **Azure Kubernetes Service (AKS)**. With GitHub Actions, you can automate deployment to these services using Azure-specific actions. + +#### Example Workflow for Deploying to Azure App Service + +Azure App Service is a platform that allows deploying web applications on a managed environment. Here is an example workflow for deploying a web application to Azure App Service. + +```yaml +name: Deploy to Azure App Service + +on: + push: + branches: + - main + +jobs: + deploy: + runs-on: ubuntu-latest + + steps: + # Step 1: Checkout repository + - name: Checkout repository + uses: actions/checkout@v2 + + # Step 2: Configure Azure credentials + - name: Log in to Azure + uses: azure/login@v1 + with: + creds: ${{ secrets.AZURE_CREDENTIALS }} + + # Step 3: Deploy to Azure App Service + - name: Deploy to Azure App Service + uses: azure/webapps-deploy@v2 + with: + app-name: "my-app-service" + package: . +``` + +### 1.3 Deployment on Google Cloud Platform (GCP) + +Google Cloud Platform offers services like **Google App Engine**, **Google Cloud Run**, and **Google Kubernetes Engine (GKE)**. GitHub Actions can be used to automate deployments on GCP. + +#### Example Workflow for Deploying to Google Cloud Run + +Google Cloud Run enables deploying containerized applications directly from a GitHub repository. Here is an example workflow for deploying an application to Google Cloud Run. + +```yaml +name: Deploy to Google Cloud Run + +on: + push: + branches: + - main + +jobs: + deploy: + runs-on: ubuntu-latest + + steps: + # Step 1: Checkout repository + - name: Checkout repository + uses: actions/checkout@v2 + + # Step 2: Configure Google Cloud credentials + - name: Authenticate to Google Cloud + uses: google-github-actions/auth@v0 + with: + credentials_json: ${{ secrets.GCP_SA_KEY }} + + # Step 3: Set up Google Cloud SDK + - name: Set up Cloud SDK + uses: google-github-actions/setup-gcloud@v1 + with: + project_id: ${{ secrets.GCP_PROJECT_ID }} + service_account_key: ${{ secrets.GCP_SA_KEY }} + + # Step 4: Build and deploy Docker image to Cloud Run + - name: Build and Deploy to Cloud Run + run: | + gcloud builds submit --tag gcr.io/${{ secrets.GCP_PROJECT_ID }}/my-app + gcloud run deploy my-app --image gcr.io/${{ secrets.GCP_PROJECT_ID }}/my-app --region us-central1 +``` + +--- + +## 2. Practical Examples of Continuous Deployment Pipelines + +CI/CD pipelines consist of automated steps that handle the build, test, and deployment of an application. Here are some practical examples of continuous deployment pipelines with GitHub Actions. + +### Basic Pipeline for a Node.js Application Deployed to AWS S3 + +```yaml +name: CI/CD Pipeline for Node.js + +on: + push: + branches: + - main + +jobs: + build-and-deploy: + runs-on: ubuntu-latest + + steps: + # Step 1: Checkout repository + - name: Checkout repository + uses: actions/checkout@v2 + + # Step 2: Set up Node.js and dependencies + - name: Set up Node.js + uses: actions/setup-node@v2 + with: + node-version: '14' + + - name: Install dependencies + run: npm install + + # Step 3: Run tests + - name: Run tests + run: npm test + + # Step 4: Build application + - name: Build application + run: npm run build + + # Step 5: Connect to AWS + - name: Configure AWS Credentials + uses: aws-actions/configure-aws-credentials@v1 + with: + aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }} + aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }} + aws-region: us-west-1 + + # Step 6: Deploy the application to an S3 bucket + - name: Deploy to S3 + run: aws s3 sync ./build s3://my-app-bucket --delete +``` + +--- + +## 3. Deployment Strategies: Blue/Green, Canary + +GitHub Actions can be used to implement various **deployment strategies**, such as **Blue/Green** and **Canary** deployment, to minimize risks during production deployments. + +### 3.1 Blue/Green Deployment + +**Blue/Green deployment** involves running two distinct environments: the **Blue** (old) environment and the **Green** (new) environment. Once deployment is ready on the Green environment, traffic is switched to this environment. + +#### Example Workflow for Blue/Green Deployment + +```yaml +name: Blue/Green Deployment + +on: + push: + branches: + - main + +jobs: + deploy: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v2 + + # Step 1: Deploy to Green environment + - name: Deploy to Green environment + run: | + aws deploy create-deployment \ + --application-name my-app \ + --deployment-group-name GreenEnvironment \ + --s3-location bucket=my-app-bucket,bundleType=zip,key=my-app.zip + + # Step 2: Switch traffic to Green + - name: Switch traffic to Green + run: | + aws deploy update-deployment-group \ + --application-name my-app \ + --current-deployment-group-name BlueEnvironment \ + --new-deployment-group-name GreenEnvironment +``` + +### 3.2 Canary Deployment + +**Canary deployment** deploys a new version to a small percentage of users to test its impact. If the Canary version is stable, deployment is gradually extended to all users. + +#### Example Workflow for Canary Deployment + +```yaml +name: Canary Deployment + +on: + push: + branches: + - main + +jobs: + deploy: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v2 + + # Step 1: Deploy Canary release (small percentage of users) + - name: Deploy Canary release + run: | + aws deploy create-deployment \ + --application-name my-app \ + --deployment-group-name CanaryEnvironment \ + --s3-location bucket=my-app-bucket,bundleType=zip,key=my-app.zip \ + --deployment-config-name CodeDeployDefault.OneAtATime + + # Step 2: Gradually increase deployment + - name: Gradually increase deployment + run: | + aws deploy create-deployment \ + --application-name my-app \ + --deployment-group-name ProductionEnvironment \ + --s3-location bucket=my-app-bucket,bundleType=zip,key=my-app.zip +``` + +--- + +## 4. Deployment Status Notifications (Slack, Email) + +GitHub Actions enables sending notifications about the status of a successful or failed deployment via **Slack**, **Email**, or other collaboration tools. + +### 4.1 Slack Notifications + +You can configure GitHub Actions to send notifications via Slack when specific events + + occur, such as deployment completion. + +#### Example Workflow with Slack Notification + +```yaml +name: CI/CD Pipeline with Slack Notifications + +on: + push: + branches: + - main + +jobs: + build-and-deploy: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v2 + + - name: Build application + run: npm run build + + - name: Deploy to production + run: ./deploy.sh + + notify: + runs-on: ubuntu-latest + needs: build-and-deploy + steps: + - name: Send Slack Notification + uses: rtCamp/action-slack-notify@v2 + env: + SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }} + SLACK_MESSAGE: "The deployment to production was successful!" +``` + +### 4.2 Email Notifications + +You can also configure email notifications using GitHub actions or third-party services to send emails after deployment. + +#### Example Workflow with Email Notification + +```yaml +name: CI/CD Pipeline with Email Notifications + +on: + push: + branches: + - main + +jobs: + build-and-deploy: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v2 + + - name: Build application + run: npm run build + + - name: Deploy to production + run: ./deploy.sh + + notify: + runs-on: ubuntu-latest + needs: build-and-deploy + steps: + - name: Send Email Notification + uses: dawidd6/action-send-mail@v2 + with: + server_address: smtp.gmail.com + server_port: 465 + username: ${{ secrets.EMAIL_USERNAME }} + password: ${{ secrets.EMAIL_PASSWORD }} + subject: "Deployment Status" + body: "The deployment was successful." + to: "recipient@example.com" +``` + +--- + +## Conclusion + +Continuous Deployment with GitHub Actions simplifies and automates the process of moving applications to production. Through integration with cloud platforms like AWS, Azure, and GCP, as well as deployment strategies such as Blue/Green or Canary, you can reduce deployment risks and ensure continuous delivery. Additionally, the ability to send notifications via Slack or Email enhances visibility on deployment status, allowing teams to respond quickly to issues. + +GitHub Actions offers extensive flexibility to automate your entire deployment pipeline, enabling you to optimize the way you manage application delivery. \ No newline at end of file diff --git a/wiki/docs/en/onboarding/hands-on-labs/learn-github-actions/first-step.md b/wiki/docs/en/onboarding/hands-on-labs/learn-github-actions/first-step.md new file mode 100644 index 0000000..7c088ef --- /dev/null +++ b/wiki/docs/en/onboarding/hands-on-labs/learn-github-actions/first-step.md @@ -0,0 +1,268 @@ +# Getting Started with GitHub Actions + +GitHub Actions is an integrated platform that enables you to create, run, and automate workflows directly within GitHub. In this section, we will explore how to set up a basic workflow, understand the YAML syntax used to define these workflows, and discover the various available event triggers. + +--- + +## 1. Basic Setup: `.github/workflows` + +To start using GitHub Actions, you need to create a specific directory in your GitHub repository to store your workflow files. This directory should be named **`.github/workflows`**. + +### Steps to create your first workflow: +1. **Create the directory**: In the root of your project, create the `.github/workflows` directory. +2. **Add a workflow file**: Workflows are defined in YAML files (with the `.yml` extension). For example, you can create a file named `ci.yml` for a CI workflow. + +### Example of a repository structure with a workflow: + +```text +my-project/ +├── .github/ +│ └── workflows/ +│ └── ci.yml +├── src/ +├── README.md +└── package.json +``` + +The workflow file contains all the steps that GitHub Actions must execute when an event is triggered, such as a `push` or `pull request`. This YAML file specifies the jobs, actions, and other parameters that form the basis of your CI/CD pipeline. + +--- + +## 2. Simple Example of a CI Workflow + +Here is a simple CI workflow example that runs every time a change is pushed to the `main` branch. This workflow installs dependencies, runs tests, and builds the project. + +```yaml +name: CI Pipeline # Workflow name + +# This workflow is triggered on a push or pull request to the 'main' branch +on: + push: + branches: + - main + pull_request: + branches: + - main + +jobs: + build: # Job name + runs-on: ubuntu-latest # Environment where the job runs + + steps: + # Step 1: Check out the source code + - name: Checkout repository + uses: actions/checkout@v2 + + # Step 2: Set up Node.js + - name: Set up Node.js + uses: actions/setup-node@v2 + with: + node-version: '14' + + # Step 3: Install dependencies + - name: Install dependencies + run: npm install + + # Step 4: Run tests + - name: Run tests + run: npm test + + # Step 5: Build the project + - name: Build project + run: npm run build +``` + +### Explanation: +- **`name:`**: Gives a name to the workflow. This name is visible in the GitHub Actions interface. +- **`on:`**: Specifies the events that trigger the workflow. In this example, the workflow runs when there is a `push` or `pull request` on the `main` branch. +- **`jobs:`**: Defines the different jobs in the workflow. Each job can contain multiple steps. +- **`runs-on:`**: Indicates the environment where the job will be executed (here, an Ubuntu machine hosted by GitHub). +- **`steps:`**: Steps to execute within the job, which may include pre-built actions (such as `actions/checkout@v2`) or commands to run. + +--- + +## 3. YAML Syntax for Defining Workflows + +GitHub Actions workflows are written in YAML, a format that is simple to read and write, allowing you to structure workflows with jobs, steps, actions, and variables. Here is a detailed explanation of the basic syntax for GitHub Actions YAML files. + +### General Structure of a GitHub Actions YAML File: +```yaml +name: Workflow name + +on: # Event trigger(s) + push: + branches: + - main + +jobs: # Jobs to execute + job_name: # Job name + runs-on: environment # Execution environment (e.g., ubuntu-latest, windows-latest, macos-latest) + + steps: # Steps to execute within this job + - name: Step name + uses: action@version # Using a pre-defined action + with: # Arguments passed to the action + param: value + + - name: Step name + run: shell_command # Shell command to execute +``` + +### Common YAML Elements: +- **`name:`**: Workflow name. +- **`on:`**: Events that trigger the workflow, such as `push`, `pull_request`, `schedule`, or others. +- **`jobs:`**: Defines the jobs, which contain steps to execute. +- **`runs-on:`**: Specifies the execution environment for the job (e.g., `ubuntu-latest`, `windows-latest`, `macos-latest`). +- **`steps:`**: Steps in a job, which can include pre-defined actions or custom commands to execute. + +### Examples of Steps: +1. **Using a Predefined Action**: + ```yaml + - name: Checkout code + uses: actions/checkout@v2 + ``` + Here, we use the `actions/checkout@v2` action to retrieve the repository’s source code. + +2. **Running a Custom Command**: + ```yaml + - name: Run tests + run: npm test + ``` + This step runs the `npm test` command to execute the project's tests. + +--- + +## 4. Triggers (events): `push`, `pull_request`, `schedule`, etc. + +GitHub Actions workflows can be triggered by a variety of events. Here are the most common triggers: + +### 4.1. `push` + +The `push` trigger is used to run a workflow whenever a `push` is made to the repository. You can also specify specific branches or paths for which the workflow should run. + +#### Example: +```yaml +on: + push: + branches: + - main + paths: + - 'src/**' +``` +- **`branches:`**: The workflow will trigger only when changes are pushed to the `main` branch. +- **`paths:`**: The workflow will only run if the modified files are located in the `src` directory. + +### 4.2. `pull_request` + +The `pull_request` trigger runs a workflow when a new pull request is created or updated. + +#### Example: +```yaml +on: + pull_request: + branches: + - main +``` +In this example, the workflow will be triggered for all pull requests opened on the `main` branch. + +### 4.3. `schedule` + +The `schedule` trigger allows you to define workflows that run at specific times, similar to a cron job. + +#### Example: +```yaml +on: + schedule: + - cron: "0 0 * * 1" +``` +This example triggers the workflow every Monday at midnight (UTC). The `cron` format is the same as that used in Linux cron jobs. + +### 4.4. Other Triggers + +- **`workflow_dispatch`**: Allows a workflow to be manually triggered through the GitHub UI. +- **`workflow_call`**: Allows a workflow to be invoked from another workflow. This is useful for reusing workflows across multiple projects or repositories. +- **`release`**: Triggers the workflow when a new release is published. +- **`issue_comment`**: Executes the workflow when a comment is added to an issue. +- **`push_tag`**: Triggers the workflow when a tag is pushed. + +#### Example of `workflow_dispatch`: +```yaml +on: + workflow_dispatch: +``` + +This workflow can be manually triggered from the GitHub Actions interface. For example, here is [a real use case](https://github.com/ClubCedille/Plateforme-Cedille/blob/master/.github/workflows/add-new-member.yml) of `workflow_dispatch` for the CEDILLE Platform, allowing the addition of a new member to the organization via the GitHub Actions user interface: + +```yaml +name: Add a new member to the organization +on: + workflow_dispatch: + inputs: + github_username: + description: 'GitHub username' + required: true + type: string + github_email: + description: 'GitHub Email' + required: true + type: string + team_sre: + description: 'Add to SRE team?' + required: false + type: boolean + cluster_role: + description: 'Cluster Role' + required: true + type: choice + options: + - None + - Reader + - Operator + - Admin +``` + +In this example, the workflow allows the administrator to add a new member to the organization, modify Terraform files, and create a Pull Request to apply these changes. + +#### Example of `workflow_call`: +```yaml +on: + workflow_call: +``` + +The `workflow_call` trigger allows a workflow to be called from another workflow. This is an effective way to share and reuse workflows across multiple projects or teams. For example, in the [cedille-workflows](https://github.com/ClubCedille/cedille-workflows) repository, we use this trigger type to centralize and reuse standardized workflows across different projects. + +Here is an example of using `workflow_call`: + +```yaml +name: Reuse a workflow + +on: + workflow_call: + inputs: + environment: + description: 'Target environment (dev, staging, prod)' + required: true + type: string + +jobs: + build: + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v2 + + + + - name: Run build + run: echo "Building for ${{ inputs.environment }}" +``` +In this example, the workflow can be invoked by other workflows to perform a specific task, such as building or deploying to a particular environment. + +--- + +## Conclusion + +With GitHub Actions, the basic setup for automating CI/CD workflows is simple and powerful. By creating workflows in the `.github/workflows` directory, you can automate tasks in response to various events such as `push`, `pull_request`, or scheduled times via `schedule`. The YAML syntax allows you to easily define jobs and steps, and the flexibility of triggers makes GitHub Actions adaptable to different development and deployment scenarios. + +GitHub Actions is designed to be intuitive and extendable using pre-built or custom actions, making it an essential tool for any modern CI/CD pipeline. \ No newline at end of file diff --git a/wiki/docs/en/onboarding/hands-on-labs/learn-github-actions/index.md b/wiki/docs/en/onboarding/hands-on-labs/learn-github-actions/index.md new file mode 100644 index 0000000..dc9de95 --- /dev/null +++ b/wiki/docs/en/onboarding/hands-on-labs/learn-github-actions/index.md @@ -0,0 +1,42 @@ +# Learning GitHub Actions + +Welcome to the GitHub Actions documentation for beginners! + +This guide is designed to help you get started with GitHub Actions, a powerful tool that allows you to automate Continuous Integration (CI), Continuous Deployment (CD), and much more directly from your GitHub repository. Whether you're an experienced developer or simply curious about GitHub Actions, this documentation will provide the foundational knowledge you need to start automating your workflows and streamlining your DevOps processes. + +--- + +## Table of Contents + +- **Introduction to GitHub Actions** + Learn key concepts such as workflows, jobs, steps, and runners, as well as the differences between GitHub Actions and other CI/CD tools. + +- **Getting Started with GitHub Actions** + Discover how to set up your first workflows, write YAML files, and use triggers to automate your tasks. + +- **Creating Custom Workflows** + Understand how to create more advanced workflows by defining jobs, using pre-built actions from the GitHub Marketplace, and creating your own custom actions. + +- **Integration with Docker and Kubernetes** + Learn how to automate Docker image builds, push them to registries, and deploy your applications to Kubernetes clusters. + +- **Continuous Deployment with GitHub Actions** + Explore deployment strategies for your applications on cloud platforms such as AWS, Azure, and GCP, and learn how to configure deployment notifications. + +- **Using GitHub Container Registry (GHCR)** + Discover how to use GitHub Container Registry to manage and distribute container images directly from GitHub. + +- **Security and Permissions Management** + Learn to use GitHub Secrets to manage sensitive information, configure workflow permissions, and integrate Dependabot for dependency security scanning. + +- **CI/CD Workflow Optimization** + Learn how to speed up your workflows by caching dependencies, managing dependency and action versions, and effectively debugging workflows. + +- **Monitoring and Reporting** + Discover how to monitor your workflows, generate automated test reports, and configure notifications for build success or failure. + +- **Practical Examples: DevOps with GitHub Actions** + Explore practical examples for deploying Node.js applications with Docker, managing CI/CD pipelines with cloud services, and automating complete DevOps chains. + +- **Best Practices and DevOps Patterns with GitHub Actions** + Discover strategies for structuring workflows in complex projects, centralizing configuration files, and managing multiple environments (development, staging, production). \ No newline at end of file diff --git a/wiki/docs/en/onboarding/hands-on-labs/learn-github-actions/integration.md b/wiki/docs/en/onboarding/hands-on-labs/learn-github-actions/integration.md new file mode 100644 index 0000000..f819169 --- /dev/null +++ b/wiki/docs/en/onboarding/hands-on-labs/learn-github-actions/integration.md @@ -0,0 +1,261 @@ +# Integration with Docker and Kubernetes in GitHub Actions + +GitHub Actions can be used to automate Docker- and Kubernetes-related tasks, such as building and publishing Docker images, as well as deploying these images to Kubernetes clusters. In this documentation, we’ll explore how to use GitHub Actions to integrate Docker and Kubernetes into your CI/CD pipelines. + +--- + +## 1. Building and Pushing Docker Images with GitHub Actions + +Docker is a lightweight virtualization tool that allows you to create containers for running applications in isolated environments. With GitHub Actions, you can automate the building of these containers and push them to a Docker registry (such as Docker Hub or GitHub Container Registry). + +### Steps to Build and Push Docker Images + +1. **Write a Dockerfile** + The Dockerfile contains the instructions to create a Docker image from your project. Here is a simple example of a Dockerfile for a Node.js application: + + ```dockerfile + # Use an official Node.js base image + FROM node:14 + + # Set the working directory + WORKDIR /app + + # Copy the package.json file + COPY package*.json ./ + + # Install dependencies + RUN npm install + + # Copy the rest of the project files + COPY . . + + # Expose the application’s port + EXPOSE 3000 + + # Start the application + CMD ["npm", "start"] + ``` + +2. **Configure GitHub Actions to build and push the image** + + Once the Dockerfile is created, you can set up a GitHub Actions workflow to build the Docker image and then push it to a Docker registry. + +### Example Workflow: Building and Pushing a Docker Image + +The following workflow runs when a change is pushed to the `main` branch. It builds a Docker image from the Dockerfile and pushes it to Docker Hub. + +```yaml +name: Build and Push Docker Image + +# Trigger the workflow on a push to the 'main' branch +on: + push: + branches: + - main + +jobs: + build: + runs-on: ubuntu-latest # Use an Ubuntu environment + + steps: + # Step 1: Checkout the repository + - name: Checkout code + uses: actions/checkout@v2 + + # Step 2: Log in to Docker Hub + - name: Log in to Docker Hub + uses: docker/login-action@v2 + with: + username: ${{ secrets.DOCKER_USERNAME }} # Store the username as a secret + password: ${{ secrets.DOCKER_PASSWORD }} # Store the password as a secret + + # Step 3: Build the Docker image + - name: Build Docker image + run: docker build -t ${{ secrets.DOCKER_USERNAME }}/my-app:latest . + + # Step 4: Push the Docker image to Docker Hub + - name: Push Docker image + run: docker push ${{ secrets.DOCKER_USERNAME }}/my-app:latest +``` + +### Workflow Explanation: +- **`docker/login-action@v2`**: This action logs into Docker Hub using securely stored username and password in the repository’s secrets. +- **`docker build`**: This command builds a Docker image from the Dockerfile in the project root. +- **`docker push`**: This command pushes the Docker image to Docker Hub. + +### Using GitHub Container Registry + +GitHub Container Registry (GHCR) is an alternative to Docker Hub for hosting Docker images. It’s integrated with GitHub and allows you to store and manage your container images alongside your source code. + +#### Example Workflow to Push to GitHub Container Registry (GHCR) + +```yaml +name: Build and Push Docker Image to GHCR + +on: + push: + branches: + - main + +jobs: + build: + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v2 + + - name: Log in to GitHub Container Registry + run: echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u ${{ github.actor }} --password-stdin + + - name: Build Docker image + run: docker build -t ghcr.io/${{ github.repository }}/my-app:latest . + + - name: Push Docker image + run: docker push ghcr.io/${{ github.repository }}/my-app:latest +``` + +In this example, the image is pushed to GitHub Container Registry instead of Docker Hub. + +--- + +## 2. Automating Kubernetes Deployments with GitHub Actions + +Kubernetes is a popular container orchestrator used to deploy, manage, and scale containerized applications. GitHub Actions can be used to automate the deployment of Docker images to a Kubernetes cluster. + +### Steps to Deploy on Kubernetes with GitHub Actions + +1. **Configure `kubectl` to interact with your Kubernetes cluster** + First, configure GitHub Actions to use `kubectl`, the Kubernetes command-line tool, to interact with your Kubernetes cluster. + +2. **Use Secrets to Store Sensitive Information** + Store sensitive information, such as Kubernetes cluster credentials and certificates, in GitHub secrets to use them securely. + +### Example Workflow: Automated Kubernetes Deployment + +The following workflow uses `kubectl` to deploy the Docker image to a Kubernetes cluster after it has been pushed to Docker Hub. + +```yaml +name: Deploy to Kubernetes + +on: + push: + branches: + - main + +jobs: + deploy: + runs-on: ubuntu-latest + + steps: + # Step 1: Checkout the repository + - name: Checkout code + uses: actions/checkout@v2 + + # Step 2: Install kubectl + - name: Set up kubectl + uses: azure/setup-kubectl@v3 + with: + version: 'latest' + + # Step 3: Configure access to the Kubernetes cluster + - name: Set up kubeconfig + run: | + mkdir -p ~/.kube + echo "${{ secrets.KUBECONFIG }}" > ~/.kube/config + + # Step 4: Update the Kubernetes deployment + - name: Deploy to Kubernetes + run: | + kubectl set image deployment/my-app my-app-container=${{ secrets.DOCKER_USERNAME }}/my-app:latest +``` + +### Workflow Explanation: + +- **`azure/setup-kubectl@v3`**: This action installs `kubectl` in the workflow environment. +- **`kubeconfig`**: The `kubeconfig` file contains authentication information to interact with the Kubernetes cluster and is stored securely in GitHub secrets. +- **`kubectl set image`**: This command updates the Kubernetes deployment with the new container image. + +At CEDILLE, we use GitOps tools like **ArgoCD** to automatically manage deployments and synchronize applications with Kubernetes clusters. ArgoCD simplifies automation by monitoring Git repositories for changes and automatically applying them to clusters, eliminating the need to manually handle these aspects via GitHub Actions. + +--- + +## 3. Examples of Using `docker`, `kubectl`, and `helm` in CI/CD Workflows + +By combining Docker, `kubectl`, and Helm, you can create powerful CI/CD workflows to automate container management and Kubernetes deployments. Here is an example of a GitHub Actions workflow that incorporates both `kubectl` and **Helm**. + +### Example: Using Docker with `kubectl` and Helm + +In this example, we will build a Docker image, push it to Docker Hub, and then update a Kubernetes deployment with this new image. We also demonstrate how to use **Helm** to manage more complex deployments. + +#### CI/CD Workflow for Docker and Kubernetes + +```yaml +name: CI/CD for Docker and Kubernetes + +on: + push: + branches: + - main + +jobs: + build-and-deploy: + runs-on: ubuntu-latest + + steps: + # Step 1: Checkout repository + - name: Checkout repository + uses: actions/checkout@v2 + + # Step 2: Log in to Docker Hub + - name: Log in to Docker Hub + uses: docker/login-action@v2 + with: + username: ${{ secrets.DOCKER_USERNAME }} + password: ${{ secrets.DOCKER_PASSWORD }} + + # Step 3: Build Docker image + - name: Build Docker image + run: docker build -t ${{ secrets.DOCKER_USERNAME }}/my-app:latest . + + # Step 4: Push Docker image + - name: Push Docker image + run: docker push ${{ secrets.DOCKER_USERNAME }}/my-app:latest + + # Step 5: Set up kubectl + - name: Set up kubectl + uses: azure/setup-kubectl@v3 + with: + version: 'latest' + + # Step 6: Deploy to Kubernetes with kubectl + - name: Update Kubernetes Deployment with kubectl + run: | + kubectl set image deployment/my-app my-app-container=${{ secrets.DOCKER_USERNAME }}/my-app:latest + + # Step 7 (optional): Deploy application with Helm + - name: Install Helm + run: | + curl https://raw.githubusercontent.com/helm/helm/master/scripts/get-helm-3 | bash + + - name: Deploy application with Helm + run: helm upgrade --install my-app ./helm-chart --set image.tag=latest +``` + +### Workflow Explanation: + +1. **kubectl**: Step 6 updates the Kubernetes deployment’s container image using `kubectl`. +2. **Helm**: Steps 7 and onward demonstrate how to install **Helm** and use it to deploy or update a Kubernetes application from a Helm chart. Helm is particularly useful for managing more complex Kubernetes deployments. +3. **Secrets**: The Kubernetes configuration file (`kubeconfig`) + + is stored in GitHub secrets to ensure the security of authentication information. + +In this workflow, you can choose to use either **kubectl** for simple deployments or **Helm** for more complex deployments. Integrating both tools in the same workflow allows you to manage a variety of use cases depending on the complexity of your Kubernetes deployments. + +--- + +## Conclusion + +Integrating Docker and Kubernetes into your CI/CD workflows with GitHub Actions simplifies the building, testing, and deployment of containerized applications. Whether using Docker to create images or Kubernetes to orchestrate these containers, GitHub Actions provides the tools needed to fully automate these processes. This enables you to build, test, and deploy applications smoothly and securely while reducing manual errors. + +By using `docker`, `kubectl`, and Helm in your workflows, you can create robust and flexible pipelines suitable for production, testing, or any other Kubernetes environment. \ No newline at end of file diff --git a/wiki/docs/en/onboarding/hands-on-labs/learn-github-actions/introductions.md b/wiki/docs/en/onboarding/hands-on-labs/learn-github-actions/introductions.md new file mode 100644 index 0000000..2121182 --- /dev/null +++ b/wiki/docs/en/onboarding/hands-on-labs/learn-github-actions/introductions.md @@ -0,0 +1,191 @@ +# Introduction to GitHub Actions + +## What is GitHub Actions? + +GitHub Actions is an automation platform integrated into GitHub that allows you to create, manage, and run automated workflows directly from your GitHub repositories. With GitHub Actions, you can set up Continuous Integration (CI) and Continuous Deployment (CD) processes, automate tests, builds, deployments, and much more. + +The key strength of GitHub Actions lies in its native integration with GitHub, enabling you to trigger workflows based on repository events like `push`, `pull requests`, or even custom triggers such as scheduled `cron` jobs. + +### Key Features of GitHub Actions: +- **Full GitHub Integration**: Workflows can be triggered by GitHub events such as `push`, `pull request`, `issues`, and many more. +- **Flexibility**: GitHub Actions is highly customizable, with hundreds of actions available in the [GitHub Marketplace](https://github.com/marketplace?type=actions). +- **Hosted and Self-hosted Runners**: GitHub provides preconfigured build environments, or you can use your own machines to run workflows. + +--- + +## Primary Use in Continuous Integration (CI) and Continuous Deployment (CD) + +GitHub Actions is particularly useful for implementing Continuous Integration (CI) and Continuous Deployment (CD) pipelines. Here’s an overview of each concept: + +### Continuous Integration (CI) + +Continuous Integration is a process in which developers regularly merge their code changes into the main branch of the repository. Automated tests are run to ensure that the newly integrated code does not break the project. GitHub Actions automates this process by creating workflows that run automatically whenever a `push` or a `pull request` is made to a repository. + +- **CI Use Case Examples**: + - Automatically running unit tests after each `commit` or `pull request`. + - Automatically building the code to check for syntax or compilation errors. + +```yaml +name: CI Pipeline + +on: [push, pull_request] + +jobs: + build: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v2 + + - name: Set up Node.js + uses: actions/setup-node@v2 + with: + node-version: '14' + + - name: Install dependencies + run: npm install + + - name: Run tests + run: npm test +``` + +### Continuous Deployment (CD) + +Continuous Deployment automates the deployment of your application to different environments (development, staging, production). GitHub Actions can be used to trigger deployments after successful tests. For instance, you can set up a workflow to deploy an application to a cloud service like AWS, Azure, or GCP after every `merge` to the main branch. + +- **CD Use Case Examples**: + - Deploying an application to AWS after a successful `merge` to the `main` branch. + - Automating releases with workflows that automatically generate application versions and publish them. + +```yaml +name: CD Pipeline + +on: + push: + branches: + - main + +jobs: + deploy: + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v2 + + - name: Deploy to AWS + uses: aws-actions/configure-aws-credentials@v1 + with: + aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }} + aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }} + aws-region: us-west-2 + + - name: Deploy application + run: | + aws s3 sync ./build s3://my-app-bucket +``` + +--- + +## Key Concepts of GitHub Actions + +GitHub Actions is based on several key concepts that help structure and organize automation workflows. Here’s a detailed explanation of the fundamental terms: + +### Workflows + +A **workflow** is an automation defined in a YAML file located in the `.github/workflows/` directory. A workflow consists of one or more **jobs** that run in response to specific events. For instance, a workflow can be triggered whenever a developer pushes code to the repository. + +- **Event Triggers**: Workflows are triggered by specific events, such as a `push`, `pull request`, or scheduled events with a `cron` job. +- **Job Definitions**: A workflow contains one or more jobs. Each job is a series of steps executed in an isolated environment. + +### Jobs + +A **job** is a sequence of **steps** that runs in an isolated environment. By default, all jobs in a workflow run in parallel, but they can be configured to run sequentially if one job depends on another. + +- **Parallel Execution**: Multiple jobs can run in parallel to reduce total execution time. +- **Job Dependencies**: A job can depend on the completion of another job. + +```yaml +jobs: + job1: + runs-on: ubuntu-latest + steps: + - name: Step 1 + run: echo "Job 1 Step 1" + + job2: + needs: job1 # Depends on job1 + runs-on: ubuntu-latest + steps: + - name: Step 1 + run: echo "Job 2 Step 1" +``` + +### Actions + +An **action** is an individual task you can run in a job. GitHub Actions offers a large library of pre-built actions available in the [GitHub Marketplace](https://github.com/marketplace?type=actions). You can also create your own actions for specific needs. + +- **Marketplace Actions**: You can reuse actions developed by others, such as `actions/checkout` to check out code or `actions/setup-node` to set up Node.js. +- **Custom Actions**: You can create project-specific actions using Bash scripts or by creating Docker containers. For a detailed example of creating a custom action, check out the [Cedille-Actions-By-Example](https://github.com/ClubCedille/cedille-actions-by-example) repository, which illustrates how to structure and configure an action like **KubeSketcher**, an action to generate Kubernetes namespace architecture diagrams. + +```yaml +steps: + - name: Checkout repository + uses: actions/checkout@v2 # Predefined action from Marketplace + + - name: Run custom script + run: ./my-custom-script.sh # Custom action +``` + +### Runners + +A **runner** is the machine that executes the job defined in a workflow. GitHub offers **hosted runners** (machines preconfigured by GitHub), and you can also configure your own **self-hosted runners** if you have specific requirements for the runtime environment. + +- **Hosted Runners**: GitHub provides hosted runners on Linux, Windows, and macOS with commonly used CI/CD tools already installed. +- **Self-hosted Runners**: If you have specific hardware or security requirements, you can configure your own runners using your machines. + +```yaml +jobs: + build: + runs-on: ubuntu-latest # Uses a hosted runner on Ubuntu + + custom-build: + runs-on: self-hosted # Uses a self-hosted runner +``` + +--- + +## Differences Between GitHub Actions and Other CI/CD Tools + +GitHub Actions stands out due to its native integration with GitHub, flexibility, and ease of configuration. Here are some major differences between GitHub Actions and other CI/CD tools like Jenkins, Travis CI, or CircleCI: + +### Native Integration with GitHub + +Unlike other CI/CD tools that require external integration with GitHub, GitHub Actions is directly embedded in the GitHub interface. This means you can manage your CI/CD workflows without leaving GitHub, with easy management of triggers, secrets, and permissions. + +### Flexibility + +GitHub Actions is extremely flexible, allowing you to define your workflows using a simple YAML file. You also have access to a wide variety of predefined actions in the Marketplace and the ability to create custom actions. + +### Execution within GitHub + +Workflows run directly within GitHub using hosted runners. Other services, like Jenkins, often require setting up your own execution servers. + +### Feature Comparison + +| CI/CD Tools | GitHub Actions | Jenkins | Travis CI | CircleCI | +|--------------------|----------------------|--------------------|--------------------|--------------------| +| **Integration** | Native GitHub | External | External | External | +| **Configuration** | YAML in repository | Jenkins interface | YAML in repository | YAML in repository | + +| **Features** | **GitHub Actions** | **Jenkins** | **CircleCI** | **GitLab CI/CD** | +|-----------------------|-------------------------|--------------------|---------------------|--------------------------| +| **Runners** | Hosted / Self-hosted | Jenkins servers | Hosted only | Hosted / Self-hosted | +| **Marketplace** | Yes, with actions | Jenkins plugins | Yes | Yes | + +--- + +## Conclusion + +GitHub Actions is a powerful platform for automating your CI/CD pipelines directly within GitHub. With its seamless integration, flexibility, and variety of available tools, GitHub Actions simplifies workflow automation for developers while remaining adaptable to the specific needs of each project. Whether for a small project or a large DevOps infrastructure, GitHub Actions is a robust and scalable solution. \ No newline at end of file diff --git a/wiki/docs/en/onboarding/hands-on-labs/learn-github-actions/monitoring.md b/wiki/docs/en/onboarding/hands-on-labs/learn-github-actions/monitoring.md new file mode 100644 index 0000000..b9ffdc9 --- /dev/null +++ b/wiki/docs/en/onboarding/hands-on-labs/learn-github-actions/monitoring.md @@ -0,0 +1,241 @@ +# Monitoring and Reporting with GitHub Actions + +Monitoring and reporting in GitHub Actions are essential to ensure CI/CD workflows run smoothly and to quickly identify issues. This guide explains how to monitor workflow status, manage logs and diagnostics, generate automated test reports, view workflows in the GitHub interface, and notify teams of build success or failure. + +--- + +## 1. Workflow Monitoring: Build Status, Logs, and Diagnostics + +### 1.1 Monitoring Build Status + +GitHub Actions provides an intuitive user interface that allows real-time monitoring of build status. You can access this interface through the **Actions** tab in your GitHub repository. Each triggered workflow generates a build with a visible status (success, failure, in progress). + +#### Build Status Indicators: +- **Green (Success)**: All jobs in the workflow have completed successfully. +- **Red (Failure)**: One or more jobs have failed. +- **Yellow (In Progress)**: The workflow is currently running. + +### 1.2 Accessing Workflow Logs + +To diagnose issues, GitHub Actions provides detailed logs for each workflow step. These logs include command output and any errors encountered. + +#### Viewing Logs: +1. Go to the **Actions** tab in your repository. +2. Select a specific workflow. +3. Click on a job to view its steps. +4. You can view logs for each step by clicking the expand button next to the step name. + +The logs provide valuable information, such as success, error, or debug messages. If a job fails, the logs are the best place to look for error details. + +#### Example: Viewing Logs After a Workflow Failure + +When a workflow fails, GitHub highlights problematic steps. You can view the log details to understand the cause of the failure: + +```bash +Run npm install +npm ERR! code ENOENT +npm ERR! syscall open +npm ERR! path /build/package.json +npm ERR! errno -2 +``` + +### 1.3 Diagnosing Issues + +GitHub Actions also allows you to rerun a workflow with more detailed logging to diagnose issues. You can enable **advanced debugging** to obtain additional information. + +#### Enabling Debug Logs: +1. Go to the workflow logs page. +2. Click **Rerun jobs with debug logging** to rerun the workflow in debug mode. +3. Detailed logs will help you understand why the job failed. + +--- + +## 2. Generating Automated Test Reports + +Automated testing is crucial to ensure code quality. By combining GitHub Actions with testing tools like JUnit, Mocha, or Jest, you can generate and publish test reports within your CI/CD workflows. + +### 2.1 Example Workflow with JUnit Test Report + +JUnit is one of the most common testing frameworks for Java applications. Here’s an example GitHub Actions workflow that runs JUnit tests and generates test reports. + +```yaml +name: Run JUnit Tests + +on: [push] + +jobs: + test: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v2 + + - name: Set up JDK + uses: actions/setup-java@v2 + with: + java-version: '11' + + - name: Run tests with JUnit + run: ./gradlew test + + - name: Archive test results + uses: actions/upload-artifact@v2 + with: + name: junit-results + path: build/test-results/test/*.xml +``` + +#### Explanation: +- **JUnit Tests**: JUnit tests are executed with the `./gradlew test` command. +- **Archive test results**: JUnit test results in XML format are saved as artifacts, which you can view in the GitHub interface. + +### 2.2 Viewing Test Reports + +GitHub Actions doesn’t provide native test report visualization, but you can generate and view test results using third-party services, or export results as downloadable artifacts. + +### 2.3 Generating Code Coverage Reports + +You can integrate tools like **Codecov** or **Coveralls** into your GitHub Actions workflows to generate code coverage reports. + +#### Example: Workflow with Codecov + +```yaml +name: Codecov Test and Coverage + +on: + push: + branches: + - main + +jobs: + test: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v2 + + - name: Run tests + run: npm test -- --coverage + + - name: Upload coverage to Codecov + uses: codecov/codecov-action@v2 + with: + token: ${{ secrets.CODECOV_TOKEN }} +``` + +--- + +## 3. Visualizing Workflows on the GitHub Interface + +GitHub provides a graphical view of CI/CD workflows for each repository. This view enables developers to follow the execution process, identify errors, and understand job dependencies. + +### 3.1 Workflow Visualization Interface + +1. Go to the **Actions** tab in your repository. +2. You’ll see a list of recently triggered workflows. +3. Clicking on a specific workflow lets you access a graphical view of the jobs and their statuses (success, failure, or pending). + +Each job is represented in a flow diagram, making it easy to visualize the pipeline stages and quickly identify failure points. + +### 3.2 Tracking Artifacts + +Artifacts generated by a workflow (build files, test results, logs) are accessible through the Actions interface. You can download them for analysis or archive them for future reference. + +--- + +## 4. Notifying Teams on Build Success or Failure + +Automatic notifications are essential to alert teams to workflow successes or failures in CI/CD. GitHub Actions integrates with communication tools like **Slack**, **Microsoft Teams**, or email services to send alerts based on build status. + +### 4.1 Notifying via Slack + +GitHub Actions allows you to send Slack notifications when a workflow succeeds or fails. You can use a **Slack Webhook** for this purpose. + +#### Example: Slack Notification for a CI/CD Workflow + +1. Create a **Slack Webhook** in your workspace. +2. Add the webhook to GitHub Actions as a secret (`SLACK_WEBHOOK_URL`). + +```yaml +name: Notify Slack on Build + +on: + push: + branches: + - main + +jobs: + notify: + runs-on: ubuntu-latest + + steps: + - name: Send Slack notification on success + if: success() + run: | + curl -X POST -H 'Content-type: application/json' \ + --data '{"text":"Build succeeded for ${{ github.repository }}"}' \ + ${{ secrets.SLACK_WEBHOOK_URL }} + + - name: Send Slack notification on failure + if: failure() + run: | + curl -X POST -H 'Content-type: application/json' \ + --data '{"text":"Build failed for ${{ github.repository }}"}' \ + ${{ secrets.SLACK_WEBHOOK_URL }} +``` + +#### Explanation: +- **`if: success()`** and **`if: failure()`**: These conditions send different notifications based on whether the build succeeded or failed. +- **`curl`**: Used to send a POST request to Slack with the appropriate message. + +### 4.2 Email Notifications + +GitHub Actions can also send email notifications using an SMTP service or third-party tools like **SendGrid** or **Mailgun**. + +#### Example: Email Notification Workflow + +```yaml +name: Notify on Build Status + +on: + push: + branches: + - main + +jobs: + notify: + runs-on: ubuntu-latest + + steps: + - name: Send email on success + if: success() + uses: dawidd6/action-send-mail@v2 + with: + server_address: smtp.gmail.com + server_port: 465 + username: ${{ secrets.EMAIL_USERNAME }} + password: ${{ secrets.EMAIL_PASSWORD }} + subject: "Build Success" + body: "The build for ${{ github.repository }} succeeded!" + to: "team@example.com" + + - name: Send email on failure + if: failure() + uses: dawidd6/action-send-mail@v2 + with: + server_address: smtp.gmail.com + server_port: 465 + username: ${{ secrets.EMAIL_USERNAME }} + password: ${{ secrets.EMAIL_PASSWORD }} + subject: "Build Failure" + body: "The build for ${{ github.repository }} failed!" + to: "team@example.com" +``` + +--- + +## Conclusion + +Monitoring and reporting are crucial aspects of managing CI/CD workflows with GitHub Actions. Using detailed logs, test reports, and notification tools, you can proactively monitor build status and quickly diagnose issues. Integration with tools like Slack or email services keeps teams informed in real-time, ensuring fast resolution of build failures and better collaboration within development teams. \ No newline at end of file diff --git a/wiki/docs/en/onboarding/hands-on-labs/learn-github-actions/practices.md b/wiki/docs/en/onboarding/hands-on-labs/learn-github-actions/practices.md new file mode 100644 index 0000000..c2b22b1 --- /dev/null +++ b/wiki/docs/en/onboarding/hands-on-labs/learn-github-actions/practices.md @@ -0,0 +1,245 @@ +# Best Practices and DevOps Patterns with GitHub + +Adopting best practices and DevOps patterns is essential for ensuring robust, scalable, and efficient CI/CD pipelines in complex projects. GitHub Actions, with its automation features, enables workflow structuring, multi-environment management, and streamlined team collaboration. This guide provides strategies and best practices for structuring workflows, centralizing configurations, managing development environments, and collaborating effectively through GitHub Actions. + +--- + +## 1. Structuring Workflows for Complex Projects + +In complex projects, structuring workflows is crucial for maintaining a smooth and manageable CI/CD lifecycle. This includes dividing workflows into specific stages, reusing workflows, and managing job dependencies. + +### 1.1. Divide Workflows into Clear Stages + +It’s recommended to break a workflow into multiple **jobs** and **steps**, assigning specific responsibilities to each job, such as testing, building, or deploying. Each job can run in parallel or as a dependency, providing greater flexibility. + +#### Structured Workflow Example + +```yaml +name: Complex Workflow + +on: + push: + branches: + - main + +jobs: + lint: + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v2 + + - name: Run linter + run: npm run lint + + test: + runs-on: ubuntu-latest + needs: lint # The 'test' job depends on 'lint' + steps: + - name: Checkout code + uses: actions/checkout@v2 + + - name: Run unit tests + run: npm test + + build: + runs-on: ubuntu-latest + needs: test # The 'build' job depends on 'test' + steps: + - name: Build application + run: npm run build + + deploy: + runs-on: ubuntu-latest + needs: build # The 'deploy' job depends on 'build' + steps: + - name: Deploy to production + run: ./deploy.sh +``` + +#### Explanation: +- **Dependent Jobs**: The `test`, `build`, and `deploy` jobs depend on previous jobs, ensuring no deployment occurs before validation through tests or builds. +- **Modularity**: Each job has a defined role, making the workflow more readable and maintainable. + +### 1.2. Workflow Modularization + +GitHub Actions allows calling one workflow from another using `workflow_call`. Modularizing workflows enables you to reuse parts of the pipeline (tests, builds, etc.) across different projects, ensuring consistency in CI/CD management across the organization. + +#### Example of a Reusable Workflow + +```yaml +# .github/workflows/tests.yml +name: Reusable Tests Workflow + +on: workflow_call + +jobs: + run-tests: + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v2 + + - name: Install dependencies + run: npm install + + - name: Run tests + run: npm test +``` + +```yaml +# .github/workflows/main.yml +name: Main Workflow + +on: + push: + branches: + - main + +jobs: + tests: + uses: ./.github/workflows/tests.yml # Reuse the test workflow +``` + +### 1.3. Use Matrices to Optimize Runs + +Using **matrices** allows testing across various combinations of environments (OS, language versions, etc.) in parallel, reducing the total pipeline runtime. + +#### Matrix Example + +```yaml +name: Matrix Build + +on: + push: + branches: + - main + +jobs: + build: + runs-on: ubuntu-latest + strategy: + matrix: + os: [ubuntu-latest, macos-latest, windows-latest] + node-version: [12, 14, 16] + + steps: + - name: Checkout repository + uses: actions/checkout@v2 + + - name: Setup Node.js + uses: actions/setup-node@v2 + with: + node-version: ${{ matrix.node-version }} + + - name: Install dependencies + run: npm install + + - name: Run tests + run: npm test +``` + +--- + +## 2. Using Centralized Configuration Files + +For complex projects, centralizing workflow configuration can ensure consistency across different pipelines and reduce duplication. + +### 2.1. Centralize Secrets and Variables + +GitHub allows managing **secrets** and **environment variables** at the organization or repository level. This lets you store sensitive information like API keys or credentials in a centralized and secure location. + +#### Example: Using Secrets in a Workflow + +```yaml +jobs: + deploy: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v2 + + - name: Deploy to AWS + env: + AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }} + AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }} + run: ./deploy.sh +``` + +### 2.2. Shared Configuration Files + +GitHub Actions allows creating shared YAML configuration files, enabling standardized CI/CD processes across multiple projects. These files can include common scripts or reusable workflows for different teams or repositories. + +#### Example: Using a Central Configuration File + +```yaml +# .github/workflows/shared-config.yml +name: Shared Config + +on: + workflow_call + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Install dependencies + run: npm install +``` + +--- + +## 3. Team Collaboration in Software Development with GitHub Actions (PR Gating, Checks) + +GitHub Actions streamlines team collaboration by automating checks and integrating pull request (PR) gating controls. + +### 3.1. Implementing PR Gating + +**PR gating** prevents code from merging into a branch without successfully passing specified tests or checks. You can configure **required checks** that must pass before merging a pull request. + +#### Example: Workflow to Validate a PR + +```yaml +name: PR Validation + +on: + pull_request: + branches: + - main + +jobs: + test: + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v2 + + - name: Install dependencies + run: npm install + + - name: Run tests + run: npm test +``` + +### 3.2. Automatic Checks on Pull Requests + +GitHub enables automatic **checks** on pull requests, such as running tests or checking code style. + +### 3.3. Protected Branch Policy + +It’s recommended to protect critical branches (like `main` or `production`) by configuring **protected branches**, which prevent direct commits or require specific workflows to complete before merging. + +#### Example: Protecting the `main` Branch + +1. Go to **Settings** in the repository. +2. Navigate to **Branches**. +3. Add a branch rule for `main`. +4. Check **Require status checks to pass before merging**. + +--- + +## Conclusion + +Applying best practices and DevOps patterns with GitHub Actions allows you to effectively structure CI/CD workflows, centralize configurations and secrets, manage multiple environments, and collaborate seamlessly within a team. Using tools such as environments, reusable workflows, protected branches, and pull request checks enables building robust and scalable pipelines for complex projects, while ensuring code quality and security. \ No newline at end of file diff --git a/wiki/docs/en/onboarding/hands-on-labs/learn-github-actions/registry.md b/wiki/docs/en/onboarding/hands-on-labs/learn-github-actions/registry.md new file mode 100644 index 0000000..6181d1c --- /dev/null +++ b/wiki/docs/en/onboarding/hands-on-labs/learn-github-actions/registry.md @@ -0,0 +1,229 @@ +# Using GitHub Container Registry (GHCR) + +GitHub Container Registry (GHCR) is a feature of GitHub Packages that enables you to store and manage Docker container images alongside your GitHub projects. GHCR integrates seamlessly with CI/CD workflows via GitHub Actions, simplifying the creation, storage, and deployment of Docker images in your projects. + +--- + +## 1. Introduction to GitHub Container Registry + +GitHub Container Registry (GHCR) is an integrated container registry service in GitHub, allowing developers to manage Docker container images directly within their GitHub repositories. GHCR is designed to provide flexible permission management, image visibility, and integration with GitHub Actions workflows. + +### Example: Cedille’s Container Registry + +For a real-world example of GHCR usage, check out the [Cedille container registry](https://github.com/orgs/ClubCedille/packages). This registry hosts container images that the club uses for its projects, integrated with CI/CD workflows and managed directly through GitHub Actions. + +### Key Features of GHCR + +- **Centralized Storage**: GHCR allows you to store Docker images alongside your project’s source code, simplifying versioning and deployments. +- **Flexible Permissions**: Images can be private, public, or have custom permissions managed for users and teams. +- **Integration with GitHub Actions**: GHCR integrates directly with GitHub Actions CI/CD workflows, allowing automated Docker image creation and deployment. +- **Support for Docker and OCI**: GHCR supports Docker and Open Container Initiative (OCI) compliant images. + +--- + +Here’s how you can integrate this example into your Dockerized projects in the section **Pushing and Pulling Container Images to GitHub Container Registry**: + +## 2. Pushing and Pulling Container Images in GitHub Container Registry + +GitHub Container Registry allows users to **push** (upload) and **pull** (download) Docker images from their GitHub projects, similar to other Docker registries such as Docker Hub. + +### Example: Workflow to Build and Push a Docker Image to GHCR + +In Cedille’s projects, workflows are used to automate the build and publish process of Docker images to GHCR. Below is an example of the [build-push-ghcr.yaml](https://github.com/ClubCedille/cedille-workflows/blob/master/.github/workflows/build-push-ghcr.yaml) file used to build and push Docker containers. + +### Workflow Explanation for [build-push-ghcr.yaml](https://github.com/ClubCedille/cedille-workflows/blob/master/.github/workflows/build-push-ghcr.yaml): +- **workflow_call**: This workflow is designed to be reusable by other workflows, allowing container name, Docker context, and Dockerfile specification. +- **Docker Buildx**: Used for building multi-platform images (e.g., amd64, arm64). +- **Docker Layer Caching**: Docker layers are cached to speed up builds. +- **Pushing Docker Images**: Images are pushed to the GitHub registry (GHCR) with tags based on the commit or PR branch, and a `latest` tag is added if the push is on the `main` or `master` branch. + +This example shows how Cedille uses GHCR to manage Docker images with automated, robust CI/CD workflows. + +### 2.1. Authenticating to GitHub Container Registry + +To interact with GHCR, you need to authenticate to GitHub using a personal access token (PAT) with the following permissions: +- `read:packages` +- `write:packages` +- `delete:packages` (if you wish to delete images) +- `repo` (if pushing images to private repositories) + +#### Creating a Personal Access Token (PAT) + +1. Go to your **GitHub Settings**. +2. Under **Developer settings**, click **Personal access tokens**. +3. Create a new token with the permissions mentioned above. + +### 2.2. Pushing a Docker Image to GitHub Container Registry + +To push a Docker image to GHCR, follow these steps: + +#### 1. Logging In to GitHub Container Registry + +Use the following Docker command to authenticate with GHCR using your personal access token (PAT): + +```bash +echo $GHCR_PAT | docker login ghcr.io -u --password-stdin +``` + +- **`$GHCR_PAT`** is your personal access token (PAT). +- **``** is your GitHub username. + +#### 2. Building a Docker Image + +Build a Docker image from your project. For example, if you have a `Dockerfile` in the root directory of your project: + +```bash +docker build -t ghcr.io//: . +``` + +- **``**: Your GitHub username. +- **``**: The name of the Docker image. +- **``**: A tag to identify the image version (e.g., `v1.0`, `latest`). + +#### 3. Pushing the Docker Image to GHCR + +Once the image is built, push it to GHCR using the following command: + +```bash +docker push ghcr.io//: +``` + +### 2.3. Pulling a Docker Image from GitHub Container Registry + +To pull a Docker image stored in GHCR, authenticate first, then run the pull command. + +#### 1. Authentication + +If you aren’t already logged in to GHCR, authenticate as follows: + +```bash +echo $GHCR_PAT | docker login ghcr.io -u --password-stdin +``` + +#### 2. Pull the Docker Image + +Use the `docker pull` command to download an image from GHCR: + +```bash +docker pull ghcr.io//: +``` + +--- + +## 3. Integrating Images with GitHub Actions Workflows + +GitHub Actions integrates seamlessly with GitHub Container Registry, enabling you to create CI/CD workflows that include automated Docker image build, test, and deployment. + +### Example Workflow to Build and Push a Docker Image to GHCR + +Below is a sample GitHub Actions workflow that builds a Docker image from a repository and automatically pushes it to GHCR. + +```yaml +name: Build and Push Docker Image to GHCR + +on: + push: + branches: + - main + +jobs: + build: + runs-on: ubuntu-latest + + steps: + # Step 1: Checkout repository + - name: Checkout repository + uses: actions/checkout@v2 + + # Step 2: Authenticate to GHCR + - name: Log in to GitHub Container Registry + run: echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u ${{ github.actor }} --password-stdin + + # Step 3: Build Docker image + - name: Build Docker image + run: docker build -t ghcr.io/${{ github.repository }}/my-app:latest . + + # Step 4: Push image to GHCR + - name: Push Docker image to GHCR + run: docker push ghcr.io/${{ github.repository }}/my-app:latest +``` + +### Explanation of Steps: + +1. **Checkout repository**: This step retrieves the repository’s source code. +2. **Log in to GitHub Container Registry**: Logs into GHCR using GitHub’s access token (`GITHUB_TOKEN`). +3. **Build Docker image**: Builds a Docker image from the Dockerfile in the project’s root directory. +4. **Push Docker image to GHCR**: Pushes the built Docker image to GHCR using the path `ghcr.io//`. + +### Workflow Example to Pull an Image and Deploy with Docker + +The following GitHub Actions workflow pulls a Docker image from GHCR and deploys it to a target machine (e.g., a production server). + +```yaml +name: Pull and Deploy Docker Image from GHCR + +on: + workflow_dispatch: + +jobs: + deploy: + runs-on: ubuntu-latest + + steps: + # Authenticate to GHCR + - name: Log in to GitHub Container Registry + run: echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u ${{ github.actor }} --password-stdin + + # Pull the Docker image + - name: Pull Docker image from GHCR + run: docker pull ghcr.io/${{ github.repository }}/my-app:latest + + # Run the Docker container + - name: Run Docker container + run: docker run -d -p 8080:80 ghcr.io/${{ github.repository }}/my-app:latest +``` + +--- + +## 4. Access Control and Permissions on Registries + +One of GHCR’s significant advantages is fine-grained **access control**. You can manage who has access to your container images and define specific permissions for each image or repository. + +### 4.1 Repository Permissions + +Access permissions for images hosted in GHCR depend on the access permissions for the associated repository: +- **Public Repositories**: Images in public repositories can be viewed and pulled by any GitHub user. +- **Private Repositories**: Images in private repositories are accessible only to people or teams with appropriate repository permissions. + +### 4.2 Permissions for Public and Private Images + +You can set specific permissions for GHCR images, independent of the repository they’re hosted in. Images can be: +- **Private**: Only users or teams granted access can pull or push images. +- **Public**: Anyone can pull the image. + +#### Make an Image Public or Private + +1. Go to the **Packages** page of your GitHub repository. +2. Select the Docker image you want to modify. +3. Click **Package settings**. +4. Change the image’s visibility to **Public** or **Private + +**. + +### 4.3 Managing Permissions for Users and Teams + +You can grant read or write permissions on your images to specific users or teams within your GitHub organization. This allows you to restrict access to sensitive images while facilitating team collaboration. + +#### Grant Access to a User or Team + +1. Go to the **Settings** of the GitHub repository containing the image. +2. Under **Manage access**, add the users or teams to whom you wish to grant access. +3. Assign specific roles (read, write, or admin) based on the desired access level. + +--- + +## Conclusion + +GitHub Container Registry (GHCR) is a powerful and flexible solution for managing your Docker images directly within GitHub. By enabling you to push, pull, and deploy container images in your CI/CD workflows via GitHub Actions, GHCR integrates seamlessly into modern development pipelines. With its advanced access control options, you can manage permissions granularity to ensure the security of your images. + +With these tools, you’re now ready to use GHCR to optimize your CI/CD workflows, enhance collaboration, and simplify Docker image management. \ No newline at end of file diff --git a/wiki/docs/en/onboarding/hands-on-labs/learn-github-actions/security.md b/wiki/docs/en/onboarding/hands-on-labs/learn-github-actions/security.md new file mode 100644 index 0000000..3ac32c2 --- /dev/null +++ b/wiki/docs/en/onboarding/hands-on-labs/learn-github-actions/security.md @@ -0,0 +1,239 @@ +# Security and Permissions Management in GitHub Actions + +Security is a crucial component of any CI/CD pipeline. GitHub Actions offers built-in features for managing sensitive information, controlling workflow access, and ensuring software dependency security. This document explores how to use GitHub Secrets for managing sensitive data, define permissions on workflows, and analyze dependencies with Dependabot. + +--- + +## 1. Using GitHub Secrets to Manage Sensitive Information + +Secrets in GitHub are used to store sensitive information such as API keys, passwords, or access tokens, which are required for workflows but should not be exposed in the source code. + +### 1.1. What are GitHub Secrets? + +**GitHub Secrets** are secure, encrypted variables stored by GitHub. They can be used in workflows to pass sensitive information without exposing it in logs or configuration files. For example, secrets are commonly used to authenticate with third-party services such as AWS, Docker, or Slack. + +### 1.2. Creating a Secret in GitHub + +1. **Go to Settings** in the repository or organization. +2. Under **Secrets and variables**, click **Actions**. +3. Select **New repository secret** (for a repository) or **New organization secret** (to share across multiple repositories). +4. Enter a name for the secret (e.g., `AWS_ACCESS_KEY_ID`). +5. Enter the secret's value, then click **Add secret**. + +### 1.3. Using Secrets in a GitHub Actions Workflow + +Once created, secrets can be used in workflows by referencing them with `${{ secrets.SECRET_NAME }}`. + +#### Example: Using Secrets for AWS Authentication + +```yaml +name: Deploy to AWS + +on: + push: + branches: + - main + +jobs: + deploy: + runs-on: ubuntu-latest + + steps: + # Checkout source code + - name: Checkout repository + uses: actions/checkout@v2 + + # Configure AWS credentials using secrets + - name: Configure AWS credentials + uses: aws-actions/configure-aws-credentials@v1 + with: + aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }} + aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }} + aws-region: us-east-1 + + # Deploy to AWS + - name: Deploy to S3 + run: aws s3 sync ./build s3://my-app-bucket +``` + +### 1.4. Best Practices for Using Secrets + +- **Limit Access to Secrets**: Only users who need to view or manage secrets should have access. +- **Use Organization-Level Secrets**: For multi-repo workflows, define organization-level secrets to share securely across repositories. +- **Encrypt Secrets**: Never include sensitive information directly in code or workflows; always use encrypted secrets. +- **Rotate Secrets Regularly**: Update secrets periodically to enhance security. + +--- + +## 2. Workflow Permissions and Access Control + +Security in GitHub Actions workflows also relies on **access permissions** and **execution rights** management. GitHub allows you to control the actions a workflow can perform and restrict access to certain events and users. + +### 2.1. Workflow Permissions + +GitHub allows configuration of default **permissions** that a workflow can use. Permissions can be set globally for the entire repository or per workflow. + +#### Configuring Workflow Permissions + +Permissions can be set at two levels: +1. **Global (for the entire repository)**. +2. **Specific to a workflow**. + +#### 2.1.1. Global Permissions for a Repository + +Set default permissions for a repository under **Settings > Actions > Workflow permissions**. The main options are: +- **Read repository content**: Restricts actions to read-only access (most secure option). +- **Read and write permissions**: Allows actions to read and modify the repository. + +#### 2.1.2. Permissions in a Specific Workflow + +Within a specific workflow, you can restrict permissions at the **job** or **step** level. + +##### Example: Defining Permissions in a Workflow + +```yaml +name: Build and Deploy + +on: + push: + branches: + - main + +permissions: + contents: read # Restrict repository access to read-only + packages: write # Allow write access to GitHub Packages + +jobs: + build: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v2 +``` + +In this example: +- The workflow has **read-only** permission for repository contents. +- The workflow has **write** permission to GitHub Packages for publishing artifacts or Docker images. + +### 2.2. Workflow Access Control + +Workflow permissions can also be controlled by organization or repository owners. Here are some best practices for securing workflows: + +- **Require Approvals for Certain Workflows**: For critical events (like a production deployment), configure workflows to require manual approval before execution. + +#### Example: Requiring Manual Approval for Deployment + +```yaml +name: Production Deployment + +on: + workflow_dispatch: + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - name: Await approval + uses: actions/manual-approval@v2 + with: + approver: "team-lead" + - name: Deploy application + run: ./deploy.sh +``` + +- **Limit Access to Secrets**: Only grant access to workflows and jobs that genuinely require it. +- **Use Protected Branches**: Restrict automatic workflows on production branches to prevent unauthorized changes. + +--- + +## 3. Dependency Security Scanning with Dependabot and Renovate + +Dependabot is a GitHub service that scans your project dependencies and identifies security vulnerabilities. It provides automatic updates to fix these vulnerabilities, enhancing the overall security of your applications. + +In our repositories, however, we primarily use **Renovate**, an open-source dependency management tool. Like Dependabot, Renovate scans dependencies and provides automated updates. However, **Renovate** offers more advanced configuration options, including update frequency, versioning strategies, and support for a wide range of languages and package managers. + +### Why Use Renovate? +- **Advanced Configuration**: Renovate enables detailed customization of update strategies, such as grouped updates, specific version ranges, and custom update schedules. +- **Extended Support**: It supports a wide range of package managers, making it ideal for multi-technology projects. +- **Easy Integration**: Like Dependabot, Renovate integrates directly with GitHub workflows and generates automated pull requests with dependency updates. + +### Example Renovate Configuration File + +In our projects, here’s a basic Renovate configuration example: + +```json +{ + "extends": [ + "config:base" + ], + "packageRules": [ + { + "matchPackagePatterns": ["*"], + "groupName": "All Dependencies", + "groupSlug": "all-dependencies" + } + ], + "schedule": ["every weekend"] +} +``` + +In this example: +- **extends**: Uses Renovate's base configuration. +- **packageRules**: Groups all dependencies in a single update batch. +- **schedule**: Updates are scheduled to run every weekend. + +Renovate and Dependabot are both powerful tools for maintaining secure and up-to-date dependencies in your projects, but Renovate is often preferred for its flexibility and advanced configuration capabilities, as we do in our repositories. + +### 3.1. What is Dependabot? + +**Dependabot** regularly scans your project dependencies and detects known vulnerabilities in the libraries you use. When a vulnerability is found, Dependabot automatically creates a **pull request** suggesting an update to a more secure version. + +### 3.2. Enabling Dependabot for Security Scanning + +1. Go to your GitHub repository’s **Settings**. +2. Under **Security & Analysis**, enable **Dependabot alerts** and **Dependabot security updates**. + +GitHub then automatically scans your project dependencies and notifies you if vulnerabilities are detected. + +### 3.3. Automatic Updates with Dependabot + +Dependabot can automatically generate pull requests to update your dependencies when security updates are available. These pull requests can then be reviewed and merged to ensure that your project remains secure. + +#### Example: Dependabot Configuration File + +Dependabot can be configured via a `.github/dependabot.yml` file, defining which dependencies to monitor and the update frequency. + +```yaml +version: 2 +updates: + - package-ecosystem: "npm" # Manage npm dependencies + directory: "/" # Directory with the package.json file + schedule: + interval: "daily" # Check for updates every day + - package-ecosystem: "docker" # Manage Docker images + directory: "/" # Directory with the Dockerfile + schedule: + interval: "weekly" # Check for updates weekly +``` + +### 3.4. Vulnerability Scanning in Code and Dependencies + +Dependabot connects to a database of known vulnerabilities to check the packages used in your projects. When a vulnerability is found: +- You receive a **Dependabot alert** in your repository’s **Security** tab. +- Dependabot can automatically create a **pull request** suggesting an update to a non-vulnerable version. + +### 3.5. Tracking Security Updates + +Dependabot enables you to: +- Track the history of vulnerabilities and patches. +- Implement automatic updates so your project always uses secure dependency versions. + +--- + +## Conclusion + +Security and permissions management in GitHub Actions is essential for maintaining the confidentiality, integrity, and security of your CI/CD pipelines. By using GitHub Secrets, you can safeguard sensitive information such as API keys and credentials. Configuring workflow and secret access permissions helps reduce the risk of compromise. Additionally, Dependabot offers a powerful tool for monitoring and automatically addressing vulnerabilities in your dependencies, further enhancing the overall security of your projects. + +These tools and practices allow you to build robust and secure workflows, adhering to best practices for security and permissions management. + diff --git a/wiki/docs/en/onboarding/hands-on-labs/learn-github-actions/use-case.md b/wiki/docs/en/onboarding/hands-on-labs/learn-github-actions/use-case.md new file mode 100644 index 0000000..c2278e3 --- /dev/null +++ b/wiki/docs/en/onboarding/hands-on-labs/learn-github-actions/use-case.md @@ -0,0 +1,331 @@ +# Practical Use Cases: DevOps with GitHub Actions + +GitHub Actions is a powerful tool for implementing CI/CD pipelines in a DevOps environment. It enables automation throughout the development lifecycle, including builds, tests, deployments, and integration with cloud services and Docker containers. This guide presents detailed use cases for implementing robust CI/CD pipelines using GitHub Actions, Docker, and AWS. + +--- + +## 1. Deploying a Node.js Application with Docker and GitHub Actions + +In this example, we’ll see how to automate the deployment of a Dockerized Node.js application using Docker and GitHub Actions. + +### 1.1. Preparing the Dockerfile + +Start by creating a `Dockerfile` to containerize the Node.js application. + +#### Sample Dockerfile: + +```dockerfile +# Use a Node.js base image +FROM node:14 + +# Create a working directory in the container +WORKDIR /app + +# Copy package.json and install dependencies +COPY package*.json ./ +RUN npm install + +# Copy the remaining application files +COPY . . + +# Expose the application port +EXPOSE 3000 + +# Start the application +CMD ["npm", "start"] +``` + +### 1.2. Creating a GitHub Actions Workflow for Build and Deployment + +Next, configure GitHub Actions to automate building and deploying this application to a server or Docker service. The following workflow builds the Docker image and pushes it to **GitHub Container Registry** (GHCR). + +#### Sample Workflow: Build and Push Docker Image + +```yaml +name: Build and Deploy Node.js Docker App + +on: + push: + branches: + - main # Trigger workflow on pushes to the 'main' branch + +jobs: + build: + runs-on: ubuntu-latest + + steps: + # Step 1: Checkout the source code + - name: Checkout code + uses: actions/checkout@v2 + + # Step 2: Authenticate with GitHub Container Registry (GHCR) + - name: Log in to GitHub Container Registry + run: echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u ${{ github.actor }} --password-stdin + + # Step 3: Build the Docker image + - name: Build Docker image + run: docker build -t ghcr.io/${{ github.repository }}/node-app:latest . + + # Step 4: Push the image to GHCR + - name: Push Docker image to GitHub Container Registry + run: docker push ghcr.io/${{ github.repository }}/node-app:latest +``` + +### 1.3. Deploying the Application + +Now, you can deploy the Docker image to a production server or a service like **Docker Swarm**, **Kubernetes**, or **AWS ECS**. + +--- + +## 2. CI/CD for a Python Application Hosted on AWS with Docker Integration + +This example demonstrates setting up a CI/CD pipeline for a Dockerized Python application hosted on **AWS Elastic Beanstalk** with Docker integration. + +### 2.1. Preparing the Dockerfile for the Python Application + +Create a `Dockerfile` to containerize the Python application. This example demonstrates a Dockerfile for a Flask app. + +#### Sample Dockerfile: + +```dockerfile +# Use a Python base image +FROM python:3.9 + +# Set the working directory +WORKDIR /app + +# Copy requirements.txt and install dependencies +COPY requirements.txt . +RUN pip install -r requirements.txt + +# Copy the rest of the source code +COPY . . + +# Expose the application port +EXPOSE 5000 + +# Start the Flask app +CMD ["python", "app.py"] +``` + +### 2.2. Configuring a GitHub Actions Workflow for AWS Elastic Beanstalk + +The following workflow is designed to build the Docker image and automatically deploy it to AWS Elastic Beanstalk. + +#### Sample Workflow: Build and Deploy on AWS Elastic Beanstalk + +```yaml +name: Build and Deploy to AWS Elastic Beanstalk + +on: + push: + branches: + - main + +jobs: + deploy: + runs-on: ubuntu-latest + + steps: + # Step 1: Checkout the source code + - name: Checkout code + uses: actions/checkout@v2 + + # Step 2: AWS Authentication + - name: Configure AWS credentials + uses: aws-actions/configure-aws-credentials@v1 + with: + aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }} + aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }} + aws-region: us-east-1 + + # Step 3: Build the Docker image + - name: Build Docker image + run: docker build -t my-python-app:latest . + + # Step 4: Deploy the application to Elastic Beanstalk + - name: Deploy to Elastic Beanstalk + run: | + zip -r app.zip . + aws elasticbeanstalk create-application-version --application-name MyPythonApp --version-label latest --source-bundle S3Bucket=my-app-bucket,S3Key=app.zip + aws elasticbeanstalk update-environment --environment-name MyPythonApp-env --version-label latest +``` + +--- + +## 3. Automating a Complete DevOps Pipeline: Testing, Building, Deploying + +This example demonstrates setting up a full DevOps pipeline, including automated testing, building, and deploying an application. + +### 3.1. Comprehensive Workflow with Unit Tests, Build, and Deployment + +The following workflow automates the entire process of testing, building, and deploying a Node.js application hosted on **Heroku**. + +#### Sample Comprehensive Workflow: + +```yaml +name: CI/CD Pipeline for Node.js App + +on: + push: + branches: + - main + +jobs: + test: + runs-on: ubuntu-latest + + steps: + # Step 1: Checkout the source code + - name: Checkout code + uses: actions/checkout@v2 + + # Step 2: Install dependencies + - name: Install dependencies + run: npm install + + # Step 3: Run unit tests + - name: Run unit tests + run: npm test + + build: + runs-on: ubuntu-latest + needs: test # Executes after the 'test' job + + steps: + # Step 1: Checkout the source code + - name: Checkout code + uses: actions/checkout@v2 + + # Step 2: Build the application + - name: Build application + run: npm run build + + deploy: + runs-on: ubuntu-latest + needs: build # Executes after the 'build' job + + steps: + # Step 1: Checkout the source code + - name: Checkout code + uses: actions/checkout@v2 + + # Step 2: Authenticate with Heroku + - name: Login to Heroku + run: echo "${{ secrets.HEROKU_API_KEY }}" | docker login --username=_ --password-stdin registry.heroku.com + + # Step 3: Deploy the image to Heroku + - name: Deploy to Heroku + run: | + docker build -t registry.heroku.com/my-app/web . + docker push registry.heroku.com/my-app/web + heroku container:release web --app my-app +``` + +#### Explanation: +- **Tests**: Runs unit tests using `npm test`. +- **Build**: If the tests pass, the application is built with `npm run build`. +- **Deployment**: If the build is successful, the application is deployed to Heroku using Docker images. + +### 3.2. Success or Failure Notification + +You can add Slack notifications to alert the team about CI/CD pipeline success or failure. + +#### Example: Slack Notification after Build + +```yaml +name: CI/CD Pipeline with Slack Notifications + +on: + push: + branches: + - main + +jobs: + build-and-deploy: + runs-on: ubuntu-latest + + steps: + # Step 1: Checkout the source code + - name: Checkout code + uses: actions/checkout@v2 + + # Step 2: Install dependencies + - name: Install dependencies + run: npm install + + # Step 3: Build the application + - name: Build application + run: npm run build + + # Step 4: Deploy the application + - name: Deploy application + run: ./deploy.sh + + notify: + runs-on: ubuntu-latest + needs: build-and-deploy + + steps: + - name: Send Slack notification on success + if: success() + run: | + curl -X POST -H 'Content-type: application/json' \ + --data '{"text":"Build succeeded for ${{ github.repository }}!"}' \ + ${{ secrets.SLACK_WEBHOOK_URL }} + + - name: Send Slack notification on failure + if: failure() + run: | + curl -X POST -H 'Content-type: application/json' \ + --data '{"text":"Build failed for ${{ github.repository }}!"}' \ + ${{ secrets.SLACK_WEBHOOK_URL }} +``` + +--- + +## 4. Collaboration with Teams: GitHub Organizations and Teams + +In a DevOps environment, effective collaboration within teams and organizations on GitHub is essential. + +### 4.1. Managing GitHub Teams + +GitHub allows managing teams within an organization, enabling: +- **Permission Management**: Assign specific access roles (read, write, admin) to different members or teams. +- **Shared Secrets**: Organization-wide secrets can be used across repositories, facilitating shared authentication for external services (like AWS, Docker, etc.). + +### 4.2. Shared Workflow Across Multiple Repositories + +You can create reusable workflows at the organizational level to share across + + multiple repositories. + +#### Example: Reusable Workflow for Builds + +```yaml +name: Reusable Build Workflow + +on: workflow_call + +jobs: + build: + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v2 + + - name: Install dependencies + run: npm install + + - name: Build application + run: npm run build +``` + +In each repository, you can then call this reusable workflow to standardize the build process across the organization. + +--- + +## Conclusion + +These practical use cases demonstrate how GitHub Actions can be used to automate the full DevOps lifecycle. Whether working with Node.js, Python, Docker, or AWS, GitHub Actions enables building robust, automated, and scalable CI/CD pipelines. By integrating tests, builds, notifications, and team collaboration through GitHub organizations, you can easily manage and optimize your DevOps processes while ensuring smooth team collaboration across the organization. \ No newline at end of file diff --git a/wiki/docs/en/onboarding/hands-on-labs/learn-github-actions/workflows.md b/wiki/docs/en/onboarding/hands-on-labs/learn-github-actions/workflows.md new file mode 100644 index 0000000..5e78910 --- /dev/null +++ b/wiki/docs/en/onboarding/hands-on-labs/learn-github-actions/workflows.md @@ -0,0 +1,329 @@ +# Creating Custom Workflows with GitHub Actions + +GitHub Actions allows you to create custom workflows tailored to your specific CI/CD needs. Workflows are defined in YAML files and can automate a wide range of tasks, from code testing to production deployment. + +--- + +## 1. Defining Jobs and Steps + +A GitHub Actions workflow is composed of multiple **jobs**, and each **job** contains a series of **steps**. A job is a set of tasks running on a given machine, while each step represents a command or specific action within that job. + +### Job Structure + +A **job** must define: +- The environment in which it runs (`runs-on`). +- The **steps** to be executed. +- Optionally, dependencies between jobs or execution conditions. + +### Example: Defining Jobs and Steps + +```yaml +name: Custom Workflow + +on: [push] + +jobs: + build: + runs-on: ubuntu-latest # Defines the environment (an Ubuntu machine) + + steps: + - name: Checkout code # Step 1: Retrieve the source code from the repository + uses: actions/checkout@v2 + + - name: Install dependencies # Step 2: Install dependencies + run: npm install + + - name: Run tests # Step 3: Run tests + run: npm test + + deploy: + runs-on: ubuntu-latest + + steps: + - name: Deploy application + run: ./deploy.sh +``` + +### Details: +- **`jobs:`** : The `jobs` section contains all jobs in the workflow. Each job is defined with a unique identifier (`build` and `deploy` here). +- **`runs-on:`** : Specifies the environment for the job (e.g., `ubuntu-latest`). +- **`steps:`** : Each job contains one or more steps, which can execute shell commands (`run`) or use existing actions (`uses`). + +--- + +## 2. Using Pre-Built Actions from GitHub Marketplace + +GitHub Actions has a **Marketplace** where you can find and use community-built actions. These actions can be easily integrated into your workflows to handle common tasks like checking code, setting up environments, or deploying applications. + +### How to Use Actions from the Marketplace + +To use an action from the Marketplace, add it to your `steps` using the following syntax: +```yaml +uses: @ +``` +Here’s an example using the `actions/checkout` action to retrieve a repository’s source code. + +#### Example: + +```yaml +steps: + - name: Checkout code + uses: actions/checkout@v2 # Uses the action to clone the repository +``` + +The `actions/checkout` action is commonly used to clone the repository onto the machine where jobs are executed. You can find hundreds of other actions on the [GitHub Marketplace](https://github.com/marketplace?type=actions), such as: +- **`actions/setup-node`** : Sets up a Node.js environment. +- **`actions/upload-artifact`** : Saves files or test results. + +### Complete Example: + +```yaml +jobs: + build: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v2 + + - name: Set up Node.js + uses: actions/setup-node@v2 + with: + node-version: '14' + + - name: Install dependencies + run: npm install +``` + +--- + +## 3. Creating and Using Your Own Custom Actions + +Besides using pre-built actions, GitHub Actions allows you to **create your own custom actions** to meet specific needs. These actions can be written in JavaScript or defined in Docker containers for more complex environments. For a practical example, see the repository [Cedille-Actions-By-Example](https://github.com/ClubCedille/cedille-actions-by-example), which presents various custom actions, including **KubeSketcher**, which generates Kubernetes namespace architecture diagrams from manifests, and **WorkflowWikiExample**, designed to illustrate creating and using a custom action. + +Here’s the process followed to create the **cedille-actions-by-example/WorkflowWikiExample** action: + +```markdown +### Types of Custom Actions + +1. **JavaScript Actions**: Actions written in JavaScript that run directly in the runner environment. +2. **Docker Actions**: Actions encapsulated in a Docker container, allowing for a more complex runtime environment. + +### Creating a Simple Custom JavaScript Action + +1. **Create a `WorkflowWikiExample` directory in your repository**. +2. **Create an `index.js` file** with the JavaScript code for your action: + +```js +// index.js +const core = require('@actions/core'); +const github = require('@actions/github'); + +try { + const message = core.getInput('message'); + console.log(`Message: ${message}`); +} catch (error) { + core.setFailed(error.message); +} +``` + +3. **Create an `action.yml` file** to describe the action: + +```yaml +name: 'Print Message' +description: 'Prints a message to the console' +inputs: + message: + description: 'The message to print' + required: true +runs: + using: 'node20' + main: 'index.js' +``` + +### Using the Custom Action + +Once created, you can use your custom action in workflows just like any other action. + +```yaml +name: Custom Action Workflow + +on: [push] + +jobs: + custom-action-job: + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v2 + + - name: Run custom action + uses: ClubCedille/Cedille-Actions-By-Example/WorkflowWikiExample@master + with: + message: "Hello from the custom action!" +``` + +### Docker Actions + +If your action requires a specific environment, you can create a Docker action, allowing you to run scripts in an isolated container. + +#### Docker Action Example: +1. Create a `Dockerfile`: + +```dockerfile +FROM node:14 +COPY . /app +WORKDIR /app +RUN npm install +CMD ["node", "index.js"] +``` + +2. Create the action YAML for Docker: + +```yaml +name: 'Custom Docker Action' +runs: + using: 'docker' + image: 'Dockerfile' +``` + +--- + +## 4. Secrets and Environment Variables + +**Secrets** and **environment variables** allow you to secure sensitive information and pass dynamic parameters to your workflows. + +### Using Secrets + +Secrets store sensitive information like API keys or credentials that you don’t want exposed in your code. You can add secrets to your repository via GitHub’s interface and reference them in your workflows. + +#### Adding a Secret: +1. Go to the **Settings** of your repository. +2. Click **Secrets and variables** > **Actions**. +3. Add a new secret (e.g., `API_KEY`). + +#### Using a Secret in a Workflow: + +```yaml +jobs: + build: + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v2 + + - name: Use secret API key + run: echo "Your API key is ${{ secrets.API_KEY }}" +``` + +### Using Environment Variables + +Environment variables can also be defined and used within jobs or steps. + +#### Example: Environment Variables: + +```yaml +jobs: + build: + runs-on: ubuntu-latest + + env: + NODE_ENV: production + API_URL: https://api.example.com + + steps: + - name: Print environment variables + run: echo "Environment: $NODE_ENV, API: $API_URL" +``` + +--- + +## 5. Parallel and Conditional Execution + +### Parallel Execution + +By default, jobs in a GitHub Actions workflow run **in parallel**. This allows multiple jobs to execute simultaneously, reducing total workflow time. + +#### Parallel Execution Example: + +```yaml +jobs: + build-frontend: + runs-on: ubuntu-latest + steps: + - name: Build frontend + run: npm run build-frontend + + build-backend: + runs-on: ubuntu-latest + steps: + - name: Build backend + run: npm run build-backend +``` +In this example, the `build-frontend` and `build-backend` jobs will run in parallel. + +### Conditional Execution + +You can define conditions to control when jobs or steps are run, such as running specific actions only if a test fails or if the branch matches a certain condition. + +#### Conditional Execution with `if`: + +```yaml +jobs: + deploy: + runs-on: ubuntu-latest + + if: github.ref =='refs/heads/main' # Run only if on 'main' branch + + steps: + - name: Deploy to production + run: ./deploy.sh +``` + +### Passing Information from One Job to Another + +It’s possible to pass information between jobs in a GitHub Actions workflow by defining **outputs** in one job and using those outputs in a following job. This allows you to reuse data computed or retrieved in one job for use in another. + +#### Example: Define and Use Outputs in Jobs + +In this example, the `build` job generates a version number and passes it to the `deploy` job. + +```yaml +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v2 + + - name: Generate version number + id: version_step + run: echo "::set-output name=version::1.0.$(date +%s)" + + deploy: + runs-on: ubuntu-latest + needs: build + steps: + - name: Checkout repository + uses: actions/checkout@v2 + + + + - name: Deploy application + run: echo "Deploying version ${{ needs.build.outputs.version }}" +``` + +#### Explanation: + +1. **Define an Output**: In the `build` job, the `::set-output` command is used to define an output called `version`. This version number is generated using the `date` command to create a unique value. + +2. **Use the Output in Another Job**: In the `deploy` job, the output from the `build` job is referenced with `${{ needs.build.outputs.version }}`, allowing access to data generated in the first job for deployment purposes. + +--- + +## Conclusion + +Creating custom workflows in GitHub Actions allows you to automate your CI/CD pipelines efficiently. Whether you use pre-built actions from the Marketplace or create your own custom actions, GitHub Actions provides unparalleled flexibility. Secrets, environment variables, and conditional execution give you complete control over your workflows, enabling you to build robust, secure processes for your project. + +With these tools, you’re now ready to build workflows tailored to your needs, enhance team collaboration, and reliably automate your deployments and testing. \ No newline at end of file diff --git a/wiki/docs/fr/onboarding/hands-on-labs/learn-github-actions/CICD.md b/wiki/docs/fr/onboarding/hands-on-labs/learn-github-actions/CICD.md new file mode 100644 index 0000000..588a88b --- /dev/null +++ b/wiki/docs/fr/onboarding/hands-on-labs/learn-github-actions/CICD.md @@ -0,0 +1,378 @@ +# Optimisation des Workflows CI/CD avec GitHub Actions + +L'optimisation des workflows CI/CD est essentielle pour améliorer l'efficacité, réduire les temps d'exécution et garantir la stabilité des pipelines de développement. Ce guide détaillé explore différentes techniques pour accélérer vos workflows, optimiser les pipelines CI/CD, gérer les versions des dépendances, et résoudre les problèmes à l'aide des outils de débogage intégrés de GitHub Actions. + +--- + +## 1. Accélérer les Workflows : Mise en Cache des Dépendances et Réutilisation des Workflows + +### 1.1. Mise en Cache des Dépendances + +La mise en cache des dépendances est une méthode efficace pour réduire le temps d'installation des bibliothèques et des modules dans vos workflows CI/CD. GitHub Actions propose une action intégrée appelée **`cache`** qui permet de stocker des fichiers comme des dépendances de build ou des résultats intermédiaires pour les réutiliser lors des exécutions suivantes. + +#### Exemple : Mise en Cache des Dépendances Node.js + +```yaml +name: CI with Cache + +on: [push] + +jobs: + build: + runs-on: ubuntu-latest + + steps: + # Étape 1 : Checkout du code source + - name: Checkout repository + uses: actions/checkout@v2 + + # Étape 2 : Mise en cache des dépendances npm + - name: Cache Node.js modules + uses: actions/cache@v2 + with: + path: node_modules + key: ${{ runner.os }}-node-${{ hashFiles('package-lock.json') }} + restore-keys: | + ${{ runner.os }}-node- + + # Étape 3 : Installer les dépendances + - name: Install dependencies + run: npm install + + # Étape 4 : Construire le projet + - name: Build project + run: npm run build +``` + +#### Explication des Étapes : +- **`actions/cache@v2`** : Cette action met en cache les modules Node.js situés dans le répertoire `node_modules`. Le cache est basé sur la somme de contrôle (hash) du fichier `package-lock.json`. Si aucune modification n'est détectée dans ce fichier, le cache est restauré, réduisant ainsi le temps d'installation des dépendances. +- **`restore-keys`** : Cette option permet de restaurer le cache partiellement si la clé exacte n'est pas trouvée. + +### 1.2. Réutilisation des Workflows + +La réutilisation des workflows permet de centraliser des parties communes de pipelines dans un fichier réutilisable, ce qui simplifie la gestion des workflows complexes. Vous pouvez appeler un workflow à partir d'un autre workflow pour éviter la duplication de code. + +Dans nos projets, nous utilisons un dépôt dédié aux workflows réutilisables. Vous pouvez consulter [**cedille-workflows**](https://github.com/ClubCedille/cedille-workflows), qui contient des exemples de workflows prêts à être réutilisés dans différents projets. Ce dépôt permet de centraliser les définitions de workflows communs, tels que la construction d'images Docker, les déploiements, et la gestion des dépendances. + +Voici la section mise à jour avec un exemple illustrant l'utilisation des variables dans un workflow réutilisable : + +```markdown +#### Exemple : Appeler un Workflow Réutilisable + +Dans ce cas, nous avons un workflow qui effectue des tests, et un autre qui gère les déploiements. Ces workflows sont réutilisés à partir d'un fichier central. + +```yaml +# .github/workflows/reusable-tests.yml +name: Reusable Test Workflow + +on: workflow_call + +jobs: + tests: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v2 + + - name: Install dependencies + run: npm install + + - name: Run tests + run: npm test +``` + +```yaml +# .github/workflows/deploy.yml +name: Deployment Pipeline + +on: + push: + branches: + - main + +jobs: + call-tests: + uses: ./.github/workflows/reusable-tests.yml + + deploy: + needs: call-tests + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v2 + + - name: Deploy to production + run: ./deploy.sh +``` + +#### Exemple : Workflow Réutilisable avec des Variables + +Vous pouvez également définir des **variables d'entrée** dans un workflow réutilisable pour plus de flexibilité. Voici un exemple qui construit et pousse une image Docker vers le GitHub Container Registry (GHCR) en utilisant des variables d'entrée : + +```yaml +# .github/workflows/build-push-ghcr.yml +name: Reusable workflow to build and push docker container to GitHub Container Registry + +on: + workflow_call: + inputs: + container-name: + required: true + type: string + context: + required: false + type: string + default: '.' + file: + required: false + type: string + default: 'Dockerfile' + +env: + REGISTRY: ghcr.io/clubcedille + +jobs: + build-and-push: + runs-on: ubuntu-latest + steps: + - name: Check Out Repo + uses: actions/checkout@v4 + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + + - name: Log in to the Container Registry + uses: docker/login-action@v1 + with: + registry: ${{ env.REGISTRY }} + username: ${{ github.actor }} + password: ${{ secrets.GITHUB_TOKEN }} + + - name: Build and push Docker image + uses: docker/build-push-action@v2 + with: + context: ${{ inputs.context }} + file: ${{ inputs.file }} + push: true + tags: ${{ env.REGISTRY }}/${{ inputs.container-name }}:latest +``` + +#### Exemple d'Utilisation du Workflow Réutilisable : + +Ce workflow peut maintenant être appelé à partir d'un autre workflow, tout en passant des variables personnalisées pour adapter le comportement : + +```yaml +# .github/workflows/deploy-with-docker.yml +name: Deployment with Docker + +on: + push: + branches: + - main + +jobs: + deploy: + uses: ./.github/workflows/build-push-ghcr.yml + with: + container-name: my-app + context: ./my-app-directory +``` + +#### Explication : +- **`workflow_call`** : Permet de réutiliser le workflow en appelant des workflows définis ailleurs. Les variables d'entrée permettent de personnaliser le comportement du workflow réutilisable. +- **Variables d'entrée (`inputs`)** : Les variables comme `container-name`, `context`, et `file` définissent des valeurs spécifiques pour chaque appel du workflow. Cela permet de construire et pousser différentes images Docker sans modifier le workflow de base. +- **Réduction de la duplication** : L'utilisation des variables dans les workflows réutilisables permet de centraliser des tâches communes tout en adaptant leur exécution à des besoins spécifiques, simplifiant ainsi la maintenance des pipelines CI/CD. + +--- + +## 2. Stratégies d’Optimisation des Pipelines (Job Matrix, Jobs Dépendantiels) + +### 2.1. Job Matrix + +La **job matrix** est une fonctionnalité puissante de GitHub Actions qui permet d'exécuter plusieurs combinaisons de configurations en parallèle. Cela est particulièrement utile pour tester votre application sur plusieurs versions de langage, environnements, ou systèmes d'exploitation. + +#### Exemple : Job Matrix avec Node.js + +```yaml +name: Node.js CI + +on: + push: + branches: + - main + +jobs: + test: + runs-on: ubuntu-latest + + strategy: + matrix: + node-version: [12, 14, 16] + os: [ubuntu-latest, windows-latest, macos-latest] + + steps: + - name: Checkout repository + uses: actions/checkout@v2 + + - name: Set up Node.js ${{ matrix.node-version }} + uses: actions/setup-node@v2 + with: + node-version: ${{ matrix.node-version }} + + - name: Install dependencies + run: npm install + + - name: Run tests + run: npm test +``` + +#### Explication : +- **`matrix.node-version`** et **`matrix.os`** : Ces deux matrices permettent de tester sur différentes versions de Node.js (`12`, `14`, `16`) et sur différents systèmes d'exploitation (`ubuntu`, `windows`, `macos`). +- **Exécution parallèle** : GitHub Actions exécute toutes les combinaisons de la matrice en parallèle, ce qui réduit considérablement le temps d’exécution total pour les tests multi-environnement. + +### 2.2. Jobs Dépendantiels + +Les jobs dépendantiels permettent de définir des relations de dépendance entre les jobs, c'est-à-dire qu'un job peut attendre qu'un autre soit terminé avec succès avant de commencer. + +#### Exemple : Dépendance entre Jobs + +```yaml +name: Build and Deploy + +on: + push: + branches: + - main + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v2 + + - name: Build application + run: npm run build + + test: + runs-on: ubuntu-latest + needs: build + steps: + - name: Run tests + run: npm test + + deploy: + runs-on: ubuntu-latest + needs: test + steps: + - name: Deploy to production + run: ./deploy.sh +``` + +#### Explication : +- **`needs`** : L’instruction `needs` permet de définir une dépendance entre jobs. Dans cet exemple, le job `test` ne démarre que lorsque le job `build` a réussi. De même, le job `deploy` attend que `test` se termine. + +--- + +## 3. Gérer les Versions des Dépendances et des Actions + +Une bonne gestion des versions des dépendances et des actions dans vos workflows permet d'assurer la stabilité et de prévenir les erreurs dues aux changements inattendus des bibliothèques ou des actions utilisées. + +### 3.1. Gérer les Versions des Actions + +Lorsque vous utilisez une action dans un workflow GitHub Actions, il est important de spécifier une version spécifique pour garantir que votre workflow reste stable même si l'action est mise à jour dans le futur. + +#### Exemple : Utilisation d'une Version Spécifique d'une Action + +```yaml +jobs: + build: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v2.3.4 # Utilisation d'une version spécifique +``` + +### 3.2. Gérer les Versions des Dépendances + +Il est également recommandé de verrouiller les versions des dépendances utilisées dans votre projet (par exemple dans `package-lock.json` ou `requirements.txt`). Cela garantit que chaque exécution du workflow utilise les mêmes versions de bibliothèques, minimisant les erreurs dues à des mises à jour non testées. + +#### Exemple : Dépendances Verrouillées dans `package-lock.json` + +```yaml +jobs: + build: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v2 + + - name: Install dependencies + run: npm ci # Installe les dépendances avec les versions verrouillées dans package-lock.json +``` + +--- + +## 4. Debugging des Workflows GitHub Actions + +Lorsqu'un workflow échoue ou se comporte de manière inattendue, il est important d’avoir les bons outils pour diagnostiquer et résoudre le problème rapidement. + +### 4.1. Activer les Logs Détaillés + +GitHub Actions permet d'activer des logs détaillés pour aider à diagnostiquer les erreurs. Cela peut être utile si un job échoue sans fournir suffisamment d'informations dans les logs standards. + +#### Activer les Logs Détaillés + +1. Accédez à la page de l'exécution du workflow. +2. Cliquez sur le job échoué pour afficher les logs. +3. Utilisez l'option **Rerun jobs with debug logging** pour relancer le job avec des logs plus détaillés. + +### 4.2. Utilisation de `ACTIONS_STEP_DEBUG` + +Vous pouvez également activer le mode debug en configurant une variable d'environnement spéciale `ACTIONS_STEP_DEBUG`. + +#### Exemple : Activer le Mode Debug dans le Workflow + +```yaml +jobs: + debug-job: + runs-on: ubuntu-latest + + steps: + - name: Enable step debug logging + run: echo "ACTIONS_STEP_DEBUG=true" >> $GITHUB_ENV + + - name: Checkout repository + uses: actions/checkout@v2 +``` + +### 4.3. Ajouter des Messages de Debugging Personnalisés + +Dans certaines situations, vous pouvez avoir besoin d'ajouter des messages de débogage dans vos workflows pour inspecter des valeurs ou vérifier des points de passage. Vous pouvez utiliser `core.debug` pour cela. + +#### Exemple : Ajouter des Messages de Debugging + +```yaml +jobs: + build: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v2 + + - name: Debug message + run: | + echo "DEBUG: Current directory is $(pwd)" + echo "DEBUG: Branch is ${{ github.ref }}" +``` + +--- + +## Conclusion + +Optimiser vos workflows CI/CD dans GitHub Actions est crucial pour garantir des exécutions rapides, stables et efficaces. La mise en cache des dépendances, la réutilisation des workflows, l'utilisation de matrices de jobs et la gestion des dépendances sont toutes des stratégies essentielles pour améliorer les performances. De plus, en utilisant les outils de débogage intégrés, vous pouvez identifier rapidement les problèmes dans vos workflows et les corriger efficacement. Ces bonnes pratiques vous permettent de maintenir des pipelines robustes et performants tout en minimisant les erreurs et les interruptions. \ No newline at end of file diff --git a/wiki/docs/fr/onboarding/hands-on-labs/learn-github-actions/deployment.md b/wiki/docs/fr/onboarding/hands-on-labs/learn-github-actions/deployment.md new file mode 100644 index 0000000..4a9f33e --- /dev/null +++ b/wiki/docs/fr/onboarding/hands-on-labs/learn-github-actions/deployment.md @@ -0,0 +1,373 @@ +# Déploiement Continu avec GitHub Actions + +Le déploiement continu (CD) consiste à automatiser le déploiement des nouvelles versions d'une application directement dans des environnements de production après avoir passé les étapes de tests et de validation. GitHub Actions permet de configurer des pipelines de déploiement continu (CD) pour des plateformes de cloud telles qu'AWS, Azure, ou Google Cloud Platform (GCP). + +--- + +## 1. Déployer une Application sur des Plateformes de Cloud (AWS, Azure, GCP) + +GitHub Actions peut être utilisé pour automatiser le déploiement d'une application sur des services cloud populaires tels que **AWS**, **Microsoft Azure**, ou **Google Cloud Platform (GCP)**. Chaque fournisseur cloud a ses propres outils et services pour gérer le déploiement des applications. + +### 1.1 Déploiement sur AWS + +AWS propose plusieurs services pour héberger des applications, notamment **Elastic Beanstalk**, **ECS (Elastic Container Service)**, et **S3**. Avec GitHub Actions, vous pouvez configurer des workflows pour déployer automatiquement vos applications sur ces services. + +#### Exemple de Workflow pour Déployer sur AWS Elastic Beanstalk + +Elastic Beanstalk simplifie le déploiement et la gestion des applications sur AWS. Voici un exemple de workflow pour déployer une application Node.js sur Elastic Beanstalk. + +```yaml +name: Deploy to AWS Elastic Beanstalk + +on: + push: + branches: + - main + +jobs: + deploy: + runs-on: ubuntu-latest + + steps: + # Étape 1 : Checkout repository + - name: Checkout repository + uses: actions/checkout@v2 + + # Étape 2 : Configure AWS credentials + - name: Configure AWS Credentials + uses: aws-actions/configure-aws-credentials@v1 + with: + aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }} + aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }} + aws-region: us-east-1 + + # Étape 3 : Déployer sur Elastic Beanstalk + - name: Deploy to Elastic Beanstalk + run: | + zip -r app.zip . # Zipper l'application + aws elasticbeanstalk create-application-version --application-name MyApp --version-label latest --source-bundle S3Bucket=my-app-bucket,S3Key=app.zip + aws elasticbeanstalk update-environment --environment-name MyApp-env --version-label latest +``` + +### 1.2 Déploiement sur Microsoft Azure + +Azure propose plusieurs services pour héberger des applications, comme **Azure App Service** et **Azure Kubernetes Service (AKS)**. Avec GitHub Actions, vous pouvez automatiser le déploiement sur ces services en utilisant des actions spécifiques à Azure. + +#### Exemple de Workflow pour Déployer sur Azure App Service + +Azure App Service est une plateforme qui permet de déployer des applications web sur un environnement managé. Voici un exemple de workflow pour déployer une application web sur Azure App Service. + +```yaml +name: Deploy to Azure App Service + +on: + push: + branches: + - main + +jobs: + deploy: + runs-on: ubuntu-latest + + steps: + # Étape 1 : Checkout repository + - name: Checkout repository + uses: actions/checkout@v2 + + # Étape 2 : Configurer les identifiants Azure + - name: Log in to Azure + uses: azure/login@v1 + with: + creds: ${{ secrets.AZURE_CREDENTIALS }} + + # Étape 3 : Déployer sur Azure App Service + - name: Deploy to Azure App Service + uses: azure/webapps-deploy@v2 + with: + app-name: "my-app-service" + package: . +``` + +### 1.3 Déploiement sur Google Cloud Platform (GCP) + +Google Cloud Platform propose des services comme **Google App Engine**, **Google Cloud Run**, et **Google Kubernetes Engine (GKE)**. GitHub Actions peut être utilisé pour automatiser les déploiements sur GCP. + +#### Exemple de Workflow pour Déployer sur Google Cloud Run + +Google Cloud Run permet de déployer des applications conteneurisées directement depuis un dépôt GitHub. Voici un exemple de workflow pour déployer une application sur Google Cloud Run. + +```yaml +name: Deploy to Google Cloud Run + +on: + push: + branches: + - main + +jobs: + deploy: + runs-on: ubuntu-latest + + steps: + # Étape 1 : Checkout repository + - name: Checkout repository + uses: actions/checkout@v2 + + # Étape 2 : Configurer les identifiants Google Cloud + - name: Authenticate to Google Cloud + uses: google-github-actions/auth@v0 + with: + credentials_json: ${{ secrets.GCP_SA_KEY }} + + # Étape 3 : Configurer Google Cloud SDK + - name: Set up Cloud SDK + uses: google-github-actions/setup-gcloud@v1 + with: + project_id: ${{ secrets.GCP_PROJECT_ID }} + service_account_key: ${{ secrets.GCP_SA_KEY }} + + # Étape 4 : Construire et déployer l'image Docker sur Cloud Run + - name: Build and Deploy to Cloud Run + run: | + gcloud builds submit --tag gcr.io/${{ secrets.GCP_PROJECT_ID }}/my-app + gcloud run deploy my-app --image gcr.io/${{ secrets.GCP_PROJECT_ID }}/my-app --region us-central1 +``` + +--- + +## 2. Exemples Pratiques de Pipelines de Déploiement Continu + +Les pipelines CI/CD consistent en des étapes automatisées qui prennent en charge le build, les tests, et le déploiement d'une application. Voici quelques exemples pratiques de pipelines de déploiement continu avec GitHub Actions. + +### Pipeline de Base pour une Application Node.js Déployée sur AWS S3 + +```yaml +name: CI/CD Pipeline for Node.js + +on: + push: + branches: + - main + +jobs: + build-and-deploy: + runs-on: ubuntu-latest + + steps: + # Étape 1 : Checkout repository + - name: Checkout repository + uses: actions/checkout@v2 + + # Étape 2 : Installer Node.js et les dépendances + - name: Set up Node.js + uses: actions/setup-node@v2 + with: + node-version: '14' + + - name: Install dependencies + run: npm install + + # Étape 3 : Exécuter les tests + - name: Run tests + run: npm test + + # Étape 4 : Construire l'application + - name: Build application + run: npm run build + + # Étape 5 : Se connecter à AWS + - name: Configure AWS Credentials + uses: aws-actions/configure-aws-credentials@v1 + with: + aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }} + aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }} + aws-region: us-west-1 + + # Étape 6 : Déployer l'application sur un bucket S3 + - name: Deploy to S3 + run: aws s3 sync ./build s3://my-app-bucket --delete +``` + +--- + +## 3. Stratégies de Déploiement : Blue/Green, Canary + +GitHub Actions peut être utilisé pour implémenter différentes **stratégies de déploiement**, telles que le déploiement **Blue/Green** et le déploiement **Canary**, pour minimiser les risques lors des déploiements en production. + +### 3.1 Déploiement Blue/Green + +Le déploiement **Blue/Green** consiste à exécuter deux environnements distincts : l'environnement **Blue** (ancien) et l'environnement **Green** (nouveau). Une fois que le déploiement est prêt sur l'environnement Green, le trafic est basculé vers cet environnement. + +#### Exemple de Workflow pour un Déploiement Blue/Green + +```yaml +name: Blue/Green Deployment + +on: + push: + branches: + - main + +jobs: + deploy: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v2 + + # Étape 1 : Déployer sur l'environnement Green + - name: Deploy to Green environment + run: | + aws deploy create-deployment \ + --application-name my-app \ + --deployment-group-name GreenEnvironment \ + --s3-location bucket=my-app-bucket,bundleType=zip,key=my-app.zip + + # Étape 2 : Basculer le trafic vers l'environnement Green + - name: Switch traffic to Green + run: | + aws deploy update-deployment-group \ + --application-name my-app \ + --current-deployment-group-name BlueEnvironment \ + --new-deployment-group-name GreenEnvironment +``` + +### 3.2 Déploiement Canary + +Le déploiement **Canary** consiste à déployer une nouvelle version à un petit pourcentage des utilisateurs pour tester son impact. Si la version Canary est stable, le déploiement est progressivement étendu à tous les utilisateurs. + +#### Exemple de Workflow pour un Déploiement Canary + +```yaml +name: Canary Deployment + +on: + push: + branches: + - main + +jobs: + deploy: + runs-on + +: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v2 + + # Étape 1 : Déployer en Canary (petit pourcentage d'utilisateurs) + - name: Deploy Canary release + run: | + aws deploy create-deployment \ + --application-name my-app \ + --deployment-group-name CanaryEnvironment \ + --s3-location bucket=my-app-bucket,bundleType=zip,key=my-app.zip \ + --deployment-config-name CodeDeployDefault.OneAtATime + + # Étape 2 : Augmenter progressivement le déploiement + - name: Gradually increase deployment + run: | + aws deploy create-deployment \ + --application-name my-app \ + --deployment-group-name ProductionEnvironment \ + --s3-location bucket=my-app-bucket,bundleType=zip,key=my-app.zip +``` + +--- + +## 4. Notifications sur le Statut du Déploiement (Slack, Email) + +GitHub Actions permet d'envoyer des notifications sur le statut d'un déploiement réussi ou échoué via **Slack**, **Email**, ou d'autres outils de collaboration. + +### 4.1 Notifications Slack + +Vous pouvez configurer GitHub Actions pour envoyer des notifications via Slack lorsque des événements spécifiques se produisent, comme l'achèvement d'un déploiement. + +#### Exemple de Workflow avec Notification Slack + +```yaml +name: CI/CD Pipeline with Slack Notifications + +on: + push: + branches: + - main + +jobs: + build-and-deploy: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v2 + + - name: Build application + run: npm run build + + - name: Deploy to production + run: ./deploy.sh + + notify: + runs-on: ubuntu-latest + needs: build-and-deploy + steps: + - name: Send Slack Notification + uses: rtCamp/action-slack-notify@v2 + env: + SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }} + SLACK_MESSAGE: "The deployment to production was successful!" +``` + +### 4.2 Notifications par Email + +Vous pouvez également configurer des notifications par email en utilisant des actions GitHub ou des services tiers pour envoyer des emails après le déploiement. + +#### Exemple de Workflow avec Notification par Email + +```yaml +name: CI/CD Pipeline with Email Notifications + +on: + push: + branches: + - main + +jobs: + build-and-deploy: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v2 + + - name: Build application + run: npm run build + + - name: Deploy to production + run: ./deploy.sh + + notify: + runs-on: ubuntu-latest + needs: build-and-deploy + steps: + - name: Send Email Notification + uses: dawidd6/action-send-mail@v2 + with: + server_address: smtp.gmail.com + server_port: 465 + username: ${{ secrets.EMAIL_USERNAME }} + password: ${{ secrets.EMAIL_PASSWORD }} + subject: "Deployment Status" + body: "The deployment was successful." + to: "recipient@example.com" +``` + +--- + +## Conclusion + +Le déploiement continu avec GitHub Actions permet de simplifier et d'automatiser le processus de mise en production de vos applications. Grâce à l'intégration avec des plateformes cloud comme AWS, Azure, et GCP, ainsi qu'à l'utilisation de stratégies de déploiement telles que Blue/Green ou Canary, vous pouvez réduire les risques de déploiement et assurer une livraison continue. De plus, la possibilité d'envoyer des notifications via Slack ou Email améliore la visibilité sur l'état des déploiements et permet aux équipes de réagir rapidement en cas de problèmes. + +GitHub Actions offre une grande flexibilité pour automatiser l'ensemble de votre pipeline de déploiement, et vous permet d'optimiser la manière dont vous gérez la livraison de vos applications. diff --git a/wiki/docs/fr/onboarding/hands-on-labs/learn-github-actions/first-step.md b/wiki/docs/fr/onboarding/hands-on-labs/learn-github-actions/first-step.md new file mode 100644 index 0000000..4d1f4bc --- /dev/null +++ b/wiki/docs/fr/onboarding/hands-on-labs/learn-github-actions/first-step.md @@ -0,0 +1,267 @@ +# Premiers Pas avec GitHub Actions + +GitHub Actions est une plateforme intégrée qui permet de créer, exécuter et automatiser des workflows directement dans GitHub. Dans cette section, nous allons explorer comment configurer un workflow de base, comprendre la syntaxe YAML utilisée pour définir ces workflows, et découvrir les différents déclencheurs d'événements disponibles. + +--- + +## 1. Configuration de base : `.github/workflows` + +Pour commencer à utiliser GitHub Actions, vous devez créer un répertoire spécifique dans votre dépôt GitHub pour y stocker vos fichiers de workflow. Ce répertoire doit être nommé **`.github/workflows`**. + +### Étapes pour créer votre premier workflow : +1. **Créer le répertoire** : Dans la racine de votre projet, créez le répertoire `.github/workflows`. +2. **Ajouter un fichier de workflow** : Les workflows sont définis dans des fichiers au format YAML (avec l'extension `.yml`). Par exemple, vous pouvez créer un fichier nommé `ci.yml` pour un workflow CI. + +### Exemple de structure de dépôt avec un workflow : + +```text +my-project/ +├── .github/ +│ └── workflows/ +│ └── ci.yml +├── src/ +├── README.md +└── package.json +``` + +Le fichier de workflow contient toutes les étapes que GitHub Actions doit exécuter lorsqu'un événement est déclenché, comme un `push` ou une `pull request`. Ce fichier YAML spécifie les jobs, les actions, et d'autres paramètres qui forment la base de votre pipeline CI/CD. + +--- + +## 2. Exemple simple d’un workflow CI + +Voici un exemple de workflow CI simple qui s'exécute à chaque fois qu'une modification est poussée vers la branche `main`. Ce workflow installe les dépendances, exécute des tests et compile le projet. + +```yaml +name: CI Pipeline # Nom du workflow + +# Ce workflow est déclenché lors d'un push ou d'une pull request sur la branche 'main' +on: + push: + branches: + - main + pull_request: + branches: + - main + +jobs: + build: # Nom du job + runs-on: ubuntu-latest # Environnement dans lequel le job s'exécute + + steps: + # Étape 1 : Vérifier le code source + - name: Checkout repository + uses: actions/checkout@v2 + + # Étape 2 : Configurer Node.js + - name: Set up Node.js + uses: actions/setup-node@v2 + with: + node-version: '14' + + # Étape 3 : Installer les dépendances + - name: Install dependencies + run: npm install + + # Étape 4 : Exécuter les tests + - name: Run tests + run: npm test + + # Étape 5 : Compiler le projet + - name: Build project + run: npm run build +``` + +### Explication : +- **`name:`** : Donne un nom au workflow. Ce nom est visible dans l’interface GitHub Actions. +- **`on:`** : Spécifie les événements qui déclenchent le workflow. Dans cet exemple, le workflow s'exécute lorsqu'il y a un `push` ou une `pull request` sur la branche `main`. +- **`jobs:`** : Définit les différents jobs dans le workflow. Chaque job peut contenir plusieurs étapes (steps). +- **`runs-on:`** : Indique l'environnement où le job sera exécuté (ici, une machine Ubuntu hébergée par GitHub). +- **`steps:`** : Les étapes à exécuter dans le job, qui peuvent inclure des actions pré-construites (comme `actions/checkout@v2`) ou des commandes à exécuter. + +--- + +## 3. Syntaxe des fichiers YAML pour définir les workflows + +Les workflows GitHub Actions sont écrits en YAML. Ce format est simple à lire et à écrire, et permet de structurer les workflows avec des jobs, des étapes, des actions, et des variables. Voici une explication détaillée de la syntaxe de base des fichiers YAML pour GitHub Actions. + +### Structure générale d’un fichier YAML GitHub Actions : +```yaml +name: Nom du workflow + +on: # Déclencheur(s) d'événement(s) + push: + branches: + - main + +jobs: # Les jobs à exécuter + job_name: # Nom du job + runs-on: environnement # Environnement d'exécution (ex: ubuntu-latest, windows-latest, macos-latest) + + steps: # Les étapes à exécuter dans ce job + - name: Nom de l'étape + uses: action@version # Utilisation d'une action prédéfinie + with: # Arguments passés à l'action + param: valeur + + - name: Nom de l'étape + run: commande_shell # Commande shell à exécuter +``` + +### Les éléments YAML les plus courants : +- **`name:`** : Nom du workflow. +- **`on:`** : Les événements qui déclenchent le workflow. Il peut s'agir de `push`, `pull_request`, `schedule`, ou autres. +- **`jobs:`** : Définit les jobs, qui contiennent des étapes à exécuter. +- **`runs-on:`** : Spécifie l'environnement d'exécution du job (ex. `ubuntu-latest`, `windows-latest`, `macos-latest`). +- **`steps:`** : Les étapes dans un job, qui peuvent inclure des actions prédéfinies ou des commandes personnalisées à exécuter. + +### Exemples d'étapes : +1. **Utilisation d’une action prédéfinie** : + ```yaml + - name: Checkout code + uses: actions/checkout@v2 + ``` + Ici, nous utilisons l'action `actions/checkout@v2` pour récupérer le code source du dépôt. + +2. **Exécution d’une commande personnalisée** : + ```yaml + - name: Run tests + run: npm test + ``` + Cette étape exécute la commande `npm test` pour lancer les tests du projet. + +--- + +## 4. Déclencheurs (events) : `push`, `pull_request`, `schedule`, etc. + +Les workflows GitHub Actions peuvent être déclenchés par une variété d'événements. Voici les déclencheurs les plus courants : + +### 4.1. `push` + +Le déclencheur `push` est utilisé pour exécuter un workflow chaque fois qu'un `push` est effectué dans le dépôt. Vous pouvez également spécifier des branches ou des chemins spécifiques pour lesquels le workflow doit s'exécuter. + +#### Exemple : +```yaml +on: + push: + branches: + - main + paths: + - 'src/**' +``` +- **`branches:`** : Le workflow se déclenchera uniquement lorsque des modifications sont poussées sur la branche `main`. +- **`paths:`** : Le workflow s'exécutera uniquement si les fichiers modifiés se trouvent dans le répertoire `src`. + +### 4.2. `pull_request` + +Le déclencheur `pull_request` permet d'exécuter un workflow lorsqu'une nouvelle pull request est créée, ou lorsque celle-ci est mise à jour. + +#### Exemple : +```yaml +on: + pull_request: + branches: + - main +``` +Dans cet exemple, le workflow se déclenchera pour toutes les pull requests ouvertes sur la branche `main`. + +### 4.3. `schedule` + +Le déclencheur `schedule` vous permet de définir des workflows qui s'exécutent à des moments spécifiques, similaires à une tâche cron. + +#### Exemple : +```yaml +on: + schedule: + - cron: "0 0 * * 1" +``` +Cet exemple déclenche le workflow chaque lundi à minuit (heure UTC). Le format `cron` est le même que celui utilisé dans les tâches cron de Linux. + +### 4.4. Autres déclencheurs + +- **`workflow_dispatch`** : Permet d’exécuter manuellement un workflow via l'interface utilisateur de GitHub. +- **`workflow_call`** : Permet d'invoquer un workflow à partir d'un autre workflow. Cela est utile pour réutiliser des workflows dans plusieurs projets ou dépôts. +- **`release`** : Déclenche le workflow lorsqu'une nouvelle version est publiée. +- **`issue_comment`** : Exécute le workflow lorsqu'un commentaire est ajouté à une issue. +- **`push_tag`** : Déclenche le workflow lorsqu'un tag est poussé. + +#### Exemple de `workflow_dispatch` : +```yaml +on: + workflow_dispatch: +``` + +Ce workflow peut être déclenché manuellement depuis l'interface GitHub Actions. Par exemple, voici [un cas d'utilisation réel](https://github.com/ClubCedille/Plateforme-Cedille/blob/master/.github/workflows/add-new-member.yml) de `workflow_dispatch` pour la Plateforme CEDILLE, permettant d'ajouter un nouveau membre à l'organisation via l'interface utilisateur de GitHub Actions : + +```yaml +name: Ajouter un nouveau membre à l'organisation +on: + workflow_dispatch: + inputs: + github_username: + description: 'GitHub username' + required: true + type: string + github_email: + description: 'GitHub Email' + required: true + type: string + team_sre: + description: 'Add to SRE team?' + required: false + type: boolean + cluster_role: + description: 'Cluster Role' + required: true + type: choice + options: + - None + - Reader + - Operator + - Admin +``` + +Dans cet exemple, le workflow permet à l'administrateur d'ajouter un nouveau membre à l'organisation, de modifier les fichiers Terraform, et de créer une Pull Request pour appliquer ces changements. + +#### Exemple de `workflow_call` : +```yaml +on: + workflow_call: +``` + +Le déclencheur `workflow_call` permet à un workflow d'être appelé depuis un autre workflow. C'est une manière efficace de partager et de réutiliser des workflows dans plusieurs projets ou équipes. Par exemple, dans le dépôt [cedille-workflows](https://github.com/ClubCedille/cedille-workflows), nous utilisons ce type de déclencheur pour centraliser et réutiliser des workflows standardisés dans différents projets. + +Voici un exemple d'utilisation de `workflow_call` : + +```yaml +name: Réutilisation d'un workflow + +on: + workflow_call: + inputs: + environment: + description: 'Environnement cible (dev, staging, prod)' + required: true + type: string + +jobs: + build: + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v2 + + - name: Run build + run: echo "Building for ${{ inputs.environment }}" +``` +Dans cet exemple, le workflow peut être invoqué par d'autres workflows pour effectuer une tâche spécifique, comme la construction ou le déploiement pour un environnement particulier. + + +--- + +## Conclusion + +Avec GitHub Actions, la configuration de base pour l'automatisation des workflows CI/CD est simple et puissante. En créant des workflows dans le répertoire `.github/workflows`, vous pouvez automatiser des tâches en réponse à divers événements tels que des `push`, `pull_request`, ou des horaires planifiés via `schedule`. La syntaxe YAML permet de définir facilement les jobs et les étapes, et la flexibilité des déclencheurs rend GitHub Actions adaptable à différents scénarios de développement et de déploiement. + +GitHub Actions est conçu pour être intuitif et peut être étendu en utilisant des actions prédéfinies ou personnalisées, ce qui en fait un outil essentiel pour tout pipeline CI/CD moderne. diff --git a/wiki/docs/fr/onboarding/hands-on-labs/learn-github-actions/index.md b/wiki/docs/fr/onboarding/hands-on-labs/learn-github-actions/index.md new file mode 100644 index 0000000..13710c6 --- /dev/null +++ b/wiki/docs/fr/onboarding/hands-on-labs/learn-github-actions/index.md @@ -0,0 +1,42 @@ +# Apprendre GitHub Actions + +Bienvenue dans la documentation GitHub Actions pour les débutants ! + +Ce guide est conçu pour vous aider à démarrer avec GitHub Actions, un outil puissant qui vous permet d'automatiser l'intégration continue (CI), le déploiement continu (CD), et bien plus encore directement depuis votre dépôt GitHub. Que vous soyez un développeur expérimenté ou simplement curieux à propos de GitHub Actions, cette documentation vous fournira les bases dont vous avez besoin pour commencer à automatiser vos workflows et simplifier vos processus DevOps. + +--- + +## Sommaire + +- **Introduction à GitHub Actions** + Apprenez les concepts clés tels que les workflows, jobs, steps, et runners, ainsi que la différence entre GitHub Actions et d'autres outils CI/CD. + +- **Premiers Pas avec GitHub Actions** + Découvrez comment configurer vos premiers workflows, écrire des fichiers YAML et utiliser les déclencheurs pour automatiser vos tâches. + +- **Créer des Workflows Personnalisés** + Comprenez comment créer des workflows plus avancés en définissant des jobs, en utilisant des actions préconstruites depuis le GitHub Marketplace, et en créant vos propres actions. + +- **Intégration avec Docker et Kubernetes** + Apprenez à automatiser la construction d'images Docker, à les pousser dans des registres et à déployer vos applications sur des clusters Kubernetes. + +- **Déploiement Continu avec GitHub Actions** + Explorez les stratégies de déploiement pour vos applications sur des plateformes cloud telles qu'AWS, Azure, et GCP, et comment configurer des notifications après déploiement. + +- **Utiliser GitHub Container Registry (GHCR)** + Découvrez comment utiliser GitHub Container Registry pour gérer et distribuer des images de conteneurs directement depuis GitHub. + +- **Gestion de la Sécurité et des Permissions** + Apprenez à utiliser GitHub Secrets pour gérer des informations sensibles, configurer les permissions des workflows et intégrer Dependabot pour les scans de sécurité des dépendances. + +- **Optimisation des Workflows CI/CD** + Apprenez à accélérer vos workflows avec la mise en cache des dépendances, à gérer les versions des dépendances et des actions, et à déboguer vos workflows efficacement. + +- **Monitoring et Reporting** + Découvrez comment surveiller vos workflows, générer des rapports de tests automatisés, et configurer des notifications d'échec ou de succès de build. + +- **Cas Pratiques : DevOps avec GitHub Actions** + Explorez des exemples pratiques pour déployer des applications Node.js avec Docker, gérer des pipelines CI/CD avec des services cloud, et automatiser des chaînes DevOps complètes. + +- **Bonnes Pratiques et Patterns DevOps avec GitHub Actions** + Découvrez des stratégies pour structurer vos workflows dans des projets complexes, centraliser les fichiers de configuration et gérer plusieurs environnements (développement, staging, production). \ No newline at end of file diff --git a/wiki/docs/fr/onboarding/hands-on-labs/learn-github-actions/integration.md b/wiki/docs/fr/onboarding/hands-on-labs/learn-github-actions/integration.md new file mode 100644 index 0000000..e7b4c14 --- /dev/null +++ b/wiki/docs/fr/onboarding/hands-on-labs/learn-github-actions/integration.md @@ -0,0 +1,259 @@ +# Intégration avec Docker et Kubernetes dans GitHub Actions + +GitHub Actions peut être utilisé pour automatiser des tâches liées à Docker et Kubernetes, notamment la construction et la publication d'images Docker ainsi que le déploiement de ces images dans des clusters Kubernetes. Dans cette documentation, nous allons explorer comment utiliser GitHub Actions pour intégrer Docker et Kubernetes dans vos pipelines CI/CD. + +--- + +## 1. Construire et Pousser des Images Docker avec GitHub Actions + +Docker est un outil de virtualisation légère qui vous permet de créer des conteneurs pour exécuter des applications dans des environnements isolés. Avec GitHub Actions, vous pouvez automatiser la construction de ces conteneurs, puis les pousser vers un registre Docker (comme Docker Hub ou GitHub Container Registry). + +### Étapes pour Construire et Pousser des Images Docker + + 1. **Écrire un Dockerfile** + Le Dockerfile contient les instructions pour créer une image Docker à partir de votre projet. Voici un exemple simple de Dockerfile pour une application Node.js : + + ```dockerfile + # Utiliser une image de base officielle Node.js + FROM node:14 + + # Définir le répertoire de travail + WORKDIR /app + + # Copier le fichier package.json + COPY package*.json ./ + + # Installer les dépendances + RUN npm install + + # Copier le reste des fichiers du projet + COPY . . + + # Exposer le port de l'application + EXPOSE 3000 + + # Démarrer l'application + CMD ["npm", "start"] + ``` + + 2. **Configurer GitHub Actions pour construire et pousser l'image** + + Une fois le Dockerfile créé, vous pouvez configurer un workflow GitHub Actions pour construire l'image Docker, puis la pousser vers un registre Docker. + +### Exemple de Workflow : Construction et Push d'une Image Docker + +Le workflow suivant s'exécute lorsqu'une modification est poussée sur la branche `main`. Il construit une image Docker à partir du Dockerfile et la pousse sur Docker Hub. + +```yaml +name: Build and Push Docker Image + +# Déclenchement du workflow sur un push vers la branche 'main' +on: + push: + branches: + - main + +jobs: + build: + runs-on: ubuntu-latest # Utilisation d'un environnement Ubuntu + + steps: + # Étape 1 : Récupérer le code source du dépôt + - name: Checkout code + uses: actions/checkout@v2 + + # Étape 2 : Connexion à Docker Hub + - name: Log in to Docker Hub + uses: docker/login-action@v2 + with: + username: ${{ secrets.DOCKER_USERNAME }} # Stocker le nom d'utilisateur comme secret + password: ${{ secrets.DOCKER_PASSWORD }} # Stocker le mot de passe comme secret + + # Étape 3 : Construire l'image Docker + - name: Build Docker image + run: docker build -t ${{ secrets.DOCKER_USERNAME }}/my-app:latest . + + # Étape 4 : Pousser l'image Docker sur Docker Hub + - name: Push Docker image + run: docker push ${{ secrets.DOCKER_USERNAME }}/my-app:latest +``` + +### Explication du Workflow : +- **`docker/login-action@v2`** : Cette action permet de se connecter à Docker Hub en utilisant un nom d'utilisateur et un mot de passe sécurisés stockés dans les secrets du dépôt. +- **`docker build`** : La commande construit une image Docker à partir du Dockerfile dans le répertoire racine du projet. +- **`docker push`** : Cette commande pousse l'image Docker vers Docker Hub. + +### Utiliser GitHub Container Registry + +GitHub Container Registry (GHCR) est une alternative à Docker Hub pour héberger vos images Docker. Il est intégré à GitHub et permet de stocker et gérer vos images conteneurisées à côté de votre code source. + +#### Exemple de Workflow pour Pousser vers GitHub Container Registry (GHCR) + +```yaml +name: Build and Push Docker Image to GHCR + +on: + push: + branches: + - main + +jobs: + build: + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v2 + + - name: Log in to GitHub Container Registry + run: echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u ${{ github.actor }} --password-stdin + + - name: Build Docker image + run: docker build -t ghcr.io/${{ github.repository }}/my-app:latest . + + - name: Push Docker image + run: docker push ghcr.io/${{ github.repository }}/my-app:latest +``` + +Dans cet exemple, l'image est poussée vers le GitHub Container Registry au lieu de Docker Hub. + +--- + +## 2. Automatiser les Déploiements Kubernetes avec GitHub Actions + +Kubernetes est un orchestrateur de conteneurs populaire utilisé pour déployer, gérer et mettre à l'échelle des applications conteneurisées. GitHub Actions peut être utilisé pour automatiser le déploiement d'images Docker dans un cluster Kubernetes. + +### Étapes pour Déployer sur Kubernetes avec GitHub Actions + +1. **Configurer `kubectl` pour interagir avec votre cluster Kubernetes** + Vous devez d'abord configurer GitHub Actions pour utiliser `kubectl`, l'outil de ligne de commande de Kubernetes, pour interagir avec votre cluster Kubernetes. + +2. **Utiliser les Secrets pour Stocker les Informations Sensibles** + Vous devrez stocker des informations comme les identifiants du cluster Kubernetes et les certificats dans les secrets GitHub pour les utiliser de manière sécurisée. + +### Exemple de Workflow : Déploiement Automatisé sur Kubernetes + +Le workflow suivant utilise `kubectl` pour déployer l'image Docker sur un cluster Kubernetes après avoir été poussée vers Docker Hub. + +```yaml +name: Deploy to Kubernetes + +on: + push: + branches: + - main + +jobs: + deploy: + runs-on: ubuntu-latest + + steps: + # Étape 1 : Récupérer le code source du dépôt + - name: Checkout code + uses: actions/checkout@v2 + + # Étape 2 : Installer kubectl + - name: Set up kubectl + uses: azure/setup-kubectl@v3 + with: + version: 'latest' + + # Étape 3 : Configurer l'accès au cluster Kubernetes + - name: Set up kubeconfig + run: | + mkdir -p ~/.kube + echo "${{ secrets.KUBECONFIG }}" > ~/.kube/config + + # Étape 4 : Mettre à jour le déploiement Kubernetes + - name: Deploy to Kubernetes + run: | + kubectl set image deployment/my-app my-app-container=${{ secrets.DOCKER_USERNAME }}/my-app:latest +``` + +### Explication du Workflow : + +- **`azure/setup-kubectl@v3`** : Cette action installe `kubectl` dans l'environnement de workflow. +- **`kubeconfig`** : Le fichier `kubeconfig` contient les informations d'authentification pour interagir avec le cluster Kubernetes. Il est stocké dans les secrets GitHub. +- **`kubectl set image`** : Cette commande met à jour l'image conteneurisée du déploiement Kubernetes. + +Au sein de CEDILLE, nous utilisons des outils GitOps comme **ArgoCD** pour gérer automatiquement nos déploiements et synchroniser nos applications avec les clusters Kubernetes. ArgoCD simplifie l'automatisation en surveillant les dépôts Git pour détecter les changements et les appliquer automatiquement aux clusters, ce qui élimine le besoin de manuellement gérer ces aspects via GitHub Actions. + +--- + +## 3. Exemples d’Utilisation de `docker`, `kubectl`, et `helm` dans des Workflows CI/CD + +En combinant Docker, `kubectl`, et Helm, vous pouvez créer des workflows CI/CD puissants pour automatiser la gestion des conteneurs et les déploiements Kubernetes. Voici un exemple d'utilisation dans un workflow GitHub Actions qui couvre à la fois `kubectl` et **Helm**. + +### Exemple : Utilisation de Docker avec `kubectl` et Helm + +Dans cet exemple, nous allons construire une image Docker, la pousser vers Docker Hub, puis mettre à jour un déploiement Kubernetes avec cette nouvelle image. Nous présentons aussi comment utiliser **Helm** pour gérer les déploiements plus complexes. + +#### Workflow CI/CD pour Docker et Kubernetes + +```yaml +name: CI/CD for Docker and Kubernetes + +on: + push: + branches: + - main + +jobs: + build-and-deploy: + runs-on: ubuntu-latest + + steps: + # Étape 1 : Checkout repository + - name: Checkout repository + uses: actions/checkout@v2 + + # Étape 2 : Log in to Docker Hub + - name: Log in to Docker Hub + uses: docker/login-action@v2 + with: + username: ${{ secrets.DOCKER_USERNAME }} + password: ${{ secrets.DOCKER_PASSWORD }} + + # Étape 3 : Build Docker image + - name: Build Docker image + run: docker build -t ${{ secrets.DOCKER_USERNAME }}/my-app:latest . + + # Étape 4 : Push Docker image + - name: Push Docker image + run: docker push ${{ secrets.DOCKER_USERNAME }}/my-app:latest + + # Étape 5 : Set up kubectl + - name: Set up kubectl + uses: azure/setup-kubectl@v3 + with: + version: 'latest' + + # Étape 6 : Deploy to Kubernetes with kubectl + - name: Update Kubernetes Deployment with kubectl + run: | + kubectl set image deployment/my-app my-app-container=${{ secrets.DOCKER_USERNAME }}/my-app:latest + + # Étape 7 (optionnel) : Deploy application with Helm + - name: Install Helm + run: | + curl https://raw.githubusercontent.com/helm/helm/master/scripts/get-helm-3 | bash + + - name: Deploy application with Helm + run: helm upgrade --install my-app ./helm-chart --set image.tag=latest +``` + +### Explication du Workflow : + +1. **kubectl** : L'étape 6 met à jour l'image conteneurisée du déploiement Kubernetes en utilisant `kubectl`. +2. **Helm** : Les étapes 7 et suivantes montrent comment installer **Helm** et l'utiliser pour déployer ou mettre à jour une application Kubernetes à partir d'un chart Helm. Helm est particulièrement utile pour gérer des déploiements plus complexes en Kubernetes. +3. **Secrets** : Le fichier de configuration Kubernetes (`kubeconfig`) est stocké dans les secrets GitHub pour assurer la sécurité des informations d'authentification. + +Dans ce workflow, vous pouvez choisir d'utiliser soit **kubectl** pour les déploiements simples, soit **Helm** pour les déploiements plus complexes. L'intégration des deux outils dans le même workflow permet de gérer des cas d'utilisation variés selon la complexité de vos déploiements Kubernetes. + +--- + +## Conclusion + +L'intégration de Docker et Kubernetes dans vos workflows CI/CD avec GitHub Actions simplifie la construction, le test, et le déploiement d'applications conteneurisées. Que vous utilisiez Docker pour créer des images et Kubernetes pour orchestrer ces conteneurs, GitHub Actions fournit les outils nécessaires pour automatiser entièrement ces processus. Vous pouvez ainsi construire, tester, et déployer des applications de manière fluide et sécurisée tout en réduisant les erreurs manuelles. + +En utilisant `docker`, `kubectl`, et Helm dans vos workflows, vous pouvez créer des pipelines robustes et flexibles, adaptés à la production, aux tests, ou à tout autre environnement Kubernetes. diff --git a/wiki/docs/fr/onboarding/hands-on-labs/learn-github-actions/introductions.md b/wiki/docs/fr/onboarding/hands-on-labs/learn-github-actions/introductions.md new file mode 100644 index 0000000..de5c99d --- /dev/null +++ b/wiki/docs/fr/onboarding/hands-on-labs/learn-github-actions/introductions.md @@ -0,0 +1,192 @@ +# Introduction à GitHub Actions + +## Qu'est-ce que GitHub Actions ? + +GitHub Actions est une plateforme d'automatisation intégrée à GitHub, qui permet de créer, gérer et exécuter des workflows automatisés directement à partir de vos dépôts GitHub. Avec GitHub Actions, vous pouvez définir des processus d'intégration continue (CI) et de déploiement continu (CD), automatiser les tests, les builds, les déploiements, et bien plus encore. + +La grande force de GitHub Actions est son intégration native avec GitHub, vous permettant de déclencher des workflows en fonction d’événements de dépôt comme les `push`, `pull requests`, ou même des déclencheurs personnalisés comme un `cron` planifié. + +### Caractéristiques principales de GitHub Actions : +- **Intégration complète avec GitHub** : Les workflows peuvent être déclenchés par les événements GitHub tels que les `push`, les `pull request`, les `issues`, et bien d'autres. +- **Flexibilité** : GitHub Actions est hautement personnalisable avec des centaines d'actions disponibles dans le [GitHub Marketplace](https://github.com/marketplace?type=actions). +- **Runners hébergés et auto-hébergés** : GitHub propose des environnements de build préconfigurés, ou vous pouvez utiliser vos propres machines pour exécuter des workflows. + +--- + +## Utilisation principale dans l'intégration continue (CI) et le déploiement continu (CD) + +GitHub Actions est particulièrement utile pour implémenter des pipelines d'intégration continue (CI) et de déploiement continu (CD). Voici un aperçu de chaque concept : + +### Intégration Continue (CI) + +L'intégration continue est un processus dans lequel les développeurs fusionnent régulièrement leurs modifications de code dans la branche principale du dépôt. Les tests automatisés sont exécutés pour vérifier que le code nouvellement intégré ne casse rien dans le projet. GitHub Actions permet d’automatiser ce processus en créant des workflows qui s'exécutent automatiquement lorsqu'un `push` ou une `pull request` est fait sur un dépôt. + +- **Exemple d’utilisation CI :** + - Exécution automatique des tests unitaires après chaque `commit` ou `pull request`. + - Compilation automatique du code pour vérifier qu’il n’y a pas d’erreurs de syntaxe ou de compilation. + +```yaml +name: CI Pipeline + +on: [push, pull_request] + +jobs: + build: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v2 + + - name: Set up Node.js + uses: actions/setup-node@v2 + with: + node-version: '14' + + - name: Install dependencies + run: npm install + + - name: Run tests + run: npm test +``` + +### Déploiement Continu (CD) + +Le déploiement continu consiste à automatiser le déploiement de votre application dans différents environnements (développement, staging, production). GitHub Actions peut être utilisé pour déclencher des déploiements après le succès des tests. Par exemple, vous pouvez configurer un workflow pour déployer une application sur un service cloud comme AWS, Azure ou GCP après chaque `merge` sur la branche principale. + +- **Exemple d’utilisation CD :** + - Déploiement d’une application sur AWS après un `merge` réussi sur la branche `main`. + - Automatisation des versions avec des workflows qui génèrent automatiquement des versions de l’application et les publient. + +```yaml +name: CD Pipeline + +on: + push: + branches: + - main + +jobs: + deploy: + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v2 + + - name: Deploy to AWS + uses: aws-actions/configure-aws-credentials@v1 + with: + aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }} + aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }} + aws-region: us-west-2 + + - name: Deploy application + run: | + aws s3 sync ./build s3://my-app-bucket +``` + +--- + +## Concepts clés de GitHub Actions + +GitHub Actions repose sur plusieurs concepts clés qui permettent de structurer et organiser les workflows d’automatisation. Voici une explication détaillée des termes fondamentaux : + +### Workflows + +Un **workflow** est une automatisation définie dans un fichier YAML dans le répertoire `.github/workflows/`. Un workflow est composé d'une ou plusieurs **jobs** qui s’exécutent en fonction d'événements spécifiques. Par exemple, un workflow peut être déclenché lorsqu'un développeur pousse du code dans le dépôt. + +- **Déclencheurs d’événements** : Les workflows sont déclenchés par des événements spécifiques, tels qu'un `push`, une `pull request`, ou des événements planifiés avec un `cron`. +- **Définition de jobs** : Un workflow contient un ou plusieurs jobs. Chaque job est une série d'étapes exécutées dans un environnement distinct. + +### Jobs + +Un **job** est une séquence d'**étapes** qui s’exécutent dans un environnement isolé. Tous les jobs dans un workflow s’exécutent par défaut en parallèle, mais ils peuvent être configurés pour s'exécuter de manière séquentielle si un job dépend d’un autre. + +- **Exécution parallèle** : Plusieurs jobs peuvent s’exécuter en parallèle pour réduire le temps total d’exécution. +- **Dépendances entre jobs** : Un job peut dépendre de l'achèvement d'un autre job. + +```yaml +jobs: + job1: + runs-on: ubuntu-latest + steps: + - name: Step 1 + run: echo "Job 1 Step 1" + + job2: + needs: job1 # Dépend de job1 + runs-on: ubuntu-latest + steps: + - name: Step 1 + run: echo "Job 2 Step 1" +``` + +### Actions + +Une **action** est une tâche individuelle que vous pouvez exécuter dans un job. GitHub Actions offre une large bibliothèque d’actions prédéfinies disponibles dans le [GitHub Marketplace](https://github.com/marketplace?type=actions). Vous pouvez également créer vos propres actions pour répondre à des besoins spécifiques. + +- **Actions de Marketplace** : Vous pouvez réutiliser des actions développées par d’autres, telles que `actions/checkout` pour vérifier le code ou `actions/setup-node` pour configurer Node.js. +- **Actions personnalisées** : Il est possible de créer des actions spécifiques à votre projet en utilisant des scripts Bash ou en créant des conteneurs Docker. Pour un exemple détaillé de création d'une action personnalisée, consultez le dépôt [Cedille-Actions-By-Example](https://github.com/ClubCedille/cedille-actions-by-example), qui illustre comment structurer et configurer une action comme **KubeSketcher**, une action permettant de générer des diagrammes d'architecture de namespaces Kubernetes. + +```yaml +steps: + - name: Checkout repository + uses: actions/checkout@v2 # Action prédéfinie depuis le Marketplace + + - name: Run custom script + run: ./my-custom-script.sh # Action personnalisée +``` + +### Runners + +Un **runner** est la machine qui exécute le job défini dans un workflow. GitHub offre des **runners hébergés** (machines préconfigurées par GitHub) et vous pouvez également configurer vos propres **runners auto-hébergés** si vous avez des besoins spécifiques en termes d'environnement d'exécution. + +- **Runners hébergés** : GitHub fournit des runners hébergés sous Linux, Windows, et macOS avec les outils CI/CD les plus utilisés déjà installés. +- **Runners auto-hébergés** : Si vous avez des besoins spécifiques en termes de matériel ou de sécurité, vous pouvez configurer vos propres runners en utilisant vos machines. + +```yaml +jobs: + build: + runs-on: ubuntu-latest # Utilise un runner hébergé sous Ubuntu + + custom-build: + runs-on: self-hosted # Utilise un runner auto-hébergé +``` + +--- + +## Différences entre GitHub Actions et d'autres outils CI/CD + +GitHub Actions se distingue par son intégration native avec GitHub, son flexibilité et la simplicité de sa configuration. Voici quelques différences majeures entre GitHub Actions et d'autres outils CI/CD tels que Jenkins, Travis CI ou CircleCI : + +### Intégration native avec GitHub + +Contrairement à d'autres outils CI/CD qui nécessitent une intégration externe à GitHub, GitHub Actions est directement intégré dans l’interface de GitHub. Cela signifie que vous pouvez gérer vos workflows CI/CD sans quitter GitHub, avec une gestion facile des triggers, secrets et permissions. + +### Flexibilité + +GitHub Actions est extrêmement flexible, vous permettant de définir vos workflows à l'aide d'un simple fichier YAML. Vous avez également accès à une grande variété d’actions prédéfinies dans le Marketplace, et la possibilité de créer vos propres actions. + +### Exécution dans GitHub + +L’exécution des workflows se fait directement dans GitHub à l’aide des runners hébergés. D'autres services, comme Jenkins, nécessitent souvent de configurer vos propres serveurs d'exécution. + +### Comparaison des Fonctionnalités + +| Outils CI/CD | GitHub Actions | Jenkins | Travis CI | CircleCI | +|------------------|----------------------|--------------------|--------------------|--------------------| +| **Intégration** | Native GitHub | Externe | Externe | Externe | +| **Configuration**| YAML dans le dépôt | Interface Jenkins | YAML dans le dépôt | YAML dans le dépôt | + + +| **Caractéristiques** | **GitHub Actions** | **Jenkins** | **CircleCI** | **GitLab CI/CD** | +|----------------------|--------------------|-------------------|---------------------|-----------------------| +| **Runners** | Hébergés / Auto-hébergés | Serveurs Jenkins | Hébergés uniquement | Hébergés / Auto-hébergés | +| **Marketplace** | Oui, avec actions | Plugins Jenkins | Oui | Oui | + +--- + +## Conclusion + +GitHub Actions est une plateforme puissante pour automatiser vos pipelines CI/CD directement au sein de GitHub. Grâce à son intégration transparente, sa flexibilité et ses nombreux outils disponibles, GitHub Actions simplifie l’automatisation des workflows pour les développeurs tout en restant adaptable aux besoins spécifiques de chaque projet. Que ce soit pour un petit projet ou pour une grande infrastructure DevOps, GitHub Actions constitue une solution robuste et évolutive. \ No newline at end of file diff --git a/wiki/docs/fr/onboarding/hands-on-labs/learn-github-actions/monitoring.md b/wiki/docs/fr/onboarding/hands-on-labs/learn-github-actions/monitoring.md new file mode 100644 index 0000000..8259c50 --- /dev/null +++ b/wiki/docs/fr/onboarding/hands-on-labs/learn-github-actions/monitoring.md @@ -0,0 +1,243 @@ +# Monitoring et Reporting avec GitHub Actions + +Le monitoring et le reporting dans GitHub Actions sont essentiels pour s'assurer que les workflows CI/CD fonctionnent correctement, et pour identifier rapidement les problèmes. Ce guide explique comment surveiller l'état des workflows, gérer les logs et diagnostics, générer des rapports de tests automatisés, visualiser les workflows dans l'interface GitHub, et notifier les équipes en cas d'échec ou de succès de builds. + +--- + +## 1. Monitoring des Workflows : État des Builds, Logs, et Diagnostics + +### 1.1. Surveillance de l'État des Builds + +GitHub Actions offre une interface utilisateur intuitive qui permet de surveiller l'état des builds en temps réel. Vous pouvez accéder à cette interface via l'onglet **Actions** dans votre dépôt GitHub. Chaque workflow déclenché génère un build dont l'état est visible (succès, échec, en cours). + +#### Statuts des Builds : +- **Vert (Succès)** : Tous les jobs dans le workflow ont été exécutés avec succès. +- **Rouge (Échec)** : Un ou plusieurs jobs ont échoué. +- **Jaune (En cours)** : Le workflow est en cours d'exécution. + +### 1.2. Accès aux Logs des Workflows + +Pour diagnostiquer des problèmes, GitHub Actions fournit des logs détaillés pour chaque étape d’un workflow. Ces logs incluent les sorties de commandes et les éventuelles erreurs rencontrées. + +#### Consulter les Logs : +1. Accédez à l'onglet **Actions** de votre dépôt. +2. Sélectionnez un workflow spécifique. +3. Cliquez sur un job pour afficher ses étapes. +4. Vous pouvez voir les logs pour chaque étape en cliquant sur le bouton d'expansion à côté du nom de l'étape. + +Les logs fournissent des informations précieuses telles que les messages de succès, d'erreurs, ou de débogage. Si un job échoue, les logs seront l'endroit où rechercher les erreurs. + +#### Exemple : Affichage des Logs après Échec d’un Workflow + +Lorsque qu’un workflow échoue, GitHub met en évidence les étapes problématiques. Vous pouvez afficher les détails des logs pour comprendre la cause de l'échec : + +```bash +Run npm install +npm ERR! code ENOENT +npm ERR! syscall open +npm ERR! path /build/package.json +npm ERR! errno -2 +``` + +### 1.3. Diagnostic des Problèmes + +GitHub Actions permet également de relancer un workflow avec des logs plus détaillés pour diagnostiquer les problèmes. Vous pouvez activer l'option de **debugging avancé** pour obtenir plus d'informations. + +#### Activer les Logs de Debugging : +1. Accédez à la page des logs du workflow. +2. Cliquez sur **Rerun jobs with debug logging** pour relancer le workflow en mode debug. +3. Les logs détaillés vous permettront de comprendre pourquoi le job a échoué. + +--- + +## 2. Générer des Rapports de Test Automatisé + +Les tests automatisés sont essentiels pour garantir la qualité du code. En combinant GitHub Actions avec des outils de tests comme JUnit, Mocha, ou Jest, vous pouvez générer et publier des rapports de tests dans vos workflows CI/CD. + +### 2.1. Exemple de Workflow avec Rapport de Tests JUnit + +JUnit est l'un des frameworks de test les plus courants pour les applications Java. Voici un exemple de workflow GitHub Actions qui exécute des tests JUnit et génère des rapports de test. + +```yaml +name: Run JUnit Tests + +on: [push] + +jobs: + test: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v2 + + - name: Set up JDK + uses: actions/setup-java@v2 + with: + java-version: '11' + + - name: Run tests with JUnit + run: ./gradlew test + + - name: Archive test results + uses: actions/upload-artifact@v2 + with: + name: junit-results + path: build/test-results/test/*.xml +``` + +#### Explication : +- **JUnit Tests** : Les tests JUnit sont exécutés avec la commande `./gradlew test`. +- **Archive test results** : Les résultats des tests JUnit au format XML sont sauvegardés en tant qu’artefacts, que vous pouvez consulter dans l'interface GitHub. + +### 2.2. Visualisation des Rapports de Test + +GitHub Actions ne fournit pas de visualisation native des rapports de tests, mais vous pouvez générer et visualiser les résultats des tests via des services tiers, ou exporter les résultats sous forme d'artefacts à télécharger. + +### 2.3. Générer des Rapports de Couverture de Code + +Vous pouvez intégrer des outils comme **Codecov** ou **Coveralls** dans vos workflows GitHub Actions pour générer des rapports de couverture de code. + +#### Exemple : Workflow avec Codecov + +```yaml +name: Codecov Test and Coverage + +on: + push: + branches: + - main + +jobs: + test: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v2 + + - name: Run tests + run: npm test -- --coverage + + - name: Upload coverage to Codecov + uses: codecov/codecov-action@v2 + with: + token: ${{ secrets.CODECOV_TOKEN }} +``` + +--- + +## 3. Visualisation des Workflows sur l'Interface GitHub + +GitHub offre une visualisation graphique des workflows CI/CD pour chaque dépôt. Cette vue permet aux développeurs de suivre le processus d'exécution, d'identifier les erreurs, et de comprendre les dépendances entre jobs. + +### 3.1. Interface de Visualisation des Workflows + +1. Accédez à l’onglet **Actions** dans votre dépôt. +2. Vous verrez une liste de workflows déclenchés récemment. +3. En cliquant sur un workflow spécifique, vous accédez à une vue graphique des jobs et de leur état (succès, échec, ou en attente). + +Chaque job est représenté dans un diagramme de flux, ce qui permet de visualiser facilement les étapes du pipeline et d'identifier rapidement les points de défaillance. + +### 3.2. Suivi des Artefacts + +Les artefacts générés par un workflow (fichiers de build, résultats de tests, logs) sont accessibles via l'interface des Actions. Vous pouvez les télécharger pour analyse ou les archiver pour référence future. + +--- + +## 4. Notifier les Équipes en Cas d'Échec ou de Succès de Build + +Les notifications automatiques sont essentielles pour alerter les équipes des succès ou des échecs dans les workflows CI/CD. GitHub Actions s'intègre à des outils de communication comme **Slack**, **Microsoft Teams**, ou des services d'email pour envoyer des alertes en fonction de l'état des builds. + +### 4.1. Notifier via Slack + +GitHub Actions permet d'envoyer des notifications Slack lorsqu'un workflow échoue ou réussit. Pour ce faire, vous pouvez utiliser une **Webhook Slack**. + +#### Exemple : Notification Slack pour un Workflow CI/CD + +1. Créez une **Webhook Slack** dans votre espace de travail. +2. Ajoutez le webhook à GitHub Actions en tant que secret (`SLACK_WEBHOOK_URL`). + +```yaml +name: Notify Slack on Build + +on: + push: + branches: + - main + +jobs: + notify: + runs-on: ubuntu-latest + + steps: + - name: Send Slack notification on success + if: success() + run: | + curl -X POST -H 'Content-type: application/json' \ + --data '{"text":"Build succeeded for ${{ github.repository }}"}' \ + ${{ secrets.SLACK_WEBHOOK_URL }} + + - name: Send Slack notification on failure + if: failure() + run: | + curl -X POST -H 'Content-type: application/json' \ + --data '{"text":"Build failed for ${{ github.repository }}"}' \ + ${{ secrets.SLACK_WEBHOOK_URL }} +``` + +#### Explication : +- **`if: success()`** et **`if: failure()`** : Ces conditions permettent d'envoyer une notification différente selon que le build a réussi ou échoué. +- **`curl`** : Utilisé pour envoyer une requête POST à Slack avec le message approprié. + +### 4.2. Notifications par Email + +GitHub Actions peut également envoyer des notifications par email en utilisant un service SMTP ou des outils tiers comme **SendGrid** ou **Mailgun**. + +#### Exemple : Workflow de Notification par Email + +```yaml +name: Notify on Build Status + +on: + push: + branches: + - main + +jobs: + notify: + runs-on: ubuntu-latest + + steps: + - name: Send email on success + if: success() + uses: dawidd6/action-send-mail@v2 + with: + server_address: smtp.gmail.com + server_port: 465 + username: ${{ secrets.EMAIL_USERNAME }} + password: ${{ secrets.EMAIL_PASSWORD }} + subject: "Build Success" + body: "The build for ${{ github.repository }} succeeded!" + to: "team@example.com" + + - name: Send email on failure + if: failure() + uses: dawidd6/action-send-mail@v2 + with: + server_address: smtp.gmail.com + server_port + +: 465 + username: ${{ secrets.EMAIL_USERNAME }} + password: ${{ secrets.EMAIL_PASSWORD }} + subject: "Build Failure" + body: "The build for ${{ github.repository }} failed!" + to: "team@example.com" +``` + +--- + +## Conclusion + +Le monitoring et le reporting sont des aspects cruciaux de la gestion des workflows CI/CD avec GitHub Actions. En utilisant les logs détaillés, les rapports de tests, et les outils de notification, vous pouvez surveiller de manière proactive l'état des builds et diagnostiquer rapidement les problèmes. L'intégration avec des outils comme Slack ou les services d'email permet de garder les équipes informées en temps réel, garantissant une résolution rapide des échecs de builds et une meilleure collaboration au sein des équipes de développement. diff --git a/wiki/docs/fr/onboarding/hands-on-labs/learn-github-actions/practices.md b/wiki/docs/fr/onboarding/hands-on-labs/learn-github-actions/practices.md new file mode 100644 index 0000000..4e6ea1e --- /dev/null +++ b/wiki/docs/fr/onboarding/hands-on-labs/learn-github-actions/practices.md @@ -0,0 +1,247 @@ +# Bonnes Pratiques et Patterns DevOps avec GitHub + +L'adoption des bonnes pratiques et des patterns DevOps est essentielle pour garantir des pipelines CI/CD robustes, évolutifs et efficaces dans les projets complexes. GitHub Actions, avec ses fonctionnalités d’automatisation, permet de structurer les workflows, de gérer plusieurs environnements, et de faciliter la collaboration d’équipe. Ce guide propose des stratégies et des pratiques exemplaires pour structurer les workflows, centraliser les configurations, gérer les environnements de développement, et collaborer efficacement via GitHub Actions. + +--- + +## 1. Structurer les Workflows pour des Projets Complexes + +Dans les projets complexes, il est essentiel de structurer vos workflows pour garantir un cycle de vie CI/CD fluide et facile à maintenir. Cela inclut la division des workflows en étapes spécifiques, la réutilisation des workflows et la gestion des dépendances entre les jobs. + +### 1.1. Diviser les Workflows en Étapes Claires + +Il est recommandé de diviser un workflow en plusieurs **jobs** et **steps**, en attribuant des responsabilités spécifiques à chaque job, telles que les tests, le build, ou le déploiement. Chaque job peut être exécuté de manière parallèle ou dépendante, ce qui permet de gagner en flexibilité. + +#### Exemple de Workflow Structuré + +```yaml +name: Complex Workflow + +on: + push: + branches: + - main + +jobs: + lint: + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v2 + + - name: Run linter + run: npm run lint + + test: + runs-on: ubuntu-latest + needs: lint # Le job 'test' dépend de 'lint' + steps: + - name: Checkout code + uses: actions/checkout@v2 + + - name: Run unit tests + run: npm test + + build: + runs-on: ubuntu-latest + needs: test # Le job 'build' dépend de 'test' + steps: + - name: Build application + run: npm run build + + deploy: + runs-on: ubuntu-latest + needs: build # Le job 'deploy' dépend de 'build' + steps: + - name: Deploy to production + run: ./deploy.sh +``` + +#### Explication : +- **Jobs dépendants** : Les jobs `test`, `build`, et `deploy` sont dépendants des jobs précédents. Cela assure qu’aucune étape de déploiement ne se fait avant la validation des tests ou du build. +- **Modularité** : Chaque job a un rôle précis, ce qui rend le workflow plus lisible et plus facile à maintenir. + +### 1.2. Modularisation des Workflows + +GitHub Actions permet d’appeler un workflow depuis un autre via `workflow_call`. Modulariser les workflows permet de réutiliser certaines parties du pipeline (tests, builds, etc.) dans différents projets, assurant ainsi une consistance dans la gestion des pipelines CI/CD à l'échelle de l'organisation. + +#### Exemple de Workflow Réutilisable + +```yaml +# .github/workflows/tests.yml +name: Reusable Tests Workflow + +on: workflow_call + +jobs: + run-tests: + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v2 + + - name: Install dependencies + run: npm install + + - name: Run tests + run: npm test +``` + +```yaml +# .github/workflows/main.yml +name: Main Workflow + +on: + push: + branches: + - main + +jobs: + tests: + uses: ./.github/workflows/tests.yml # Réutiliser le workflow de tests +``` + +### 1.3. Utiliser les Matrices pour Optimiser les Exécutions + +L'utilisation de **matrices** permet de tester différentes combinaisons d'environnements (OS, versions de langage, etc.) en parallèle, réduisant ainsi le temps total d'exécution du pipeline. + +#### Exemple d’Utilisation de Matrice + +```yaml +name: Matrix Build + +on: + push: + branches: + - main + +jobs: + build: + runs-on: ubuntu-latest + strategy: + matrix: + os: [ubuntu-latest, macos-latest, windows-latest] + node-version: [12, 14, 16] + + steps: + - name: Checkout repository + uses: actions/checkout@v2 + + - name: Setup Node.js + uses: actions/setup-node@v2 + with: + node-version: ${{ matrix.node-version }} + + - name: Install dependencies + run: npm install + + - name: Run tests + run: npm test +``` + +--- + +## 2. Utiliser des Fichiers de Configuration Centralisés + +Pour les projets complexes, il est souvent utile de centraliser la configuration des workflows afin d’assurer la cohérence entre différents pipelines et éviter la duplication. + +### 2.1. Centraliser les Secrets et Variables + +GitHub offre la possibilité de gérer les **secrets** et les **variables d’environnement** au niveau de l’organisation ou du dépôt. Cela permet de stocker des informations sensibles comme des clés API ou des identifiants dans un emplacement centralisé et sécurisé. + +#### Exemple : Utilisation de Secrets dans un Workflow + +```yaml +jobs: + deploy: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v2 + + - name: Deploy to AWS + env: + AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }} + AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }} + run: ./deploy.sh +``` + +### 2.2. Fichiers de Configuration Partagés + +GitHub Actions permet de créer des fichiers YAML de configuration partagée, ce qui permet de standardiser les processus CI/CD dans plusieurs projets. Ces fichiers peuvent inclure des scripts communs ou des workflows réutilisables pour différentes équipes ou dépôts. + +#### Exemple : Utilisation d'un Fichier Central de Configuration + +```yaml +# .github/workflows/shared-config.yml +name: Shared Config + +on: + workflow_call + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Install dependencies + run: npm install +``` + +--- + +## 3. Développement de Logiciels en Équipe avec GitHub Actions (PR Gating, Checks) + +GitHub Actions facilite la collaboration au sein des équipes de développement en automatisant les vérifications et en intégrant des contrôles sur les pull requests. + +### 3.1. Mise en Place de PR Gating + +Le **PR gating** consiste à empêcher la fusion de code dans une branche sans que certains tests ou checks aient été exécutés avec succès. Vous pouvez configurer des **checks obligatoires** qui doivent être validés avant de fusionner une pull request. + +#### Exemple : Workflow pour Valider une PR + +```yaml +name: PR Validation + +on: + pull_request: + branches: + - main + +jobs: + test: + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v2 + + - name: Install dependencies + run: npm install + + + + - name: Run tests + run: npm test +``` + +### 3.2. Checks Automatiques sur les Pull Requests + +GitHub permet de configurer des **checks** automatiques sur les pull requests, comme l'exécution de tests ou des vérifications de style de code. + +### 3.3. Politique de Branches Protégées + +Il est recommandé de protéger les branches critiques (comme `main` ou `production`) en configurant des **branches protégées**, qui empêchent les commits directs ou exigent l'exécution de workflows spécifiques avant la fusion. + +#### Exemple : Protéger la Branche `main` + +1. Accédez aux **Settings** du dépôt. +2. Allez dans **Branches**. +3. Ajoutez une règle de branche pour `main`. +4. Cochez l’option **Require status checks to pass before merging**. + +--- + +## Conclusion + +L'application de bonnes pratiques et de patterns DevOps avec GitHub Actions permet de structurer efficacement vos workflows CI/CD, centraliser les configurations et secrets, gérer plusieurs environnements, et collaborer de manière fluide au sein d'une équipe. L'utilisation d'outils comme les environnements, les workflows réutilisables, les branches protégées, et les checks de pull requests permet de construire des pipelines robustes et évolutifs pour des projets complexes tout en assurant la qualité et la sécurité du code. diff --git a/wiki/docs/fr/onboarding/hands-on-labs/learn-github-actions/registry.md b/wiki/docs/fr/onboarding/hands-on-labs/learn-github-actions/registry.md new file mode 100644 index 0000000..2ea78af --- /dev/null +++ b/wiki/docs/fr/onboarding/hands-on-labs/learn-github-actions/registry.md @@ -0,0 +1,228 @@ +# Utiliser GitHub Container Registry (GHCR) + +GitHub Container Registry (GHCR) est une fonctionnalité de GitHub Packages qui permet de stocker et gérer des images de conteneurs Docker aux côtés de vos projets GitHub. Le GHCR s’intègre parfaitement aux workflows CI/CD avec GitHub Actions, facilitant ainsi la création, le stockage, et le déploiement d’images Docker dans vos projets. + +--- + +## 1. Introduction à GitHub Container Registry + +GitHub Container Registry (GHCR) est un service de registre de conteneurs intégré à GitHub. Il permet aux développeurs de gérer des images de conteneurs Docker directement dans leurs dépôts GitHub. GHCR est conçu pour offrir plus de flexibilité dans la gestion des permissions, la visibilité des images et l'intégration avec les workflows GitHub Actions. + +### Exemple : Registre de Conteneurs de CEDILLE + +Pour un exemple concret de l'utilisation de GHCR, vous pouvez consulter le [registre de conteneurs de CEDILLE](https://github.com/orgs/ClubCedille/packages). Ce registre contient des images de conteneurs que le club utilise pour ses projets, intégrées aux workflows CI/CD et gérées directement via GitHub Actions. + +### Caractéristiques Principales de GHCR + +- **Stockage centralisé** : Le GHCR permet de stocker des images Docker aux côtés du code source de votre projet, simplifiant ainsi la gestion des versions et des déploiements. +- **Permissions flexibles** : Les images peuvent être privées, publiques ou contrôlées par des permissions personnalisées pour les utilisateurs et les équipes. +- **Intégration avec GitHub Actions** : Le GHCR s'intègre directement avec les workflows CI/CD de GitHub Actions, ce qui permet d'automatiser la création et le déploiement des images Docker. +- **Support de Docker et OCI** : GHCR prend en charge les images conformes aux normes Docker et Open Container Initiative (OCI). + +--- + +Voici comment vous pouvez intégrer cet exemple utilisé dans vos projets dockerisés dans la section sur **Pousser et Tirer des Images de Conteneurs dans GitHub Container Registry** : + +## 2. Pousser et Tirer des Images de Conteneurs dans GitHub Container Registry + +Le GitHub Container Registry permet aux utilisateurs de **pousser** (uploader) et **tirer** (download) des images Docker à partir de leurs projets GitHub, de manière similaire à d'autres registres Docker tels que Docker Hub. + +### Exemple : Workflow de Build et Push d'une Image Docker vers GHCR + +Dans les projets de CEDILLE, nous utilisons des workflows pour automatiser la construction et la publication d'images Docker dans le GitHub Container Registry. Voici un exemple concret du fichier [build-push-ghcr.yaml](https://github.com/ClubCedille/cedille-workflows/blob/master/.github/workflows/build-push-ghcr.yaml) utilisé pour construire et pousser des conteneurs Docker. + + +### Explication du Workflow [build-push-ghcr.yaml](https://github.com/ClubCedille/cedille-workflows/blob/master/.github/workflows/build-push-ghcr.yaml) : +- **workflow_call** : Ce workflow est conçu pour être réutilisé par d'autres workflows, permettant de spécifier le nom du conteneur, le contexte Docker, et le fichier Dockerfile. +- **Docker Buildx** : Utilisé pour construire des images multi-plateformes (par exemple, amd64, arm64). +- **Cache des couches Docker** : Les couches Docker sont mises en cache pour accélérer les builds. +- **Pousser les images Docker** : Les images sont poussées vers le registre GitHub (GHCR) avec des tags basés sur le commit ou la branche PR, et un tag `latest` est ajouté si le push se fait sur la branche `main` ou `master`. + +Cet exemple montre comment CEDILLE utilise GHCR pour gérer les images Docker de manière automatisée, avec des workflows CI/CD robustes. + +### 2.1. Authentification à GitHub Container Registry + +Pour interagir avec GHCR, vous devez vous authentifier auprès de GitHub en utilisant un jeton d'accès personnel (PAT). Ce jeton doit avoir les permissions suivantes : +- `read:packages` +- `write:packages` +- `delete:packages` (si vous souhaitez supprimer des images) +- `repo` (si vous poussez des images vers des dépôts privés) + +#### Création d’un Jeton d’Accès Personnel (PAT) + +1. Allez dans vos **Settings** GitHub. +2. Sous **Developer settings**, cliquez sur **Personal access tokens**. +3. Créez un nouveau jeton avec les permissions mentionnées ci-dessus. + +### 2.2. Pousser une Image Docker vers GitHub Container Registry + +Pour pousser une image Docker dans le GHCR, vous devez suivre les étapes suivantes : + +#### 1. Connexion à GitHub Container Registry + +Utilisez la commande Docker suivante pour vous authentifier auprès de GHCR à l’aide de votre jeton d’accès personnel (PAT) : + +```bash +echo $GHCR_PAT | docker login ghcr.io -u --password-stdin +``` + +- **`$GHCR_PAT`** est votre jeton d’accès personnel (PAT). +- **``** est votre nom d'utilisateur GitHub. + +#### 2. Construire une Image Docker + +Créez une image Docker à partir de votre projet. Par exemple, si vous avez un `Dockerfile` dans le répertoire racine de votre projet : + +```bash +docker build -t ghcr.io//: . +``` + +- **``** : Votre nom d’utilisateur GitHub. +- **``** : Le nom de l’image Docker. +- **``** : Un tag pour identifier la version de l’image (ex : `v1.0`, `latest`). + +#### 3. Pousser l'Image Docker vers GHCR + +Une fois l’image construite, utilisez la commande suivante pour la pousser vers GHCR : + +```bash +docker push ghcr.io//: +``` + +### 2.3. Tirer une Image Docker depuis GitHub Container Registry + +Pour tirer une image Docker stockée dans GHCR, vous devez d’abord vous authentifier, puis exécuter la commande de tirage (pull). + +#### 1. Authentification + +Si vous n'êtes pas encore connecté à GHCR, vous pouvez vous authentifier comme suit : + +```bash +echo $GHCR_PAT | docker login ghcr.io -u --password-stdin +``` + +#### 2. Tirer l'Image Docker + +Utilisez la commande `docker pull` pour télécharger une image depuis GHCR : + +```bash +docker pull ghcr.io//: +``` + +--- + +## 3. Intégration des Images avec les Workflows GitHub Actions + +GitHub Actions s'intègre parfaitement avec GitHub Container Registry, vous permettant de créer des workflows CI/CD qui incluent la construction, le test, et le déploiement automatisé d'images Docker. + +### Exemple de Workflow pour Construire et Pousser une Image Docker vers GHCR + +Voici un exemple de workflow GitHub Actions qui construit une image Docker à partir d’un dépôt, puis la pousse automatiquement dans le GHCR. + +```yaml +name: Build and Push Docker Image to GHCR + +on: + push: + branches: + - main + +jobs: + build: + runs-on: ubuntu-latest + + steps: + # Étape 1 : Checkout du code source + - name: Checkout repository + uses: actions/checkout@v2 + + # Étape 2 : Authentification à GHCR + - name: Log in to GitHub Container Registry + run: echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u ${{ github.actor }} --password-stdin + + # Étape 3 : Construire l'image Docker + - name: Build Docker image + run: docker build -t ghcr.io/${{ github.repository }}/my-app:latest . + + # Étape 4 : Pousser l'image vers GHCR + - name: Push Docker image to GHCR + run: docker push ghcr.io/${{ github.repository }}/my-app:latest +``` + +### Explication des Étapes : + +1. **Checkout repository** : Cette étape récupère le code source du dépôt. +2. **Log in to GitHub Container Registry** : Se connecte à GHCR en utilisant le jeton d'accès GitHub (`GITHUB_TOKEN`). +3. **Build Docker image** : Construit une image Docker à partir du Dockerfile dans le répertoire racine du projet. +4. **Push Docker image to GHCR** : Pousse l'image Docker construite vers GHCR, en utilisant le chemin `ghcr.io//`. + +### Exemple de Workflow pour Tirer une Image et Déployer avec Docker + +Voici un exemple de workflow GitHub Actions qui tire une image Docker depuis GHCR et la déploie sur une machine cible (par exemple, un serveur de production). + +```yaml +name: Pull and Deploy Docker Image from GHCR + +on: + workflow_dispatch: + +jobs: + deploy: + runs-on: ubuntu-latest + + steps: + # Authentification à GHCR + - name: Log in to GitHub Container Registry + run: echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u ${{ github.actor }} --password-stdin + + # Tirer l'image Docker + - name: Pull Docker image from GHCR + run: docker pull ghcr.io/${{ github.repository }}/my-app:latest + + # Démarrer le conteneur Docker + - name: Run Docker container + run: docker run -d -p 8080:80 ghcr.io/${{ github.repository }}/my-app:latest +``` + +--- + +## 4. Contrôle d’Accès et Permissions sur les Registres + +L'un des avantages majeurs de GitHub Container Registry est la gestion fine des **permissions d'accès**. Vous pouvez contrôler qui a accès à vos images de conteneurs, et définir des autorisations spécifiques pour chaque image ou dépôt. + +### 4.1 Permissions sur les Dépôts + +Les permissions pour accéder aux images hébergées dans GHCR dépendent des permissions d'accès au dépôt associé : +- **Dépôts Publics** : Les images dans les dépôts publics peuvent être consultées et tirées par tout utilisateur GitHub. +- **Dépôts Privés** : Les images dans les dépôts privés sont accessibles uniquement aux personnes ou équipes ayant les permissions appropriées sur le dépôt. + +### 4.2 Permissions pour les Images Publiques et Privées + +Vous pouvez définir des permissions spécifiques pour les images GHCR, indépendamment du dépôt dans lequel elles sont hébergées. Les images peuvent être : +- **Privées** : Seuls les utilisateurs ou équipes ayant reçu des accès peuvent tirer ou pousser des images. +- **Publiques** : N’importe qui peut tirer l’image. + +#### Rendre une Image Publique ou Privée + +1. Allez sur la page **Packages** du dépôt GitHub. +2. Sélectionnez l’image Docker que vous souhaitez modifier. +3. Cliquez sur **Package settings**. +4. Modifiez la visibilité de l'image à **Public** ou **Private**. + +### 4.3 Gérer les Permissions pour les Utilisateurs et Équipes + +Vous pouvez attribuer des permissions de lecture ou d'écriture sur vos images à des utilisateurs spécifiques ou à des équipes au sein de votre organisation GitHub. Cela permet de restreindre l'accès aux images sensibles, tout en facilitant la collaboration au sein de l'équipe. + +#### Accorder l'Accès à un Utilisateur ou une Équipe + +1. Allez dans les **Settings** du dépôt GitHub contenant l'image. +2. Sous **Manage access**, ajoutez les utilisateurs ou les équipes auxquels vous souhaitez donner accès. +3. Attribuez des rôles spécifiques (lecture, écriture, ou admin) selon le niveau d'accès souhaité. + +--- + +## Conclusion + +GitHub Container Registry (GHCR) est une solution puissante et flexible pour gérer vos images Docker directement au sein de GitHub. En vous permettant de pousser, tirer et déployer des images de conteneurs dans vos workflows CI/CD via GitHub Actions, GHCR s’intègre parfaitement dans les pipelines de développement modernes. De plus, avec ses options de contrôle d'accès avancées, vous pouvez gérer les permissions de manière granulaire, assurant ainsi la sécurité de vos images. + +Avec ces outils, vous êtes désormais prêt à utiliser GHCR pour optimiser vos workflows CI/CD, améliorer la collaboration, et simplifier la gestion des images Docker. diff --git a/wiki/docs/fr/onboarding/hands-on-labs/learn-github-actions/security.md b/wiki/docs/fr/onboarding/hands-on-labs/learn-github-actions/security.md new file mode 100644 index 0000000..7bd2f3f --- /dev/null +++ b/wiki/docs/fr/onboarding/hands-on-labs/learn-github-actions/security.md @@ -0,0 +1,238 @@ +# Gestion de la Sécurité et des Permissions dans GitHub Actions + +La sécurité est une composante essentielle de tout pipeline CI/CD. GitHub Actions offre des fonctionnalités intégrées pour gérer les informations sensibles, contrôler les accès aux workflows, et garantir la sécurité de vos dépendances logicielles. Dans ce document, nous allons explorer comment utiliser GitHub Secrets pour gérer les informations sensibles, définir des permissions sur les workflows et analyser les dépendances avec Dependabot. + +--- + +## 1. Utilisation de GitHub Secrets pour Gérer les Informations Sensibles + +Les secrets dans GitHub sont utilisés pour stocker des informations sensibles telles que des clés API, des mots de passe, ou des jetons d'accès, qui sont nécessaires pour vos workflows mais qui ne doivent pas être exposées dans le code source. + +### 1.1. Qu'est-ce que GitHub Secrets ? + +Les **GitHub Secrets** sont des variables sécurisées qui sont chiffrées et stockées par GitHub. Elles peuvent être utilisées dans vos workflows pour passer des informations sensibles sans les exposer dans les logs ou dans les fichiers de configuration. Par exemple, les secrets sont couramment utilisés pour se connecter à des services tiers comme AWS, Docker, ou Slack. + +### 1.2. Créer un Secret dans GitHub + +1. **Accédez aux Settings** du dépôt ou de l’organisation. +2. Sous **Secrets and variables**, cliquez sur **Actions**. +3. Sélectionnez **New repository secret** (pour un dépôt) ou **New organization secret** (pour un secret partagé entre plusieurs dépôts). +4. Entrez un nom pour le secret (par exemple, `AWS_ACCESS_KEY_ID`). +5. Entrez la valeur du secret, puis cliquez sur **Add secret**. + +### 1.3. Utiliser les Secrets dans un Workflow GitHub Actions + +Une fois les secrets créés, ils peuvent être utilisés dans vos workflows en les appelant avec la syntaxe `${{ secrets.NOM_DU_SECRET }}`. + +#### Exemple : Utilisation de Secrets pour l'Authentification AWS + +```yaml +name: Deploy to AWS + +on: + push: + branches: + - main + +jobs: + deploy: + runs-on: ubuntu-latest + + steps: + # Checkout du code source + - name: Checkout repository + uses: actions/checkout@v2 + + # Configuration des identifiants AWS en utilisant les secrets + - name: Configure AWS credentials + uses: aws-actions/configure-aws-credentials@v1 + with: + aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }} + aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }} + aws-region: us-east-1 + + # Déploiement sur AWS + - name: Deploy to S3 + run: aws s3 sync ./build s3://my-app-bucket +``` + +### 1.4. Meilleures Pratiques pour Utiliser des Secrets + +- **Limiter l'accès aux secrets** : Seuls les utilisateurs ayant besoin de voir ou de gérer les secrets doivent y avoir accès. +- **Utiliser des secrets au niveau de l'organisation** : Si vous travaillez avec plusieurs dépôts, vous pouvez définir des secrets au niveau de l'organisation et les partager entre plusieurs dépôts. +- **Chiffrer les secrets** : Ne jamais inclure des informations sensibles directement dans votre code ou vos workflows. Utilisez toujours des secrets chiffrés. +- **Rotation des secrets** : Modifiez régulièrement vos secrets pour renforcer la sécurité. + +--- + +## 2. Permissions des Workflows et Gestion des Droits d'Accès + +La sécurité des workflows dans GitHub Actions repose également sur la gestion des **permissions d'accès** et des **droits d'exécution** des workflows. GitHub permet de contrôler les actions qu’un workflow peut effectuer et de limiter l'accès à certains événements et utilisateurs. + +### 2.1. Permissions des Workflows + +GitHub permet de configurer les **permissions par défaut** qu’un workflow peut utiliser. Vous pouvez définir des permissions pour chaque workflow ou globalement pour tout le dépôt. + +#### Configurer les Permissions des Workflows + +Les permissions peuvent être définies à deux niveaux : +1. **Globale (pour tout le dépôt)**. +2. **Spécifique à un workflow**. + +#### 2.1.1. Permissions Globales pour un Dépôt + +Vous pouvez configurer les permissions par défaut d’un dépôt sous **Settings > Actions > Workflow permissions**. Deux options principales sont disponibles : +- **Read repository content** : Limite les actions aux lectures de dépôt (option la plus sécurisée). +- **Read and write permissions** : Donne aux actions la permission de lire et de modifier le dépôt. + +#### 2.1.2. Permissions dans un Workflow Spécifique + +Dans un workflow spécifique, vous pouvez restreindre les permissions au niveau des **jobs** ou des **étapes** (steps). + +##### Exemple : Définir les Permissions dans un Workflow + +```yaml +name: Build and Deploy + +on: + push: + branches: + - main + +permissions: + contents: read # Limite l'accès au dépôt en lecture seule + packages: write # Autorise l'écriture dans GitHub Packages + +jobs: + build: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v2 +``` + +Dans cet exemple : +- Le workflow a la permission de **lire** le contenu du dépôt. +- Le workflow peut **écrire** dans GitHub Packages pour publier des artefacts ou des images Docker. + +### 2.2. Contrôle des Droits d'Accès aux Workflows + +Les permissions des workflows peuvent également être contrôlées par l'organisation ou les propriétaires du dépôt. Voici quelques bonnes pratiques pour sécuriser les workflows : + +- **Exiger des approbations pour certains workflows** : Pour certains événements critiques (comme un déploiement en production), configurez des workflows de manière à exiger une approbation manuelle avant leur exécution. + +#### Exemple : Exiger une Approbation Manuelle pour Déployer + +```yaml +name: Production Deployment + +on: + workflow_dispatch: + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - name: Await approval + uses: actions/manual-approval@v2 + with: + approver: "team-lead" + - name: Deploy application + run: ./deploy.sh +``` + +- **Limiter l’accès aux secrets** : N’accordez des permissions d'accès aux secrets qu’aux workflows et jobs qui en ont réellement besoin. +- **Utiliser des branches protégées** : Restreindre les exécutions automatiques de workflows sur les branches de production pour éviter des modifications non autorisées. + +--- + +## 3. Scan de Sécurité des Dépendances avec Dependabot et Renovate + +Dependabot est un service intégré à GitHub qui analyse les dépendances de vos projets et identifie les vulnérabilités de sécurité. Il propose des mises à jour automatiques pour corriger ces vulnérabilités, améliorant ainsi la sécurité globale de vos applications. + +Cependant, dans nos dépôts, nous utilisons principalement **Renovate**, un autre outil open-source de gestion des dépendances. Comme Dependabot, Renovate scanne les dépendances et propose des mises à jour automatisées. Toutefois, **Renovate** offre une flexibilité plus avancée avec des options de configuration étendues pour ajuster la fréquence des mises à jour, définir des stratégies de versioning spécifiques, et prendre en charge un large éventail de langages et de gestionnaires de paquets. + +### Pourquoi Utiliser Renovate ? +- **Configuration Avancée** : Renovate permet une personnalisation fine des stratégies de mise à jour, telles que les mises à jour groupées, les plages de versions spécifiques ou encore la fréquence des vérifications. +- **Support Étendu** : Il supporte une large variété de gestionnaires de paquets, ce qui en fait un choix idéal pour des projets multi-technologies. +- **Facilité d'Intégration** : Comme Dependabot, Renovate s'intègre directement dans vos workflows GitHub et génère des pull requests automatiques avec les mises à jour de dépendances. + +### Exemple de Fichier de Configuration Renovate +Dans nos projets, voici un exemple basique de configuration Renovate : + +```json +{ + "extends": [ + "config:base" + ], + "packageRules": [ + { + "matchPackagePatterns": ["*"], + "groupName": "All Dependencies", + "groupSlug": "all-dependencies" + } + ], + "schedule": ["every weekend"] +} +``` + +Dans cet exemple : +- **extends** : Utilise la configuration de base fournie par Renovate. +- **packageRules** : Regroupe toutes les dépendances dans une seule mise à jour groupée. +- **schedule** : Les mises à jour sont planifiées pour être effectuées tous les week-ends. + +Renovate et Dependabot sont tous deux de puissants outils pour maintenir la sécurité et la mise à jour des dépendances dans vos projets, mais Renovate est souvent préféré pour sa flexibilité et sa configuration avancée, comme nous le faisons dans nos répertoires. + +### 3.1. Qu'est-ce que Dependabot ? + +**Dependabot** scanne régulièrement les dépendances de vos projets et détecte les vulnérabilités connues dans les bibliothèques que vous utilisez. Lorsqu'une vulnérabilité est détectée, Dependabot crée automatiquement une **pull request** proposant une mise à jour vers une version plus sécurisée. + +### 3.2. Activer Dependabot pour le Scan de Sécurité + +1. Accédez aux **Settings** de votre dépôt GitHub. +2. Sous **Security & Analysis**, activez **Dependabot alerts** et **Dependabot security updates**. + +GitHub scanne ensuite automatiquement les dépendances de votre projet et vous avertit en cas de vulnérabilités. + +### 3.3. Mises à Jour Automatiques avec Dependabot + +Dependabot peut générer automatiquement des pull requests pour mettre à jour vos dépendances lorsque des mises à jour de sécurité sont disponibles. Ces pull requests peuvent ensuite être révisées et fusionnées pour garantir que votre projet reste sécurisé. + +#### Exemple : Fichier de Configuration Dependabot + +Dependabot peut être configuré via un fichier `.github/dependabot.yml` qui définit les dépendances à surveiller et la fréquence de mise à jour. + +```yaml +version: 2 +updates: + - package-ecosystem: "npm" # Gérer les dépendances npm + directory: "/" # Répertoire contenant le fichier package.json + schedule: + interval: "daily" # Vérification des mises à jour chaque jour + - package-ecosystem: "docker" # Gérer les images Docker + directory: "/" # Répertoire contenant le fichier Dockerfile + schedule: + interval: "weekly" # Vérification des mises à jour chaque semaine +``` + +### 3.4. Analyse des Vulnérabilités dans le Code et les Dépendances + +Dependabot se connecte à une base de données de vulnérabilités connues pour vérifier les packages utilisés dans vos projets. Lorsqu’une vulnérabilité est trouvée : +- Vous recevez une alerte **Dependabot alert** dans l’onglet **Security** de votre dépôt. +- Dependabot peut automatiquement créer une **pull request** pour vous proposer une mise à jour vers une version non vulnérable. + +### 3.5. Suivi des Mises à Jour de Sécurité + +Dependabot vous permet de : + +- Suivre l’historique des vulnérabilités et des correctifs. +- Mettre en œuvre des mises à jour automatiques pour que votre projet utilise toujours des versions sécurisées des dépendances. + +--- + +## Conclusion + +La gestion de la sécurité et des permissions dans GitHub Actions est essentielle pour garantir la confidentialité, l'intégrité et la sécurité de vos pipelines CI/CD. En utilisant GitHub Secrets, vous pouvez protéger les informations sensibles telles que les clés API et les identifiants. En configurant correctement les permissions des workflows et des accès aux secrets, vous pouvez limiter les risques de compromission. De plus, avec Dependabot, vous avez un outil puissant pour surveiller et corriger automatiquement les vulnérabilités dans vos dépendances, contribuant ainsi à renforcer la sécurité globale de vos projets. + +Ces outils et pratiques vous permettent de construire des workflows robustes et sécurisés, tout en respectant les meilleures pratiques en matière de gestion de la sécurité et des permissions. diff --git a/wiki/docs/fr/onboarding/hands-on-labs/learn-github-actions/use-case.md b/wiki/docs/fr/onboarding/hands-on-labs/learn-github-actions/use-case.md new file mode 100644 index 0000000..6453e92 --- /dev/null +++ b/wiki/docs/fr/onboarding/hands-on-labs/learn-github-actions/use-case.md @@ -0,0 +1,333 @@ +# Cas Pratiques : DevOps avec GitHub Actions + +GitHub Actions est un outil puissant pour implémenter des pipelines CI/CD dans un environnement DevOps. Il permet d'automatiser l'intégralité du cycle de vie du développement, incluant le build, les tests, le déploiement, et l'intégration avec des services de cloud et des conteneurs Docker. Ce guide présente des cas pratiques détaillés pour mettre en œuvre des pipelines CI/CD robustes en utilisant GitHub Actions, Docker, et AWS. + +--- + +## 1. Déploiement d’une Application Node.js avec Docker et GitHub Actions + +Dans ce cas pratique, nous allons voir comment automatiser le déploiement d'une application Node.js conteneurisée à l'aide de Docker et GitHub Actions. + +### 1.1. Préparer le Dockerfile + +Commencez par créer un fichier `Dockerfile` pour conteneuriser l'application Node.js. + +#### Exemple de Dockerfile : + +```dockerfile +# Utiliser une image Node.js de base +FROM node:14 + +# Créer un répertoire de travail dans le conteneur +WORKDIR /app + +# Copier package.json et installer les dépendances +COPY package*.json ./ +RUN npm install + +# Copier le reste des fichiers de l'application +COPY . . + +# Exposer le port de l'application +EXPOSE 3000 + +# Démarrer l'application +CMD ["npm", "start"] +``` + +### 1.2. Créer un Workflow GitHub Actions pour Build et Déploiement + +Ensuite, configurez GitHub Actions pour automatiser la création et le déploiement de cette application sur un serveur ou un service Docker. Le workflow suivant va construire l'image Docker et la pousser dans le **GitHub Container Registry** (GHCR). + +#### Exemple de Workflow : Build et Push Docker Image + +```yaml +name: Build and Deploy Node.js Docker App + +on: + push: + branches: + - main # Déclenche le workflow uniquement sur les pushes vers la branche 'main' + +jobs: + build: + runs-on: ubuntu-latest + + steps: + # Étape 1 : Checkout du code source + - name: Checkout code + uses: actions/checkout@v2 + + # Étape 2 : Authentification à GitHub Container Registry (GHCR) + - name: Log in to GitHub Container Registry + run: echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u ${{ github.actor }} --password-stdin + + # Étape 3 : Construire l'image Docker + - name: Build Docker image + run: docker build -t ghcr.io/${{ github.repository }}/node-app:latest . + + # Étape 4 : Pousser l'image vers GHCR + - name: Push Docker image to GitHub Container Registry + run: docker push ghcr.io/${{ github.repository }}/node-app:latest +``` + +### 1.3. Déploiement de l'Application + +Vous pouvez maintenant déployer l'image Docker sur un serveur de production ou un service comme **Docker Swarm**, **Kubernetes**, ou **AWS ECS**. + +--- + +## 2. CI/CD pour une Application Python Hébergée sur AWS avec Intégration Docker + +Dans ce cas, nous allons mettre en place un pipeline CI/CD pour une application Python conteneurisée, hébergée sur **AWS Elastic Beanstalk**, en intégrant Docker dans le processus. + +### 2.1. Préparer le Dockerfile pour l'Application Python + +Créez un fichier `Dockerfile` pour conteneuriser l'application Python. Cet exemple montre un Dockerfile pour une application Flask. + +#### Exemple de Dockerfile : + +```dockerfile +# Utiliser une image Python de base +FROM python:3.9 + +# Définir le répertoire de travail +WORKDIR /app + +# Copier le fichier requirements.txt et installer les dépendances +COPY requirements.txt . +RUN pip install -r requirements.txt + +# Copier le reste du code source +COPY . . + +# Exposer le port de l'application +EXPOSE 5000 + +# Démarrer l'application Flask +CMD ["python", "app.py"] +``` + +### 2.2. Configurer un Workflow GitHub Actions pour AWS Elastic Beanstalk + +Le workflow suivant est conçu pour construire l'image Docker et la déployer automatiquement sur AWS Elastic Beanstalk. + +#### Exemple de Workflow : Build et Déploiement sur AWS Elastic Beanstalk + +```yaml +name: Build and Deploy to AWS Elastic Beanstalk + +on: + push: + branches: + - main + +jobs: + deploy: + runs-on: ubuntu-latest + + steps: + # Étape 1 : Checkout du code source + - name: Checkout code + uses: actions/checkout@v2 + + # Étape 2 : Authentification AWS + - name: Configure AWS credentials + uses: aws-actions/configure-aws-credentials@v1 + with: + aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }} + aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }} + aws-region: us-east-1 + + # Étape 3 : Construire l'image Docker + - name: Build Docker image + run: docker build -t my-python-app:latest . + + # Étape 4 : Déployer l'application sur Elastic Beanstalk + - name: Deploy to Elastic Beanstalk + run: | + zip -r app.zip . + aws elasticbeanstalk create-application-version --application-name MyPythonApp --version-label latest --source-bundle S3Bucket=my-app-bucket,S3Key=app.zip + aws elasticbeanstalk update-environment --environment-name MyPythonApp-env --version-label latest +``` + +--- + +## 3. Automatisation d’une Chaîne DevOps Complète : Tests, Build, Déploiement + +Ce cas pratique montre comment configurer une chaîne DevOps complète, incluant les tests, la construction, et le déploiement automatisés d'une application. + +### 3.1. Workflow Complet avec Tests Unitaires, Build et Déploiement + +Le workflow suivant automatise l'intégralité du processus de tests, de build, et de déploiement pour une application Node.js hébergée sur **Heroku**. + +#### Exemple de Workflow Complet : + +```yaml +name: CI/CD Pipeline for Node.js App + +on: + push: + branches: + - main + +jobs: + test: + runs-on: ubuntu-latest + + steps: + # Étape 1 : Checkout du code source + - name: Checkout code + uses: actions/checkout@v2 + + # Étape 2 : Installer les dépendances + - name: Install dependencies + run: npm install + + # Étape 3 : Exécuter les tests unitaires + - name: Run unit tests + run: npm test + + build: + runs-on: ubuntu-latest + needs: test # Exécute ce job après le job 'test' + + steps: + # Étape 1 : Checkout du code source + - name: Checkout code + uses: actions/checkout@v2 + + # Étape 2 : Construire l'application + - name: Build application + run: npm run build + + deploy: + runs-on: ubuntu-latest + needs: build # Exécute ce job après le job 'build' + + steps: + # Étape 1 : Checkout du code source + - name: Checkout code + uses: actions/checkout@v2 + + # Étape 2 : Authentification Heroku + - name: Login to Heroku + run: echo "${{ secrets.HEROKU_API_KEY }}" | docker login --username=_ --password-stdin registry.heroku.com + + # Étape 3 : Déployer l'image sur Heroku + - name: Deploy to Heroku + run: | + docker build -t registry.heroku.com/my-app/web . + docker push registry.heroku.com/my-app/web + heroku container:release web --app my-app +``` + +#### Explication : +- **Tests** : Ce workflow exécute les tests unitaires à l'aide de `npm test`. +- **Build** : Une fois les tests réussis, l'application est construite avec `npm run build`. +- **Déploiement** : Si le build réussit, l'application est déployée sur Heroku en utilisant des images Docker. + +### 3.2. Notification de Succès ou Échec + +Vous pouvez ajouter des notifications Slack pour alerter l’équipe en cas de succès ou d'échec du pipeline CI/CD. + +#### Exemple : Notification Slack après Build + +```yaml +name: CI/CD Pipeline with Slack Notifications + +on: + push: + branches: + - main + +jobs: + build-and-deploy: + runs-on: ubuntu-latest + + steps: + # Étape 1 : Checkout du code source + - name: Checkout code + uses: actions/checkout@v2 + + # Étape 2 : Installer les dépendances + - name: Install dependencies + run: npm install + + # Étape 3 : Construire l'application + - name: Build application + run: npm run build + + # Étape 4 : Déployer l'application + - name: Deploy application + run: ./deploy.sh + + notify: + runs-on: ubuntu-latest + + + needs: build-and-deploy + + steps: + - name: Send Slack notification on success + if: success() + run: | + curl -X POST -H 'Content-type: application/json' \ + --data '{"text":"Build succeeded for ${{ github.repository }}!"}' \ + ${{ secrets.SLACK_WEBHOOK_URL }} + + - name: Send Slack notification on failure + if: failure() + run: | + curl -X POST -H 'Content-type: application/json' \ + --data '{"text":"Build failed for ${{ github.repository }}!"}' \ + ${{ secrets.SLACK_WEBHOOK_URL }} +``` + +--- + +## 4. Exemple de Collaboration avec des Équipes : Organisations et Équipes GitHub + +Dans un environnement DevOps, il est crucial de collaborer efficacement au sein des équipes et des organisations sur GitHub. + +### 4.1. Gestion des Équipes GitHub + +GitHub permet de gérer des équipes au sein d'une organisation. Cela permet de : + +- **Définir des permissions** : Vous pouvez attribuer des rôles d'accès spécifiques (lecture, écriture, admin) à différents membres ou équipes. +- **Partager des secrets** : Les secrets à l’échelle de l’organisation peuvent être utilisés dans plusieurs dépôts, facilitant la gestion de l'authentification partagée pour des services externes (comme AWS, Docker, etc.). + + +### 4.2. Exemple de Workflow Partagé entre Plusieurs Dépôts + +Vous pouvez créer des workflows réutilisables au niveau de l’organisation pour les partager entre plusieurs dépôts. + +#### Exemple : Workflow Réutilisable pour le Build + +```yaml +name: Reusable Build Workflow + +on: workflow_call + +jobs: + build: + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v2 + + - name: Install dependencies + run: npm install + + - name: Build application + run: npm run build +``` + +Dans chaque dépôt, vous pouvez ensuite appeler ce workflow réutilisable pour standardiser le processus de build dans toute l’organisation. + +--- + +## Conclusion + +Ces cas pratiques montrent comment GitHub Actions peut être utilisé pour automatiser le cycle de vie DevOps complet. Que vous travailliez avec des applications Node.js, Python, Docker, ou AWS, GitHub Actions vous permet de construire des pipelines CI/CD robustes, automatisés et scalables. En intégrant les tests, les builds, les notifications, et la gestion collaborative via les équipes GitHub, vous pouvez facilement gérer et optimiser vos processus DevOps, tout en assurant une collaboration fluide au sein de votre organisation. diff --git a/wiki/docs/fr/onboarding/hands-on-labs/learn-github-actions/workflows.md b/wiki/docs/fr/onboarding/hands-on-labs/learn-github-actions/workflows.md new file mode 100644 index 0000000..a82afcd --- /dev/null +++ b/wiki/docs/fr/onboarding/hands-on-labs/learn-github-actions/workflows.md @@ -0,0 +1,355 @@ +# Créer des Workflows Personnalisés avec GitHub Actions + +GitHub Actions vous permet de créer des workflows personnalisés adaptés à vos besoins spécifiques en matière d'intégration continue (CI) et de déploiement continu (CD). Les workflows sont définis dans des fichiers YAML et peuvent être utilisés pour automatiser un large éventail de tâches, du test de code au déploiement en production. + +--- + +## 1. Définir des Jobs et des Étapes (Steps) + +Un workflow dans GitHub Actions est composé de plusieurs **jobs**, et chaque **job** contient une série d'**étapes** (steps). Un job est un ensemble de tâches qui s'exécute sur une machine donnée, tandis que chaque étape représente une commande ou une action spécifique exécutée dans ce job. + +### Structure d’un Job + +Un **job** doit définir : +- L’environnement sur lequel il s’exécute (`runs-on`). +- Les **étapes** à exécuter. +- Optionnellement, des dépendances entre jobs ou des conditions d'exécution. + +### Exemple de Définition de Jobs et d'Étapes + +```yaml +name: Custom Workflow + +on: [push] + +jobs: + build: + runs-on: ubuntu-latest # Définit l'environnement (une machine Ubuntu hébergée) + + steps: + - name: Checkout code # Étape 1 : Récupérer le code source du dépôt + uses: actions/checkout@v2 + + - name: Install dependencies # Étape 2 : Installer les dépendances + run: npm install + + - name: Run tests # Étape 3 : Exécuter les tests + run: npm test + + deploy: + runs-on: ubuntu-latest + + steps: + - name: Deploy application + run: ./deploy.sh +``` + +### Détails : +- **`jobs:`** : La section `jobs` contient tous les jobs du workflow. Chaque job est défini par un identifiant unique (ici, `build` et `deploy`). +- **`runs-on:`** : Spécifie l'environnement dans lequel le job s'exécute (par exemple, `ubuntu-latest`). +- **`steps:`** : Chaque job contient une ou plusieurs étapes, qui peuvent exécuter des commandes shell (`run`) ou utiliser des actions existantes (`uses`). + +--- + +## 2. Utiliser des Actions Préconstruites depuis le GitHub Marketplace + +GitHub Actions dispose d'un **Marketplace** où vous pouvez trouver et utiliser des actions préconstruites créées par la communauté. Ces actions peuvent être facilement intégrées dans vos workflows pour effectuer des tâches courantes telles que vérifier le code, configurer des environnements, ou déployer des applications. + +### Comment Utiliser des Actions depuis le Marketplace + +Pour utiliser une action depuis le Marketplace, vous pouvez l'intégrer dans vos étapes (`steps`) en utilisant la syntaxe suivante : +```yaml +uses: @ +``` +Voici un exemple d'utilisation de l'action `actions/checkout` pour récupérer le code source d'un dépôt. + +#### Exemple : + +```yaml +steps: + - name: Checkout code + uses: actions/checkout@v2 # Utilise l'action pour cloner le dépôt +``` + +L'action `actions/checkout` est couramment utilisée pour cloner le dépôt sur la machine où les jobs s'exécutent. Vous pouvez trouver des centaines d'autres actions sur le [GitHub Marketplace](https://github.com/marketplace?type=actions), comme : +- **`actions/setup-node`** : Configurer un environnement Node.js. +- **`actions/upload-artifact`** : Sauvegarder des fichiers ou des résultats de tests. + +### Exemple Complet : + +```yaml +jobs: + build: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v2 + + - name: Set up Node.js + uses: actions/setup-node@v2 + with: + node-version: '14' + + - name: Install dependencies + run: npm install +``` + +--- + +## 3. Créer et Utiliser Vos Propres Actions Personnalisées + +En plus d'utiliser des actions préconstruites, GitHub Actions vous permet de **créer vos propres actions personnalisées** pour répondre à des besoins spécifiques. Ces actions peuvent être écrites en JavaScript ou définies dans des conteneurs Docker pour des environnements plus complexes. Pour un exemple pratique de création d'une action personnalisée, vous pouvez consulter le dépôt [Cedille-Actions-By-Example](https://github.com/ClubCedille/cedille-actions-by-example). Ce dépôt présente différentes actions, dont l'action **KubeSketcher**, qui génère des diagrammes d'architecture de namespaces Kubernetes à partir de manifests, et **WorkflowWikiExample**, une action créée spécialement pour illustrer la création et le fonctionnement d'une action. + +Voici la procédure qui a été suivie pour la création de l'action **cedille-actions-by-example/WorkflowWikiExample** : + +```markdown +### Types d'Actions Personnalisées + +1. **Actions JavaScript** : Actions écrites en JavaScript qui s'exécutent directement dans l'environnement du runner. +2. **Actions Docker** : Actions encapsulées dans un conteneur Docker, permettant de définir un environnement d'exécution plus complexe. + +### Créer une Action JavaScript Personnalisée + +Voici comment créer une action simple en JavaScript : + +1. **Créer un répertoire `WorkflowWikiExample` dans votre dépôt**. +2. **Créer un fichier `index.js`** avec le code JavaScript de votre action : + +```js +// index.js +const core = require('@actions/core'); +const github = require('@actions/github'); + +try { + const message = core.getInput('message'); + console.log(`Message: ${message}`); +} catch (error) { + core.setFailed(error.message); +} +``` + +3. **Créer un fichier `action.yml`** pour décrire l’action : + +```yaml +name: 'Print Message' +description: 'Imprime un message dans la console' +inputs: + message: + description: 'Le message à imprimer' + required: true +runs: + using: 'node20' + main: 'index.js' +``` + +### Utiliser l'Action Personnalisée + +Une fois que vous avez créé votre action, vous pouvez l'utiliser dans vos workflows comme n'importe quelle autre action. + +```yaml +name: Custom Action Workflow + +on: [push] + +jobs: + custom-action-job: + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v2 + + - name: Run custom action + uses: ClubCedille/Cedille-Actions-By-Example/WorkflowWikiExample@master + with: + message: "Bonjour depuis l'action personnalisée !" +``` + +### Actions Docker + +Si votre action nécessite un environnement spécifique, vous pouvez créer une action Docker. Cela vous permet d'exécuter des scripts dans un conteneur isolé. + +#### Exemple d'Action Docker : +1. Créez un fichier `Dockerfile` : + +```dockerfile +FROM node:14 +COPY . /app +WORKDIR /app +RUN npm install +CMD ["node", "index.js"] +``` + +2. Créez l’action YAML pour Docker : + +```yaml +name: 'Custom Docker Action' +runs: + using: 'docker' + image: 'Dockerfile' +``` + +--- + +## 4. Secrets et Variables d’Environnement + +Les **secrets** et **variables d'environnement** permettent de sécuriser les informations sensibles et de passer des paramètres dynamiques à vos workflows. + +### Utiliser des Secrets + +Les secrets sont des informations sensibles, comme des clés API ou des identifiants de connexion, que vous ne voulez pas exposer directement dans votre code. Vous pouvez ajouter des secrets à votre dépôt via l'interface GitHub, puis les référencer dans vos workflows. + +#### Ajouter un Secret : +1. Allez dans les **Settings** du dépôt. +2. Cliquez sur **Secrets and variables** > **Actions**. +3. Ajoutez un secret (par exemple, `API_KEY`). + +#### Utiliser un Secret dans un Workflow : + +```yaml +jobs: + build: + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v2 + + - name: Use secret API key + run: echo "Your API key is ${{ secrets.API_KEY }}" +``` + +### Utiliser des Variables d'Environnement + +Vous pouvez également définir des variables d'environnement à utiliser dans les jobs ou les étapes. + +#### Exemple de Variables d'Environnement : + +```yaml +jobs: + build: + runs-on: ubuntu-latest + + env: + NODE_ENV: production + API_URL: https://api.example.com + + steps: + - name: Print environment variables + run: echo "Environment: $NODE_ENV, API: $API_URL" +``` + +--- + +## 5. Exécution Parallèle et Conditionnelle + +### Exécution Parallèle + +Par défaut, les jobs dans un workflow GitHub Actions s'exécutent en **parallèle**. Cela signifie que plusieurs jobs peuvent s'exécuter simultanément, ce qui permet d’accélérer le temps d'exécution global. + +#### Exemple d'Exécution Parallèle : + +```yaml +jobs: + build-frontend: + runs-on: ubuntu-latest + steps: + - name: Build frontend + run: npm run build-frontend + + build-backend: + runs-on: ubuntu-latest + steps: + - name: Build backend + run: npm run build-backend +``` +Dans cet exemple, les jobs `build-frontend` et `build-backend` s'exécuteront en parallèle. + +### Exécution Conditionnelle + +Vous pouvez définir des conditions pour exécuter ou sauter des jobs ou des étapes. Cela permet, par exemple, de n’exécuter certaines actions que si un test échoue, ou si la branche correspond à une certaine condition. + +#### Exécution Conditionnelle avec `if` : + +```yaml +jobs: + deploy: + runs-on: ubuntu-latest + + if: github.ref =='refs/heads/main' #Exécuter uniquement si la branche est 'main' + + steps: + - name: Deploy to production + run: ./deploy.sh +``` + +Voici comment vous pouvez ajouter une section sur le passage d'informations d'un workflow à un autre, en plus de la section d'exécution conditionnelle : + +```markdown +#### Exécution Conditionnelle en Fonction de l'Échec ou du Succès : + +```yaml +jobs: + test: + runs-on: ubuntu-latest + steps: + - name: Run tests + run: npm test + + notify: + runs-on: ubuntu-latest + needs: test + if: failure() # Ce job s'exécute uniquement si le job 'test' échoue + steps: + - name: Send notification + run: echo "Tests failed!" +``` + +### Passage d'Informations d'un Job à un Autre + +Il est possible de faire passer des informations d'un job à un autre dans un workflow GitHub Actions en définissant des **outputs** dans un job et en utilisant ces outputs dans un job suivant. Cela permet de réutiliser des données calculées ou récupérées dans un job pour les utiliser dans un autre. + +#### Exemple : Définir et Utiliser des Outputs dans des Jobs + +Dans cet exemple, le premier job **build** génère un numéro de version et le passe au job suivant **deploy**. + +```yaml +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v2 + + - name: Generate version number + id: version_step + run: echo "::set-output name=version::1.0.$(date +%s)" + + deploy: + runs-on: ubuntu-latest + needs: build + steps: + - name: Checkout repository + uses: actions/checkout@v2 + + - name: Deploy application + run: echo "Deploying version ${{ needs.build.outputs.version }}" +``` + +#### Explication : + +1. **Définir un Output** : Dans le job `build`, la commande `::set-output` est utilisée pour définir un output appelé `version`. Ce numéro de version est généré à l'aide de la commande `date` pour créer une valeur unique. + +2. **Utiliser l'Output dans un Autre Job** : Dans le job `deploy`, l'output du job `build` est référencé via la syntaxe `${{ needs.build.outputs.version }}`. Cela permet d'accéder à l'information générée dans le premier job et de l'utiliser pour déployer une version spécifique. + +#### Référence vers la Documentation + +Pour plus de détails, vous pouvez consulter la documentation GitHub Actions sur le [passage d'informations entre jobs](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/passing-information-between-jobs#example-defining-outputs-for-a-job). + +--- + +## Conclusion + +La création de workflows personnalisés dans GitHub Actions vous permet d'automatiser efficacement vos pipelines CI/CD. Que vous utilisiez des actions préconstruites depuis le Marketplace, ou que vous créiez vos propres actions, GitHub Actions offre une flexibilité inégalée. Les secrets, variables d'environnement, et les conditions d'exécution vous donnent un contrôle total sur vos workflows, vous permettant de créer des processus robustes et sécurisés pour votre projet. + +Avec ces outils, vous êtes maintenant prêt à créer des workflows adaptés à vos besoins, améliorer la collaboration entre les équipes, et automatiser vos déploiements et tests de manière fiable. diff --git a/wiki/mkdocs-en.yml b/wiki/mkdocs-en.yml index 12da482..1975d7b 100644 --- a/wiki/mkdocs-en.yml +++ b/wiki/mkdocs-en.yml @@ -76,7 +76,19 @@ nav: - 'Docker Hub & Container Registry': onboarding/tracks/learn-docker/container-registry.md - 'Track - Web Development': onboarding/tracks/web-development.md - 'Track - App Development': onboarding/tracks/app-development.md - - 'Track - DevOps': onboarding/tracks/devops.md + - Track - DevOps: + - Learn GitHub Actions: + - 'Introduction to GitHub Actions': onboarding/hands-on-labs/learn-github-actions/introductions.md + - 'Getting Started with GitHub Actions': onboarding/hands-on-labs/learn-github-actions/first-step.md + - 'Creating Custom Workflows': onboarding/hands-on-labs/learn-github-actions/workflows.md + - 'Integration with Docker and Kubernetes': onboarding/hands-on-labs/learn-github-actions/integration.md + - 'Continuous Deployment with GitHub Actions': onboarding/hands-on-labs/learn-github-actions/deployment.md + - 'Using GitHub Container Registry (GHCR)': onboarding/hands-on-labs/learn-github-actions/registry.md + - 'Managing Security and Permissions': onboarding/hands-on-labs/learn-github-actions/security.md + - 'Optimizing CI/CD Workflows': onboarding/hands-on-labs/learn-github-actions/CICD.md + - 'Monitoring and Reporting': onboarding/hands-on-labs/learn-github-actions/monitoring.md + - 'Practical Use Cases: DevOps with GitHub Actions': onboarding/hands-on-labs/learn-github-actions/use-case.md + - 'Best Practices and DevOps Patterns with GitHub': onboarding/hands-on-labs/learn-github-actions/practices.md - 'Track - SRE': onboarding/tracks/sre.md - Finish the Onboarding: onboarding/complete.md - CEDILLE Platform: diff --git a/wiki/mkdocs-fr.yml b/wiki/mkdocs-fr.yml index 11199f9..298614f 100644 --- a/wiki/mkdocs-fr.yml +++ b/wiki/mkdocs-fr.yml @@ -76,7 +76,19 @@ nav: - 'Docker Hub & registre de conteneurs': onboarding/tracks/learn-docker/container-registry.md - 'Piste - Développement Web': onboarding/tracks/web-development.md - 'Piste - Développement applicatif': onboarding/tracks/app-development.md - - 'Piste - DevOps': onboarding/tracks/devops.md + - Piste - DevOps: + - Apprendre GitHub Actions: + - 'Introduction à GitHub Actions': onboarding/hands-on-labs/learn-github-actions/introductions.md + - 'Premiers Pas avec GitHub Actions': onboarding/hands-on-labs/learn-github-actions/first-step.md + - 'Créer des Workflows Personnalisés': onboarding/hands-on-labs/learn-github-actions/workflows.md + - 'Intégration avec Docker et Kubernetes': onboarding/hands-on-labs/learn-github-actions/integration.md + - 'Déploiement Continu avec GitHub Actions': onboarding/hands-on-labs/learn-github-actions/deployment.md + - 'Utiliser GitHub Container Registry (GHCR)': onboarding/hands-on-labs/learn-github-actions/registry.md + - 'Gestion de la Sécurité et des Permissions': onboarding/hands-on-labs/learn-github-actions/security.md + - 'Optimisation des Workflows CI/CD': onboarding/hands-on-labs/learn-github-actions/CICD.md + - 'Monitoring et Reporting': onboarding/hands-on-labs/learn-github-actions/monitoring.md + - 'Cas Pratiques : DevOps avec GitHub Actions': onboarding/hands-on-labs/learn-github-actions/use-case.md + - 'Bonnes Pratiques et Patterns DevOps avec GitHub': onboarding/hands-on-labs/learn-github-actions/practices.md - 'Piste - SRE': onboarding/tracks/sre.md - Complète l'intégration: onboarding/complete.md - Plateforme CEDILLE: @@ -88,6 +100,8 @@ nav: - 'Retrospection 1': plateforme-cedille/log791/retrospective-1.md - 'Retrospection 2': plateforme-cedille/log791/retrospective-2.md - 'Retrospection 3': plateforme-cedille/log791/retrospective-3.md + - 'DevOps': + - onboarding/hands-on-labs/devops.md - 'Document de vision': plateforme-cedille/vision.md - Infrastructure: plateforme-cedille/infra.md - 'Cluster kubernetes': plateforme-cedille/cluster-kubernetes.md