⚙️ CI/CD & Deployment

You push a commit — and somehow it becomes a running app on a server. This page removes the "somehow": pipelines, the machines that run them, environments, how a push to main knows where to deploy, how to roll back, and how to publish packages. GitLab CI is the main track; every example has a GitHub Actions tab.

What is CI/CD?

Continuous Integration (CI) — every push is automatically built and tested, so broken code is caught in minutes, not at release time. Continuous Delivery/Deployment (CD) — code that passes CI is automatically shipped to an environment.

Three words carry the whole topic:

Runners & Agents — the Machines That Do the Work

A pipeline is just YAML until something executes it. That something is a runner (GitLab) / runner agent (GitHub Actions) — a small program on a machine that polls the server, picks up jobs, runs their scripts, and reports results back.

Registering a self-hosted runner (Windows):

# download gitlab-runner.exe from docs.gitlab.com, then:
.\gitlab-runner.exe install
.\gitlab-runner.exe register --url https://gitlab.com --token glrt-XXXXXXXX
.\gitlab-runner.exe start

# download + extract the runner package, then:
.\config.cmd --url https://github.com/your-org/your-repo --token XXXXXXXX
.\run.cmd

How a job finds its runner: jobs and runners are matched by tags (GitLab) or labels via runs-on: (GitHub). A job tagged windows only runs on a runner registered with the windows tag. If no runner matches, the job waits forever — remember this for the Troubleshooting section.

That's all you need to use runners. Administering them (Docker executors, autoscaling, runner fleets) is its own topic — go deeper in the GitLab Runner docs or the GitHub self-hosted runner docs.

The Pipeline File

The pipeline lives in the repo, versioned like any other file. GitLab reads .gitlab-ci.yml at the repo root; GitHub reads every .yml/.yaml file in .github/workflows/. A complete three-stage pipeline:

stages:
  - build
  - test
  - deploy

build-job:
  stage: build
  script:
    - echo "Compiling the app..."
    - mkdir build
    - echo "compiled output" > build/app.txt
  artifacts:
    paths:
      - build/          # hand the output to later stages

test-job:
  stage: test
  script:
    - echo "Running tests..."

deploy-job:
  stage: deploy
  script:
    - echo "Copying build/ to the server..."
  environment: staging

name: CI
on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: echo "Compiling the app..."
      - run: mkdir build && echo "compiled output" > build/app.txt
      - uses: actions/upload-artifact@v4
        with:
          name: build
          path: build/

  test:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: echo "Running tests..."

  deploy:
    needs: [build, test]
    runs-on: ubuntu-latest
    environment: staging
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: build
      - run: echo "Copying build/ to the server..."

What triggers a pipeline?

Half of all CI/CD confusion is "why did (or didn't) a pipeline start?" These are the trigger types:

How the deploy job gets the build output

Jobs are isolated — each may run on a different runner, starting from a fresh clone. Your compiled output does not magically survive between jobs. The bridge is artifacts: the build job uploads build/ to the server, and later jobs download it automatically (GitLab) or via download-artifact (GitHub).

Environments — dev, staging, production

An environment is a named place your app runs: dev, staging, production. Both platforms treat environments as first-class objects — declare one on a deploy job and the platform starts tracking which commit is running where.

deploy-job:
  stage: deploy
  script:
    - echo "Deploying..."
  environment:
    name: staging
    url: https://staging.example.com   # link shown in the UI

deploy:
  runs-on: ubuntu-latest
  environment:
    name: staging
    url: https://staging.example.com
  steps:
    - run: echo "Deploying..."

"I pushed to main — which environment gets deployed?"

The question this page exists to answer. The short version: Git has no idea. A push just moves a branch pointer. The branch→environment mapping is written by your team, in the pipeline file, as rules on the deploy jobs:

deploy-staging:
  stage: deploy
  script:
    - echo "Deploying to STAGING"
  environment: staging
  rules:
    - if: '$CI_COMMIT_BRANCH == "develop"'

deploy-production:
  stage: deploy
  script:
    - echo "Deploying to PRODUCTION"
  environment: production
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'

# .github/workflows/deploy-staging.yml
on:
  push:
    branches: [develop]
jobs:
  deploy:
    environment: staging
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying to STAGING"

# .github/workflows/deploy-production.yml
on:
  push:
    branches: [main]
jobs:
  deploy:
    environment: production
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying to PRODUCTION"

Common team conventions (yours may differ — the pipeline file is the truth):

Deployment Patterns

Auto-deploy vs manual gate

Staging usually deploys automatically. Production usually waits for a human to press a button:

deploy-production:
  stage: deploy
  script:
    - echo "Deploying to PRODUCTION"
  environment: production
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
      when: manual        # pipeline pauses; a ▶ button appears in the UI

Tag-based releases

Many teams deploy production only from a version tag, never from a branch — releases become explicit, numbered, auditable events:

deploy-production:
  stage: deploy
  script:
    - echo "Deploying $CI_COMMIT_TAG to PRODUCTION"
  environment: production
  rules:
    - if: '$CI_COMMIT_TAG =~ /^v/'   # only runs for tags like v1.2.0

on:
  push:
    tags: ['v*']    # only runs for tags like v1.2.0

Releasing then becomes: git tag v1.2.0 && git push origin v1.2.0. (Tags themselves are covered in the GitLab Platform guide.)

Deploying an old version (rollback)

New build is broken in production? Three ways back, in order of preference:

Who is allowed to deploy?

Two locks, usually combined: protected branches control who can push/merge to main (covered in Branch Protection), and protected environments control who can trigger a deploy job targeting production — GitLab: Settings → CI/CD → Protected environments; GitHub: Settings → Environments → required reviewers + deployment branch rules. If you can't press the production ▶ button, this is why — ask a maintainer, don't work around it.

Secrets & Variables

Real deploys need credentials — server passwords, API keys, tokens. They must never be committed to the repo (see the .gitignore guide). Instead, store them on the platform and the runner injects them as environment variables at job time:

deploy-job:
  script:
    - ./deploy.sh --api-key "$DEPLOY_API_KEY"   # injected, never in the repo

steps:
  - run: ./deploy.sh --api-key "${{ secrets.DEPLOY_API_KEY }}"

Shipping Packages, Not Just Deployments

Sometimes the pipeline's product isn't a running app — it's a package other people install. Same machinery, different last step.

Repo → NuGet package

A library repo can publish itself to a NuGet feed on every version tag. (This is the one .NET-specific example on this page — the pattern is identical for npm, PyPI, and Maven: pack on tag, push to registry with a stored API key.)

publish-nuget:
  stage: deploy
  rules:
    - if: '$CI_COMMIT_TAG =~ /^v/'
  script:
    - dotnet pack -c Release -o out
    - dotnet nuget push "out/*.nupkg"
        --source "$NUGET_FEED_URL"
        --api-key "$NUGET_API_KEY"

on:
  push:
    tags: ['v*']
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: dotnet pack -c Release -o out
      - run: dotnet nuget push "out/*.nupkg"
             --source "https://api.nuget.org/v3/index.json"
             --api-key "${{ secrets.NUGET_API_KEY }}"

Consumers then just run dotnet add package YourLibrary — your repo has become a product with releases.

Repo → AI plugin marketplace

The opposite extreme, and a lesson about Git itself: for AI coding tools like Claude Code, a plain Git repo is the distribution channel. No pipeline, no registry, no build — pushing is publishing, because consumers install straight from the git URL.

A marketplace is a repo with one JSON manifest and a folder per plugin:

team-marketplace/
├── .claude-plugin/
│   └── marketplace.json      # the catalog
└── plugins/
    └── commit-helper/
        ├── .claude-plugin/plugin.json
        ├── commands/          # slash commands
        ├── agents/            # custom agents
        └── skills/            # skills

// .claude-plugin/marketplace.json
{
  "name": "team-marketplace",
  "owner": { "name": "Your Team" },
  "plugins": [
    {
      "name": "commit-helper",
      "source": "./plugins/commit-helper",
      "description": "Team conventions for commits and MRs"
    }
  ]
}

Anyone on the team installs it with the repo URL:

/plugin marketplace add https://gitlab.com/your-team/team-marketplace.git
/plugin install commit-helper@team-marketplace

GitLab ↔ GitHub Actions Reference

Same concepts, different vocabulary:

Deep dives: GitLab CI/CD docs · GitHub Actions docs.

Troubleshooting — When the Deploy Goes Wrong

Six situations every team hits. Click a card to expand it.