Getting Started

This guide walks you through setting up a self-hosted runner and running your first workflow against a Copia repository. By the end, you will have a working runner connected to your organization and a workflow that triggers on every push.

Prerequisites & Setup

Before you begin, make sure you have:

• A Copia account with access to at least one repository at https://app.copia.io

• A machine to host your runner (Linux, macOS, or Windows)

1

Enable Actions on Your Repository

Actions must be enabled per-repository. Navigate to your repository on Copia and go to Settings > Actions (under the repository settings sidebar). Check Enable Repository Actions and save. You must have Admin permissions or higher to modify repository settings.

2

Obtain a Registration Token

You need a registration token to connect your runner to Copia. Tokens can be scoped to different levels:

• Organization level — the runner serves all repositories in your organization. Go to your organization page, then Settings > Actions > Runners.

• Repository level — the runner serves only a single repository. Go to your repository, then Settings > Actions > Runners.

Copy the registration token displayed on that page. Each token can be used to register multiple runners until it is revoked and replaced.

3

Create and Download the Runner

From the same Runners settings page where you obtained your token, click Create New Runner. This opens a guided setup form where you configure your runner before downloading it.

Fill out the following fields:

• Architecture - Select the CPU architecture of your runner machine (e.g., x64).

• Operating System - Select the OS where the runner will be installed (Windows, Linux, or macOS).

• Runner Name - Enter a name to identify this runner. If left blank, the hostname of the machine will be used.

• Labels - Labels determine which workflow jobs get routed to this runner. The self-hosted label and your selected OS label are included by default. You can add additional custom labels to match specific workflows. For example, a label like release-runner clearly indicates the runner's intended purpose.

Once your fields are filled in, click Generate Configuration. This produces two sets of commands tailored to your selections: Download and Configure.

Copy and run the commands in the Download section on your runner machine. This will download and extract the runner binary.

4

Configure and Start the Runner

Copy and run the commands in the Configure section. This will register the runner with your Copia instance and start it. The registration token, instance URL, labels, and runner name are all pre-filled in the generated command, so no manual substitution is needed.

After running the configure commands, your runner will register and begin running as a daemon. It should appear in the Runners list on the Copia settings page shortly after.

5

Create Your First Workflow

In your Copia repository, create a file at .copia/workflows/hello.yaml with the following content:

Ensure the runs-on value matches the label(s) you entered in the previous step.

.copia/workflows/hello.yaml

name: Hello Copia Actions
on: [push]

jobs:
  greet:
    runs-on: ubuntu-latest
    steps:
      - name: Say hello
        run: echo "Hello from Copia Actions Runners!"

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

      - name: List repository files
        run: ls -la

Commit and push this file to your repository. Because the workflow is triggered on: [push], the act of pushing the file will itself trigger the workflow.

6

View the Results

Navigate to the Actions tab in your repository on Copia. You should see a workflow run in progress or recently completed.

Click on the run to view the job logs and step-by-step output.

What's Next

Now that you have a working runner and a simple workflow, you can:

• Write more complex workflows — with multiple jobs, triggers, and reusable actions. See Workflows.

• Store sensitive configuration — like API keys and credentials, using secrets. See Secrets.