Workflows

Workflows are automated processes that you define in YAML files within your repository. They describe what should happen when certain events occur — such as running tests on every push, or deploying when a release is published.

Workflow Files

Workflow files are stored in the .copia/workflows/ directory of your repository. Any file with a .yaml or .yml extension in that directory will be recognized as a workflow.

For example:

my-repo/
├── .copia/
│   └── workflows/
│       ├── ci.yaml
│       └── deploy.yaml
├── src/
└── README.md

Basic Structure

A workflow file has three main sections: the name, trigger events, and jobs.

name: My Workflow                # Human-readable name
on: [push]                       # When to run
jobs:
  build:                         # Job ID
    runs-on: windows10-S5K       # Which runner label to use
    steps:
      - name: Check out code
        uses: actions/checkout@v4
      - name: Run a script
        run: echo "Build complete"

Trigger Events

The on key defines which events trigger the workflow. You can specify a single event, a list of events, or events with filters.

Single event

on: push

Multiple events

on: [push, pull_request]

Manual dispatch

You can trigger a workflow manually from the Copia UI using workflow_dispatch:

on:
  workflow_dispatch:

The https:// or http:// prefix is required when using absolute URLs for actions (see From any Git repository below).

Supported Trigger Events

Event	Activity Types
create	Branch or tag created
delete	Branch or tag deleted
push	Commits pushed
issues	Issue opened, closed, or labels changed
issue_comment	New comment on an issue or pull request
pull_request	Pull request opened, closed, merged, target branch changed, or labels changed
pull_request_review	Pull request reviewed (approved, rejected, or commented)
release	Release published, updated, or deleted
device_link_backup_changes_found	DeviceLink backup completed with 'Modified' status
device_link_backup_no_changes_found	DeviceLink backup completed with 'Up to Date' status
device_link_backup_failed	DeviceLink backup completed with 'Failed' or 'Timed out' status
workflow_dispatch	On-demand, manual user trigger

Jobs

Jobs define what runs on a given runner. Each job runs in its own environment on the runner host.

Basic job

jobs:
  test:
    runs-on: windows10-S5K
    steps:
      - uses: actions/checkout@v4
      - run: npm test

Multiple jobs

By default, jobs run in parallel. To run them sequentially, use needs:

jobs:
  build:
    runs-on: windows10-S5K
    steps:
      - uses: actions/checkout@v4
      - run: npm run build

  test:
    needs: build
    runs-on: windows10-S5K
    steps:
      - uses: actions/checkout@v4
      - run: npm test

The runs-on key

The runs-on value must match a label registered by one of your runners. Common values include ubuntu-latest, ubuntu-22.04, or custom labels you define (such as windows10-S5K). See Runner Setup — Labels for details.

Steps

Steps are the individual tasks within a job. Each step either runs a shell command or uses an action.

Run a shell command

steps:
  - name: Print a greeting
    run: echo "Hello, world!"

Run a multi-line script

steps:
  - name: Build project
    run: |
      echo "Installing dependencies..."
      npm install
      echo "Building..."
      npm run build

Use an action

steps:
  - name: Check out code
    uses: actions/checkout@v4

Specify a working directory

steps:
  - name: Run tests
    run: npm test
    working-directory: ./my-app

Set environment variables

steps:
  - name: Deploy
    run: ./deploy.sh
    env:
      TARGET_ENV: production
      API_URL: https://api.example.com

Using Actions

Actions are reusable units of work. You can reference actions from public GitHub repositories, from other Git hosts via absolute URL, or define them locally. When referencing an action via an absolute URL, the URL must be publicly accessible on the internet, otherwise cloning will fail.

From GitHub (default)

uses: actions/checkout@v4
uses: actions/setup-node@v4

By default, actions without a full URL are downloaded from GitHub.

From any Git repository (absolute URL)

Copia supports referencing actions from any accessible Git repository using an absolute URL:

uses: https://github.com/actions/checkout@v4
uses: https://your-internal-server.com/org/my-action@main

The https:// or http:// prefix is required when using absolute URLs.

Local actions

You can define actions within your own repository:

uses: ./.copia/actions/my-custom-action

Context Variables

Context variables provide information about the workflow run, repository, and environment. They are accessed using the ${{ }} expression syntax.

Common context variables:

Expression	Description
${{ github.actor }}	The user who triggered the workflow
${{ github.event_name }}	The event that triggered the workflow (e.g., push)
${{ github.ref }}	The branch or tag ref that triggered the workflow
${{ github.repository }}	The repository name (e.g., my-org/my-repo)
${{ github.workspace }}	The default working directory for steps
${{ runner.os }}	The operating system of the runner
${{ job.status }}	The current status of the job

Both ${{ github.xyz }} and ${{ gitea.xyz }} are currently supported and behave identically. Check back for updates on the recommended namespace.

Conditional Steps

You can use if to conditionally run a step:

steps:
  - name: Deploy to production
    if: github.ref == 'refs/heads/main'
    run: ./deploy.sh

Default Shell

On Linux and macOS runners, bash is the default shell. On Windows runners, you need to explicitly set powershell:

defaults:
  run:
    shell: powershell

Or per-step:

steps:
  - name: Run PowerShell script
    run: Get-Process
    shell: powershell

Example: PLC Project Validation Workflow

name: Validate PLC Project
on: pull_request
jobs:
  validate:
    runs-on: windows10-S5K
    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Run validation checks
        run: |
          echo "Running PLC project validation..."
          # TODO: Replace with actual validation commands
          echo "Validation passed."