FAQs

Frequently asked questions about Copia Actions Runners, including compatibility with GitHub Actions, security, troubleshooting, and platform support.

General

Do I need to enable Actions on each repository?

Yes. Actions are enabled per-repository. Go to your repository on Copia, then Settings > Actions, and check Enable Repository Actions.

Where do workflow files go?

Workflow files are stored in the .copia/workflows/ directory of your repository, with a .yaml or .yml extension. For example: .copia/workflows/ci.yaml.

Can I trigger a workflow manually?

Yes. Add workflow_dispatch to your workflow's on: triggers, then use the Run Workflow button on the Actions tab in the Copia UI.

Can I run workflows on a schedule?

Scheduling workflows is not available at this time.

Compatibility with GitHub Actions

How compatible is Copia Actions with GitHub Actions?

Copia Actions workflow syntax is designed to be largely compatible with GitHub Actions. Most GitHub Actions workflows can be adapted with minimal changes. The main differences are:

• Workflow files go in .copia/workflows/ instead of .github/workflows/.

• Some advanced syntax features are not yet supported (see below).

• Actions are downloaded from GitHub by default, but you can use absolute URLs to reference actions from any Git repository.

Which GitHub Actions syntax features are not supported?

The following workflow syntax features are currently not supported and will be ignored if present:

Feature	Notes
concurrency	Running a single job at a time is not enforced
permissions / jobs.<job_id>.permissions	Job-level permission scoping is not available
jobs.<job_id>.timeout-minutes	Job timeouts are not enforced via this field
jobs.<job_id>.continue-on-error	Jobs will not continue on error
jobs.<job_id>.environment	Environment protection rules are not available
Complex runs-on	Only runs-on: label or runs-on: [label] is supported

Are there any other differences from GitHub Actions?

Yes, a few additional differences to be aware of:

• Package registry tokens: The automatic job token cannot currently publish to package registries. Use a Personal Access Token (PAT) stored as a secret instead.

• Problem matchers: Scanning action output for regex patterns and surfacing annotations in the UI is not supported.

• Error annotations: Not supported.

• Expression functions: Only always() is supported as a status check function.

• Pre/Post steps: These run correctly, but do not have their own section in the job log UI.

• Service containers: These run correctly, but do not have their own section in the job log UI.

• Pull request ref: For pull_request events, the ref is refs/pull/:prNumber/head (the PR head), not refs/pull/:prNumber/merge (the merge preview) as in GitHub Actions.

Can I use actions from GitHub?

Yes. By default, actions referenced without a full URL (like actions/checkout@v4) are downloaded from GitHub. You can also use absolute URLs to reference actions from any accessible Git repository:

example: uses with 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.

Should I use `${{ github.xyz }}` or `${{ gitea.xyz }}` in my workflows?

Both ${{ github.xyz }} and ${{ gitea.xyz }} are supported and behave identically. You can use either. We recommend ${{ github.xyz }} for maximum compatibility if you also use GitHub Actions.

Runners

What operating systems are supported for runners?

The runner binary is available for Linux, macOS, and Windows. Other operating systems may work if supported by Go and Docker, but are untested.

When running jobs directly on the host (not in Docker containers), be aware of environment differences. For example, bash is typically not available on Windows — you will need to set powershell as the default shell:

example: set default shell to powershell

defaults:
  run:
    shell: powershell

Can I register runners at the organization level or repository level?

Runners can be registered at two levels:

• Organization level — The runner serves all repositories in your organization.

• Repository level — The runner serves only that specific repository.

A repository may use organization-level runners even if it has its own repository-level runners.

What are runner labels and how do they work?

Labels determine which jobs a runner can accept and how those jobs are executed. When a workflow specifies runs-on: ubuntu-latest, the job is routed to a runner with a matching ubuntu-latest label.

Labels also encode the execution mode. For example:

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

• linux_amd64:host — Run directly on the host machine

See Runner Setup — Labels for details.

What if `runs-on` specifies multiple labels like `[label_a, label_b]`?

This is valid syntax. It means the job should run on a runner that has both labels. The runner must have all specified labels registered.

What is the difference between agent labels and custom labels?

Agent labels are reported to Copia by the runner during registration. Custom labels can be added manually by an administrator. However, a custom label may not map to an environment the runner knows how to handle. If you need to change a runner's labels, we recommend re-registering the runner or updating the runners.labels section in the runner's config.yaml and restarting.

Can I use Copia-hosted runners?

Not at launch. Copia Actions Runners currently supports self-hosted runners only — you provide and manage the machines that execute jobs. Copia-hosted runners are planned for a future release.

Security

What permissions does a runner have?

Idle runners have no standing permissions on your Copia instance. They can only connect and poll for jobs. Once a job is assigned, the runner receives a temporary, scoped token that grants read-only access to the repository associated with that job. The token expires when the job completes.

Additional permissions can be granted to the runner using personal access tokens (PATs) and Secrets.

Can I push to my repository?

Yes. Your actions runner has read-only permissions to your repository by default, but you can allow write operations (e.g. pushing commits) using personal access tokens (PATs) and Secrets. Start by creating a personal access token. Personal access tokens are tied to a Copia user account and are managed in the user's settings. In your user settings, click "Applications" in the left-hand navigation menu. Give the token a name and click "Generate Token". Ensure the user has write access to the repo you want to push to. In your repository or organization settings, click "Secrets" in the left-hand navigation menu. Add a new Secret and paste the personal access token you just created in the Secret's "Value" field. Add the "token" field to the actions/checkout step in your workflow file (replace "YOUR_SECRET_NAME_HERE" with the actual name of the secret you created):

- uses: actions/checkout@v5
  with:
    token: ${{ secrets.YOUR_SECRET_NAME_HERE }}

How do I protect against malicious workflows?

There are two main threat vectors: untrusted runners and malicious workflows.

An untrusted runner could steal code or secrets from jobs it executes. Only register runners you control on trusted infrastructure. Only provide runners to organizations and repositories you trust. Run jobs in Docker containers for isolation. Avoid host mode unless necessary. Use ephemeral runners for high-security environments — they execute one job and terminate. A workflow could run harmful code on your runner. Only register runners you control on trusted infrastructure. Only provide runners to organizations and repositories you trust. Run jobs in Docker containers for isolation. Avoid host mode unless necessary. For pull requests from forks, require approval before workflows run. Use ephemeral runners for high-security environments — they execute one job and terminate.

Why should I use Docker mode?

Docker mode runs each job in a fresh, isolated container. This prevents jobs from:

• Interfering with each other

• Leaving artifacts on the runner host

• Accessing the runner's filesystem or other processes

It also ensures reproducibility — the same Docker image produces the same environment every time.

Troubleshooting

My runner shows as "Offline" in the Copia UI

• Verify the runner process is still running (./act_runner daemon or the Docker container).

• Check that the runner can reach your Copia instance over the network.

• If using a self-hosted Copia instance, confirm the instance URL is correct and not a loopback address.

Jobs fail with "checkout" errors

• Ensure the job container can reach your Copia instance. The actions/checkout action clones your repository by connecting to the instance URL.

• Do not use 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.

Windows runner fails because `bash` is not found

On Windows, bash is not available by default. Set powershell as the default shell for your workflow:

example: set default shell to powershell

defaults:
  run:
    shell: powershell

Or per-step:

example: per-step powershell

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

The `.runner` file is corrupted

If the .runner file (created during registration) becomes corrupted or the runner fails to start, delete the file and re-register:

example: re-register runner

rm .runner
./act_runner register --no-interactive --instance https://app.copia.io --token <token> --name <name>

Git LFS files fail to download in workflows

There is a known LFS bug in GitHub's checkout action that causes duplicate Authentication headers to be sent in requests, resulting in HTTP 400 Bad Request responses from our server. If you are seeing these kinds of errors, there are two remediations you may try: For actions/checkout@v5 (and lower versions):

- uses: actions/checkout@v5
  with:
    lfs: false
    persist-credentials: true
- run: |
    git lfs install --local
    $AUTH = git config --local "http.${{ github.server_url }}/.extraheader"
    git config --local --unset "http.${{ github.server_url }}/.extraheader"
    git config --local "http.${{ github.server_url }}/${{ github.repository }}.git/info/lfs/objects/batch.extraheader" "$AUTH"
    git lfs pull

For actions/checkout@v6, create a new personal access token for a Copia user who has (at minimum) read access to the repository you are trying to clone. Then, create a new repository or organization "Secret" with the token as the value. Finally, use the secret in the workflow as shown below:

- uses: actions/checkout@v6
  with:
    lfs: false
    persis-credentials: false
- run: |
    git lfs install --local
    $encodedToken = [uri]::EscapeDataString($env:COPIA_TOKEN)
    git remote set-url origin "https://x-access-token:[email protected]/${{ github.repository }}.git"
    git lfs pull
  env:
    COPIA_TOKEN: ${{ secrets.COPIA_TOKEN }}

Note for Self-Hosted Copia customers: All troubleshooting steps apply equally. Replace https://app.copia.io with your instance URL.