Beginning CI/CD: A Practical Introduction using GitHub Actions

Below is a tighter, clearer version of your chapter. I preserved all substantive content, removed filler, fixed grammar and formatting, and turned free‑form lists into clean tables. I also corrected the GitHub Actions example so it actually surfaces the release_id.

Comparison of Versioning Solutions

Choosing the right tool

• Simplicity first: For straightforward .NET repos and simple branching, minver or Nerdbank.GitVersioning are often enough.
• Conventional Commits: If you already enforce them, prefer standard‑version, semantic‑release, or release‑please.
• Fully automated CD: semantic‑release is the most “hands‑off.”
• Monorepos: changesets shines for multi‑package workspaces.
• Maximum flexibility: GitVersion and release‑it give you the most control.

Example: minimal release workflow (GitHub Actions)

This demonstrates wiring a human‑triggered release with a staging step and an optional production promotion. It also fixes the release_id output so later jobs can use it.

name: Deployment

on:
  workflow_dispatch:
    inputs:
      releaseType:
        description: "Where to deploy?"
        type: choice
        required: true
        options:
          - staging
          - production

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: false

jobs:
  create_release:
    # Only create a GitHub Release when targeting production
    if: ${{ github.event.inputs.releaseType == 'production' }}
    runs-on: ubuntu-latest
    permissions:
      contents: write
    outputs:
      release_id: ${{ steps.create_release.outputs.release_id }}
    steps:
      - name: Create Release
        id: create_release
        uses: actions/github-script@v7
        with:
          script: |
            const tag = `v${Date.now()}`; // Example tag; customize to your scheme.
            const release = await github.rest.repos.createRelease({
              owner: context.repo.owner,
              repo: context.repo.repo,
              tag_name: tag,
              name: 'Production Release',
              body: 'New production release',
              draft: false,
              prerelease: false
            });
            core.setOutput('release_id', release.data.id.toString());

  staging:
    runs-on: ubuntu-latest
    environment:
      name: staging
      url: https://github.com
    steps:
      - name: Check out repository
        uses: actions/checkout@v4
      - name: Deploy to Staging
        run: |
          echo "Deploying to staging..."
          sleep 5

  production:
    needs: [staging, create_release]
    if: ${{ github.event.inputs.releaseType == 'production' }}
    runs-on: ubuntu-latest
    environment:
      name: production
      url: https://github.com
    steps:
      - name: Check out repository
        uses: actions/checkout@v4
      - name: Deploy to Production
        run: |
          echo "Deploying to production with release ID: ${{ needs.create_release.outputs.release_id }}"
          sleep 5

Importance of versioning

• Traceability & reproducibility: Tie a deployed artifact to the exact source revision and build environment. This is essential for bug reproduction, rollbacks, audits, and incident response.
• Quality & debugging: Testers and developers must reference specific versions to reproduce and fix issues reliably.
• Documentation & marketing: Docs, release notes, and launch materials should map to a version and feature set, especially across large or multi‑team initiatives.
• Security & compliance: When a vulnerability emerges, version history lets you determine exposure windows and precisely identify affected releases.
• Multi‑version support: If you serve multiple customer segments or platforms, versions help you support several lines in parallel.
• Communication: Clear, visible version identifiers prevent confusion (“which build is this?”) and help teams celebrate milestones.

Practical tips

• Ensure the running version is easy to see (CLI flag, UI footer, health endpoint, etc.).
• Use unique, comparable identifiers (avoid ambiguous glyphs like l, I, 1, |; avoid unsupported special characters).
• Don’t embed private information in version strings.
• Be consistent. You can change schemes later, but do so infrequently and decisively.

Role of dependency managers & artifact repositories

• Why artifact repos (vs only Git): Artifacts should be immutable and centrally discoverable. Git history can be rewritten; artifact repos are designed for immutable storage, indexing, metadata, checksums, replication, and access control.
• Dependency resolution: Package managers read manifests/lockfiles, resolve version constraints and dependency trees, and fetch the exact versions needed.
• Security & integrity: Registries provide checksums, provenance, and allow vulnerability scanning across dependency graphs; this makes it easy to identify what must be upgraded when a CVE lands.
• Operational simplicity: Standardized distribution avoids bespoke install steps, reduces errors, and supports side‑by‑side versions.
• Don’t ship unnecessary files: Store only what’s required to run; avoid committing node_modules or similar. Prefer lockfiles + registry availability to ensure repeatability.
• Treat internal deps like external: Pin, test upgrades in isolation, and only merge when CI passes to avoid “latest breaks latest” churn.
• Artifact mutability rule: Never change a published artifact without a version bump, and update its manifest/metadata when you do.

Ecosystem examples (learn their specifics):

• JavaScript: npm (SemVer ranges like ^1.2.3, ~1.2.3), package-lock.json.
• Python: pip/PyPI (==, >=, <=), requirements.txt.
• Java: Maven/Gradle (SNAPSHOTs, ranges). See Oracle’s Maven versioning guide: https://docs.oracle.com/middleware/1212/core/MAVEN/maven_version.htm#MAVEN401.
• Ruby: RubyGems/Bundler (Gemfile constraints).
• Rust: Cargo (Cargo.toml, Cargo.lock, SemVer).
• .NET: NuGet (PackageReference constraints).
• Scala: SBT (cross‑versioning patterns).

Version types: internal builds, release builds, customer builds

• Internal builds: Frequent, short‑lived outputs from branch/PR pipelines used for fast feedback. Often not retained long‑term.
• Release builds: Candidate artifacts destined for customers but not yet GA; may flow through gated or staged pipelines and be retained.
• Customer builds (GA): Published/production releases; retain and index for the long term.

Why pipelines “run a lot,” and what to retain

• Triggers: push to branches, PR open/update, new tags, manual runs.
• PR nuance: CI usually builds the PR as a merge preview with the target branch. Because the target branch can change before merge, rerunning on the target after merge ensures integration still holds.
• Retention: Keep release/tagged artifacts; use shorter retention for branch/PR artifacts; consider cold storage for long‑term retention needs.

Versioning strategies

A good scheme is comparable, communicative, and automatable.

Anti‑patterns (avoid):

• Overlong or visually confusing identifiers (e.g., dozens of repeated characters, ambiguous glyphs).
• Unsupported special characters or overly long tags (breaks Docker/Git constraints).
• Hiding sensitive data in versions.
• “Mostly SemVer” with frequent exceptions—consumers need reliable ordering and compatibility cues.

Build numbers vs versions

• Versions communicate to users/consumers (e.g., iOS 17.0.3).
• Build numbers identify a specific build (often a checksum or CI build ID) and should be immutable. It’s fine for many builds to share one “marketing” version.

Traceability requirements

• Make it possible to trace an artifact back to: source commit, build tools (optionally), environment, and platform/edition (e.g., add platform or SKU where relevant).

Storing artifacts & retention

• Keep: Customer releases, tagged builds, artifacts needed for rollbacks/regulatory needs.
• De‑prioritize: High‑churn CI intermediates unless needed for short‑term debugging.
• Costs & complexity: Storage isn’t free; transitive dependencies can be hard to untangle if deleted—prefer deprecation over deletion.
• Cold storage: Use cheaper tiers for long‑term archives.
• Snapshots vs releases: Snapshots (“nightlies,” “PR builds”) are usually temporary; releases should be immutable and retained.
• Backups & integrity: Rely on registry checksums, replication, and backups provided by the artifact manager.
• When registries are down: Prefer mirrored registries/caches over committing vendor directories.

How do I version code and Docker images?

• Containers & CI are alike: Both provide clean, stateless environments. Building in Docker ensures consistency with CI runners.
• Tagging strategy: Tags are aliases for specific Git commits. Use them to map source to artifacts and Docker image tags.

Git tagging essentials

1. Lightweight tag (pointer only)

   git tag v1.0.0
   

2. Annotated tag (with metadata)

   git tag -a v1.0.0 -m "First stable release"
   

3. Tag an older commit

   git tag v0.9 9fceb02
   

4. Push tags to remote

   git push origin v1.0.0
   # or push all tags
   git push --tags
   

5. Delete a tag

   git tag -d v1.0.0
   git push origin :refs/tags/v1.0.0
   

Some CI systems require at least one commit on the branch (PR‑only merge policies). If you need a tag without code changes, use an empty commit:

git commit --allow-empty -m "chore: cut release v1.0.0"

Branching note: If you must maintain multiple supported versions, consider release branches rather than trying to use tags alone on a single trunk; tags are immutable pointers and don’t let you patch old lines without affecting newer ones.

Docker images

• Docker images are the build outputs; containers are running instances.
• Use Docker tags to map image versions to Git tags or CI build IDs (e.g., myapp:1.4.2, myapp:2025.09.23, myapp:1.4.2-build.123).
• Publish immutable tags for releases; use moving tags like latest only as a convenience, not as the sole reference.

Programming‑language–specific versioning quirks

• Maven (Java): SNAPSHOTs, ranges, and ordering rules are unique—see Oracle’s guide: https://docs.oracle.com/middleware/1212/core/MAVEN/maven_version.htm#MAVEN401.
• npm (JS): SemVer ranges (^, ~), package-lock.json, and release tooling (e.g., semantic-release, release-please).
• pip/PyPI (Python): PEP 440 specifiers (==, >=, <=), requirements.txt.
• Gradle (JVM): Dynamic versions, conflict resolution strategies.
• RubyGems/Bundler (Ruby): Gem constraints in Gemfile, resolver behavior.
• Cargo (Rust): Strong SemVer culture, Cargo.lock semantics.
• NuGet (.NET): Version ranges and PackageReference rules.
• SBT (Scala): Cross‑versioning patterns and Ivy resolution.

Additional reading (build and POM relationships):

• Oracle: “From Build Automation to Continuous Integration”
• Sonatype: “The Nexus Book” (POM relationships and syntax)

Final reminders

• Keep artifacts immutable; never overwrite a published version.
• Always bump versions when contents change, and stamp manifests/metadata to avoid collisions.
• Prefer automation (commit messages → versions → changelogs → releases) where culture and tooling allow.
• Make the running version obvious to both humans and machines.