Detailing the build and release flow [EN]

Workflow Explanation

This GitHub Actions workflow automates the process of releasing a Node.js project and building a Docker image. Here's a detailed step-by-step explanation:

Triggering Events

The workflow is triggered when a pull request to develop, main, or branches matching hotfix/v* or feature/* is closed. It ignores changes to specific file types like .env, .md, and .txt files, ensuring that unnecessary updates don’t trigger the workflow.

Jobs

1. Release Job

This job handles the creation of a release for a Node.js project using semantic-release.

Name: Create Release for Node.js Project Runs-on: ubuntu-latest Steps: Create GitHub App Token: Generates a GitHub App token using the app credentials stored in GitHub Secrets. This token provides scoped permissions for repository access.

Checkout Repository: Fetches the repository with full history (depth = 0) using the generated token for access.

Import GPG Key: Configures GPG signing for commits, ensuring that commits and tags created by the workflow are signed and verified.

Set up Node.js: Installs Node.js version 22 to align with the project's runtime requirements.

Install Dependencies: Installs project dependencies using npm ci, ensuring a clean installation.

Run Semantic Release: Executes semantic-release, which analyzes commit messages to determine if a new release is necessary.

Key Mechanism of Semantic Release: Commit Message Analysis: Uses conventional commit messages (e.g., fix:, feat:, BREAKING CHANGE:) to identify whether to bump the version and what type of release is needed (patch, minor, major). Output: If a release is needed, semantic-release outputs the next version number (e.g., v1.2.3), which is captured in an environment variable semantic_tag.

2. Build and Publish Job

This job builds a Docker image of the application and pushes it to Docker Hub.

Name: Build and Publish Docker Image Runs-on: ubuntu-latest Depends on: The release job ensures that only successful releases proceed to Docker image creation. Steps: Checkout Repository: Pulls the latest repository changes for building the Docker image.

Log in to Docker Hub: Authenticates with Docker Hub using credentials stored in GitHub Secrets.

Generate Valid Docker Tag: Extracts the version tag from the semantic_tag environment variable to ensure consistent Docker tagging.

Docker Metadata: Prepares metadata for the Docker image, including image name and tags (e.g., lerianstudio/midaz-console:v1.2.3).

Build Docker Image: Builds the Docker image using the repository's Dockerfile. It also enables caching for faster rebuilds.

Run Trivy Vulnerability Scanner: Scans the built Docker image for vulnerabilities. The scanner focuses on CRITICAL and HIGH severity issues, ignoring unfixed vulnerabilities. If vulnerabilities are detected, it exits with a non-zero code, failing the workflow.

Push Docker Image: Pushes the built Docker image with the specified tags to Docker Hub.

Semantic Release Validation Semantic-release ensures that a new release is only created when necessary by:

Analyzing Git History: Examines commit messages for changes. Determining Version Updates: Identifies the required version bump: Patch: Bug fixes (fix:). Minor: New features (feat:). Major: Breaking changes (BREAKING CHANGE: in commit message). Skipping Unnecessary Releases: If no qualifying commits are found, semantic-release skips the release step.