# 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](https://app.copia.io/)
* A machine to host your runner (Linux, macOS, or Windows)

{% stepper %}
{% step %}

### 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.
{% endstep %}

{% step %}

### 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.
{% endstep %}

{% step %}

### 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.

<figure><img src="/files/L9kG1Z15bnUZLnqaKNWb" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### 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.
{% endstep %}

{% step %}

### Create Your First Workflow

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

{% hint style="info" %}
Ensure the `runs-on` value matches the label(s) you entered in the previous step.
{% endhint %}

{% code title=".copia/workflows/hello.yaml" %}

```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
```

{% endcode %}

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.
{% endstep %}

{% step %}

### 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.
{% endstep %}
{% endstepper %}

## 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](/docs/actions/workflows.md).
* Store sensitive configuration — like API keys and credentials, using secrets. See [Secrets](/docs/actions/secrets.md).


---

# 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/getting-started.md?ask=<question>
```

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.