CI/CD Configuration

CI/CD pipelines are defined using YAML configuration files in your repository. Project113's CI/CD system is powered by a modified Woodpecker instance, so the Woodpecker documentation may also be a useful reference for pipeline configuration.

Configuration File

You can define your pipeline in one of these ways:

• Single file — Create a .project113.yml or .woodpecker.yml file in the root of your repository.
• Directory — Create a .project113/ or .woodpecker/ directory containing multiple YAML files that are combined into a single pipeline definition.

Files are checked in priority order: .project113/, .project113.yaml, .project113.yml, .woodpecker/, .woodpecker.yaml, .woodpecker.yml. You can also configure a custom file path in repository settings.

Basic Structure

steps:
  build:
    image: node:20
    commands:
      - npm install
      - npm run build

  test:
    image: node:20
    commands:
      - npm test

Steps

Each step in the pipeline runs in its own container. Steps are executed in the order they are defined. If a step fails, subsequent steps are skipped unless configured otherwise.

Skipping the Clone Step

To save time when your steps don't need the repository source code (e.g., running external tools or deployment scripts), you can skip the automatic git clone step:

skip_clone: true

  steps:
  deploy:
    image: alpine
    commands:
      - echo "Deploying without cloning repo..."

When skip_clone: true is set, the pipeline starts directly with your first step.

Path-Based Triggering

Restrict steps or entire workflows to run only when specific files are changed. This is useful for monorepos or when you want to avoid running tests for documentation-only changes.

File Include/Exclude Patterns

steps:
  test:
    image: golang:1.21
    commands:
      - go test ./...
    when:
      path:
        include:
          - 'src/**'
          - 'pkg/**'
          - 'go.mod'
          - 'go.sum'
        exclude:
          - '**/*.md'
          - 'docs/**'
          - 'test/**'

Ignore Commit Message

Add an ignore_message to skip the pipeline when a commit message contains a specific pattern:

steps:
  test:
    image: golang:1.21
    commands:
      - go test ./...
    when:
      path:
        include: ['src/**', 'pkg/**']
        ignore_message: '[SKIP CI]'

When a commit message contains [SKIP CI], the step will run regardless of file changes. This is useful for manual re-triggers or hotfixes.

Triggers

By default, steps run on push events and change request updates. You can restrict a step or workflow with a when block:

steps:
  build:
    image: node:20
    commands:
      - npm run build
    when:
      branch:
        - master
        - release/*
      event:
        - push
        - pull_request

Available When Conditions

• branch — Match branch names (supports glob patterns)
• event — Match event types: push, pull_request, tag, cron, manual, deployment, release
• path — Match changed files (include/exclude/ignore_message/on_empty)
• ref — Match git refs (e.g., refs/tags/v*)
• status — Match pipeline status: success, failure, etc.
• platform — Match platform: linux/amd64, windows/amd64
• instance — Match CI instance hostname
• repo — Match repository name
• matrix — Match matrix values
• evaluate — Custom expression using pipeline variables
• local — Run only in local mode
• cron — Match cron job names

Environment Variables

Define environment variables for a step using the environment block:

steps:
  build:
    image: node:20
    environment:
      NODE_ENV: production
    commands:
      - echo $NODE_ENV

Secrets

Use secrets for sensitive values. Define them in repository settings, then reference them:

steps:
  deploy:
    image: alpine
    environment:
      DEPLOY_KEY:
        from_secret: DEPLOY_KEY
    commands:
      - ssh -i $DEPLOY_KEY deploy@server "deploy.sh"

Matrix Builds

Run steps multiple times with different configurations using a matrix:

steps:
  test:
    image: golang
    commands:
      - go test ./...
    matrix:
      GO_VERSION:
        - '1.21'
        - '1.22'
      REDIS_VERSION:
        - '6'
        - '7'

This creates 4 combinations (2×2) and runs the step for each.

Workflows

Group steps into named workflows for parallel execution and organization:

workflows:
  build:
    steps:
      - build
      - test
  deploy:
    steps:
      - deploy-staging
      - deploy-prod
    depends_on: [build]

Dependencies Between Steps

Define step execution order using depends_on:

steps:
  build:
    image: golang:1.21
    commands:
      - go build ./...
  test:
    image: golang:1.21
    commands:
      - go test ./...
    depends_on: [build]
  lint:
    image: golangci/golangci-lint
    commands:
      - golangci-lint run
    depends_on: [build]