# 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**. ```yaml 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 ```yaml on: push ``` ### Multiple events ```yaml on: [push, pull_request] ``` ### Manual dispatch You can trigger a workflow manually from the Copia UI using `workflow_dispatch`: ```yaml on: workflow_dispatch: ``` {% hint style="info" %} The `https://` or `http://` prefix is required when using absolute URLs for actions (see [From any Git repository](#from-any-git-repository-absolute-url) below). {% endhint %} ### Supported Trigger Events | Event | Activity Types | | :----------------------------: | :-------------------------------------------------------------------------------------------: | | `create` | Branch or tag created | | `delete` | Branch or tag deleted | | `push` | Commits pushed | | `issues` | Issue opened, closed, or re-opened | | `issue_label` | Issue labels updated | | `issue_comment` | Comment on issue | | `pull_request` | Pull request opened, closed, re-opened, merged, or edited | | `pull_request_label` | Pull request labels updated | | `pull_request_comment` | Comment on pull request | | `pull_request_review_approved` | Pull request review approved | | `pull_request_review_rejected` | Pull request review rejected | | `pull_request_sync` | Pull request synchronized with target branch (commits merged into pull request source branch) | | `release` | Release published, updated, or deleted | | `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 ```yaml 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`: ```yaml 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](broken://pages/72f38d5498ddd1a2347ee4882c33159cdf37a790#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 ```yaml steps: - name: Print a greeting run: echo "Hello, world!" ``` ### Run a multi-line script ```yaml steps: - name: Build project run: | echo "Installing dependencies..." npm install echo "Building..." npm run build ``` ### Use an action ```yaml steps: - name: Check out code uses: actions/checkout@v4 ``` ### Specify a working directory ```yaml steps: - name: Run tests run: npm test working-directory: ./my-app ``` ### Set environment variables ```yaml 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) ```yaml 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: ```yaml uses: https://github.com/actions/checkout@v4 uses: https://your-internal-server.com/org/my-action@main ``` {% hint style="warning" %} The `https://` or `http://` prefix is required when using absolute URLs. {% endhint %} ### Local actions You can define actions within your own repository: ```yaml 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 | {% hint style="info" %} Both `${{ github.xyz }}` and `${{ gitea.xyz }}` are currently supported and behave identically. Check back for updates on the recommended namespace. {% endhint %} ## Conditional Steps You can use `if` to conditionally run a step: ```yaml 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`: ```yaml defaults: run: shell: powershell ``` Or per-step: ```yaml steps: - name: Run PowerShell script run: Get-Process shell: powershell ``` ## Example: PLC Project Validation Workflow ```yaml 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." ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.copia.io/docs/actions/workflows.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.