How It Works

This page explains the architecture behind Copia Actions Runners — how the runner communicates with Copia, how jobs are executed, and what network connectivity is required.

Architecture Overview

Copia Actions is built on three main components:

1

Copia (the server)

Your Copia instance manages workflows, schedules jobs, stores logs, and provides the web UI. When a trigger event occurs (such as a push or pull request), Copia parses the workflow files in your repository and creates jobs.

2

Act Runner (the runner)

A standalone program that runs on your infrastructure. It connects to Copia, polls for available jobs, and executes them. The runner is based on a fork of nektos/act, a tool originally designed to run GitHub Actions locally.

Communication Protocol

The runner communicates with Copia using gRPC over HTTP. This means the runner reuses the same HTTP port that serves the Copia web UI — no additional ports need to be opened on the Copia side.

The communication flow works like this:

1

Registration

The runner sends its registration token and labels to Copia. Copia validates the token and records the runner.

2

Polling

The runner periodically polls Copia for new jobs that match its labels.

3

Job assignment

When a matching job is available, Copia assigns it to the runner and provides the job details (workflow steps, secrets, variables).

4

Execution

The runner executes the job and streams logs back to Copia in real time.

5

Completion

The runner reports the final job status (success, failure, or cancelled) to Copia.

How Jobs Run

When the runner receives a job, it follows these steps:

1

Select the execution environment

Based on the label that matched (e.g., windows-S5K), the runner prepares the host environment.

2

Execute steps sequentially

Each step in the job runs in order. Steps can be shell commands (run:) or actions (uses:).

3

Download actions

When a step uses an action (e.g., actions/checkout@v4), the runner downloads the action's source code from the specified repository. By default, actions without a full URL are downloaded from GitHub.

4

Stream logs

As each step runs, the output is streamed back to Copia and made available in the Actions tab.

5

Clean up

After all steps complete (or if the job fails), the container is stopped and removed.

Network Requirements

There are four network connections involved in running a job. Understanding these helps you configure firewalls and network policies.

1

Runner to Copia Instance (required)

The runner must be able to reach your Copia instance over HTTPS. This is the primary connection used for registration, job polling, log streaming, and status reporting.

• Protocol: HTTPS (port 443)

• Direction: Runner → Copia

• Example: https://app.copia.io

Do not use loopback addresses (127.0.0.1 or localhost) as the instance URL. Job containers run in separate network namespaces and cannot reach loopback addresses on the host.

2

Job Containers to Copia Instance (required for most workflows)

Job containers need to connect to Copia to fetch repository code. For example, actions/checkout@v4 clones the repository by connecting to the Copia instance URL.

• Protocol: HTTPS (port 443) or HTTP (port 80)

• Direction: Job container → Copia

• Why: Code checkout, LFS downloads, API calls within workflows

This is why the instance URL must be a routable address — not localhost.

3

Runner to the Internet (recommended)

When a workflow uses actions like actions/checkout@v4, the runner downloads the action's source code. By default, actions are downloaded from GitHub (github.com). The runner also pulls Docker images from Docker Hub or other registries when starting job containers.

• Protocol: HTTPS (port 443)

• Direction: Runner → app.copia.io, github.com, Docker Hub, etc.

• Required for: Downloading actions, pulling container images

Hint for air-gapped environments: If your runner cannot access the internet, you can host actions on your Copia instance and reference them using absolute URLs. You can also pre-pull or mirror Docker images to a local registry.

4

Job Containers to the Internet (optional)

Some actions download additional resources at runtime. For example, actions/setup-node downloads Node.js binaries. If your workflows don't need runtime downloads, this connection is not required.

• Protocol: HTTPS (port 443)

• Direction: Job container → various hosts

• Required for: Runtime downloads within actions (e.g., language runtimes, package managers)

Network Summary

Connection	Required?	Purpose
Runner → Copia	Yes	Registration, polling, logs, status
Job container → Copia	Yes (for most workflows)	Code checkout, LFS, API access
Runner → Internet	Recommended	Download actions and Docker images
Job container → Internet	Optional	Runtime downloads within actions

Runner Labels and Job Routing

When a runner registers with Copia, it reports its labels. Labels tell Copia what kinds of jobs the runner can handle and how to run them.

When a workflow specifies runs-on: windows-S5K, Copia looks for an online runner that has the windows-S5K label and assigns the job to it. If multiple runners match, Copia selects one that is available.

Labels also encode the execution mode:

• ubuntu-latest:docker://node:16-bullseye — Run the job in a Docker container using the node:16-bullseye image

• linux_amd64:host — Run the job directly on the runner's host machine

See Runner Setup — Labels for full details on label format and customization.

Security Model

Runners have no standing permissions on your Copia instance beyond the ability to connect and poll for jobs. When a job is assigned, the runner receives a temporary, scoped token that grants access only to the repository associated with that job. This token expires when the job completes.

Additional permissions (such as access to package registries or external services) can be granted through secrets that you configure in the Copia UI. See Variables and Secrets.

Recommendations

• Only register runners you control. A runner has the ability to execute arbitrary code from workflows, so it should run on trusted infrastructure.

• Only provide runners to repositories and organizations you trust. Workflows in those repositories will be able to run code on your runner.

Note for Self-Hosted Copia customers: Replace https://app.copia.io with your instance URL in all network configurations. All architecture and security considerations apply equally.