Skip to content

Home

Jump to bottom
Charly edited this page Jul 24, 2025 · 10 revisions

CI/CD Pipeline Documentation

This repository uses a modular GitHub Actions-based CI/CD system to automate testing, semantic versioning, and releases, with extra security controls for version bump automation.

Main Workflow: CI Pipeline

File: .github/workflows/ci.yml

Trigger Events

  • Manual dispatch
  • Push to main
  • Pull Requests

Concurrency

  • One run per branch/ref at a time (superseded runs are canceled)

Jobs & Logic

  1. bump_version_check
  • Type: Reusable workflow (.github/workflows/bump-version.yml)
  • Purpose:
    • Detects if a version bump is needed.
    • Outputs:
      • bump: The type of bump (major, minor, patch, none)
      • version: New version string, if any
      • should_run_tests_and_release: true if further validation/release is needed
    • Security:
  1. typechecking
  • Runs if: should_run_tests_and_release == 'true'
  • Needs: bump_version_check
  • Type: Reusable workflow (typechecking.yml)
  • Purpose: Runs static type checks.
  1. tests
  • Runs if: should_run_tests_and_release == 'true'
  • Needs: bump_version_check
  • Type: Reusable workflow (tests.yml)
  • Purpose: Runs the test suite.
  1. comment_start
  • Needs: typechecking, tests
  • Runs on: PRs only
  • Purpose: Comments "requested" build status on PRs at build start.
  1. draft_release
  • Runs if: should_run_tests_and_release == 'true'
  • Needs: typechecking, tests
  • Type: Reusable workflow (release.yml)
  • Purpose:
    • Builds and uploads release artifacts.
    • Runs in dry-run mode if not on a main branch or no real bump.
    • Uses secrets for secure signing, AWS, Sentry, etc.
  1. comment_end
  • Needs: draft_release
  • Runs on: PRs only (always runs, even on failure)
  • Purpose: Posts "completed" status on PRs with release result.
  1. check_release_status
  • Needs: draft_release
  • Runs: Always (even if draft_release failed/skipped)
  • Purpose:
    • Marks workflow failed if draft_release failed.
    • Success if release succeeded or was skipped.

Workflow: Bump Version

File: .github/workflows/bump-version.yml

Core Logic & Security

  • Purpose
    • Automate version bumping based on semantic commit history.
    • Restrict actual bumping to commits made by the trusted bot only.

Steps

  1. Checkout
  • Pulls the full main branch with tags for accurate diff/versioning.
  1. Check if we should skip version bump
  • Skips unless the event is a push to main.
  • Gets last commit message and author email.
  • Skips bump if last commit is a bump and the author is decentraland-bot ([email protected]).
  • If not by the bot, continues—prevents spoofing and accidental triggers.
  1. Determine and bump version from commits
  • Determines next semantic version based on commit messages since the last version bump commit (e.g., chore(release): bump version to ...), not the last tag.
  • Runs update script to increment all version fields.
  • Stores new version in outputs.
  1. Commit changes
  • Commits the bump as github-actions[bot].
  1. Create Pull Request for version bump
  • Opens a PR from the bump branch to main as decentraland-bot.
  • Only possible using a secure bot token.
  1. Auto-approve PR & Enable auto-merge
  • PRs from the bot are auto-approved and set to squash-merge for safety as decentraland-bot.
  1. Evaluate if we should run tests and release
  • Checks if running on a PR (not from a bump branch), or on a main push with a bump.
  • Sets output flag for downstream jobs.

Version Bumping Logic

Note: This workflow does not use the latest Git tag as the reference for version bumping. Instead, it uses the most recent version bump commit on main (matching the pattern chore(release): bump version to ...). All commit messages since this last bump commit are used to determine the next semantic version, ensuring accurate versioning even if some bumps are not tagged.

This workflow uses the Conventional Commits naming convention to automatically determine whether a new release should be a major, minor, or patch version. This is evaluated during the bump_version job, specifically in the "Determine and bump version from commits" step.

Commit Message Rules

  • Major version bump

    • Triggered if any commit message since the last version bump commit contains:
      • BREAKING CHANGE anywhere in the message body, or
      • an exclamation mark after the type, e.g. feat!:, fix!:
    • Example: 
      feat!: remove support for legacy API
      or 
      refactor(api): update response format

BREAKING CHANGE: clients must update payload parsing

  • Minor version bump

    • Triggered if any commit message since the last version bump commit starts with:
      • feat( or feat:
    • Example: 
      feat(auth): add login with Google

  • Patch version bump

    • Used if no commits since the last version bump commit match the above rules (major/minor).
    • Most other changes like bug fixes, refactors, or documentation will default to a patch bump.
    • Example: 
      fix(ui): correct button color on dark mode

How it works in the workflow

  • The workflow collects all commit messages since the last version bump commit.
  • It checks for the patterns above in order: major, minor, patch.
  • The highest priority match (major > minor > patch) determines the bump.
  • The new version is then generated and committed automatically.

Scenario Summary

This table summarizes how each job in the CI pipeline behaves in key scenarios: a normal PR push, an autobump PR push, and after each is merged to the main branch. It clarifies which parts of the workflow run in each situation, helping maintainers and contributors understand the pipeline’s logic and what to expect after every PR or automated version bump.

Scenario bump_version_check typechecking
& tests		 comment_start &
comment_end		 draft_release check_release_status
Normal PR push ✅ ✅ ✅ ✅ ✅
Normal PR merged to main ✅ ❌ ❌ ❌ ✅
Autobump PR push ✅ ❌ ❌ ❌ ✅
Autobump PR merged to main ✅ ✅ ❌ ✅ ✅

Legend:
✅ Job runs
❌ Job does not run

Notes:

  • comment_start and comment_end are only relevant for pull request events on normal PRs.
  • For normal PR merged & autobump PR pushes, only bump_version_check and check_release_status run; the rest of the pipeline is skipped until the autobump PR is merged.
  • When autobump PR is merged to main, the full release pipeline (typechecking, tests, draft_release, check_release_status) runs.
  • The check_release_status job always runs after draft_release and will fail the workflow if the release step fails (not if it is skipped).
  • This logic ensures that test and release jobs only run when appropriate, avoiding duplicate releases or builds from automated bump PRs.
Clone this wiki locally