Skip to content

Run workflows

Avrea CI reads .yml and .yaml files directly inside .avrea/workflows/. Use GitHub Actions YAML for jobs, steps, expressions, and supported triggers.

This workflow runs tests for pushes to main, pull requests targeting main, and manual invocations:

.avrea/workflows/test.yml
name: Tests
on:
push:
branches: [main]
pull_request:
branches: [main]
workflow_dispatch:
jobs:
test:
runs-on: avrea-ubuntu-24.04
timeout-minutes: 20
steps:
- uses: actions/checkout@v7
- run: ./scripts/test.sh

Replace ./scripts/test.sh with your project's test command. Standard checkout of the workflow's repository works without adding a GitHub token.

TriggerBehavior
pushRuns from the pushed branch or tag. Supports branch, tag, and path filters. Deleting a branch or tag does not start a run.
pull_requestDefaults to opened, synchronized, and reopened pull requests. Use types for other supported pull request activities. Branch filters match the target branch.
workflow_dispatchRuns a selected branch or tag with validated inputs. Requires repository write access.

Push path filters compare changed files; tag pushes do not use path filters. If Avrea cannot determine the changed files, push path filters count as matched. This includes new branches, rewritten histories, comparisons exceeding 1,000 commits, and comparison timeouts.

Pull request path filters use changes relative to the merge base. For an open pull request, Avrea CI tests the verified merge commit, with github.sha and checkout pointing to that commit. Its GitHub check is attached to the pull request head. Resolve merge conflicts before expecting a pull request run.

Fork pull requests targeting public repositories need approval from a repository writer through the Avrea API. Sign in as an Avrea organization member with current GitHub write access to the target repository, then:

  1. List approval requests with GET /orgs/{org_id}/repos/{repo_id}/workflow-admissions?pull_request_id={pull_request_id}. Use the Avrea pull request ID, rather than its GitHub number.
  2. Select the pending request for the commits you reviewed. Read its admission_id, expires_at, and pull_request_context.
  3. Send POST /orgs/{org_id}/repos/{repo_id}/workflow-admissions/{admission_id}/approvals with a JSON body containing the exact head_sha and base_sha from that request's pull_request_context.

Approve within 30 minutes of Avrea receiving the pull request event. Expired requests or changed commits return HTTP 409. Approval applies only to that event's head and base commits; a new event or changed head or base needs new approval.

Review the fork-run restrictions before approving a run.

  1. Add workflow_dispatch and commit the workflow to the repository's default branch. The selected branch or tag must also contain that workflow with workflow_dispatch declared.
  2. Open the repository's Workflows tab in the Avrea console.
  3. Find the workflow labeled Avrea CI, choose Run workflow, select the branch or tag, and fill in its inputs.
  4. Submit the run. It appears in the workflow's runs once it starts. A run that cannot start is listed as failed, with the reason.

Inputs support string, boolean, number, choice, and environment types:

.avrea/workflows/smoke.yml
name: Smoke test
on:
workflow_dispatch:
inputs:
suite:
description: Test suite
type: choice
options: [quick, full]
default: quick
verbose:
description: Enable verbose output
type: boolean
default: false
jobs:
test:
runs-on: avrea-ubuntu-24.04
env:
TEST_SUITE: ${{ inputs.suite }}
steps:
- uses: actions/checkout@v7
- run: ./scripts/smoke.sh "$TEST_SUITE"
- if: ${{ inputs.verbose }}
run: echo "Verbose output enabled"

The inputs context preserves booleans and numbers. The github.event.inputs context contains their string representations. Use inputs.verbose for a boolean condition. Pass user input to shell commands through environment variables and quote it, as in the example.

Manual runs accept branches and tags, not raw commit SHAs. If a branch and tag share a name, use refs/heads/name or refs/tags/name to disambiguate. The selected commit is fixed when the request is accepted, even if the ref moves while the run waits. Each new manual invocation can run the same commit again.

Avrea secrets and variables are supported for push and manual runs when enabled for the repository. Manual runs require current GitHub repository write access and active Avrea organization membership. Pull request runs cannot use managed configuration, including same-repository pull requests.

Inputs are not a place for credentials. Configure secrets and variables in Avrea instead. An environment input does not add an approval gate or configure secret scopes.

Use needs to run a job after another job, and $GITHUB_OUTPUT to expose step outputs. Each job runs in a separate VM, so files do not carry over between jobs automatically.

Static matrices and matrices generated from completed job outputs are supported. This example defines two independent test jobs at runtime:

.avrea/workflows/matrix.yml
name: Matrix tests
on: push
jobs:
prepare:
runs-on: avrea-ubuntu-24.04
outputs:
matrix: ${{ steps.define.outputs.matrix }}
steps:
- id: define
run: echo 'matrix={"suite":["unit","integration"]}' >> "$GITHUB_OUTPUT"
test:
needs: prepare
runs-on: avrea-ubuntu-24.04
strategy:
fail-fast: false
max-parallel: 2
matrix: ${{ fromJSON(needs.prepare.outputs.matrix) }}
env:
TEST_SUITE: ${{ matrix.suite }}
steps:
- uses: actions/checkout@v7
- run: ./scripts/test.sh "$TEST_SUITE"

max-parallel limits simultaneous jobs in that matrix. Overall run capacity and organization limits also apply. A workflow can expand to at most 256 jobs in total. An invalid matrix, including one with no resulting jobs, fails the job that uses it.

Push workflows can call local or authorized cross-repository workflows with job-level uses. The called workflow must declare workflow_call:

.avrea/workflows/test.yml
name: Tests
on: push
jobs:
test:
uses: ./.avrea/workflows/test-shared.yml
with:
suite: unit
.avrea/workflows/test-shared.yml
on:
workflow_call:
inputs:
suite:
type: string
required: true
jobs:
test:
runs-on: avrea-ubuntu-24.04
env:
TEST_SUITE: ${{ inputs.suite }}
steps:
- uses: actions/checkout@v7
- run: ./scripts/test.sh "$TEST_SUITE"

Local calls use the containing workflow's commit. Remote calls use owner/repository/path@ref; their source revision is fixed for the run. Use a commit SHA when you require a particular remote revision. A private called repository must share the caller's GitHub App installation and have reusable workflow sharing enabled. Public source repositories also require approved access through Avrea. Contact support if a source is unavailable.

Nested calls, typed inputs, declared outputs, and static or dynamic matrices are supported. Calls and their child jobs all count toward the run's job limit. Forward secrets explicitly or with same-owner inheritance at each call level.

Reusable workflows remain unsupported for pull request and manual runs. Within a reusable workflow tree, permission declarations cannot exceed contents: read or a caller's declared permissions; they do not create a GitHub token. Expression defaults for inputs, environments on called workflows, and call-level concurrency or continue-on-error are unsupported.

Use a concurrency group to avoid running obsolete work on the same branch:

concurrency:
group: ci-${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true

Groups are case-insensitive and scoped to the repository. By default, each group holds one running entry and one pending entry; a new entry replaces the older pending one. With cancel-in-progress: true, it also cancels the running entry and waits for that entry to finish stopping.

To keep queued work, use queue: max without cancel-in-progress: true. This retains up to 100 pending entries in arrival order. Additional arrivals are cancelled.

You can set concurrency on the workflow or an individual job. Use different group names at those levels: a job cannot acquire the group already held by its own workflow. Groups do not coordinate with GitHub Actions runs.

Fork pull request workflows cannot use repository concurrency groups.

On a completed run in the console, choose Re-run workflow. Rerun the whole workflow, only failed and cancelled jobs, or selected jobs. A rerun creates a new run ID and increments the attempt number; the original run and logs remain available. You need current GitHub write access.

Selected jobs and their downstream dependents run again. Other jobs retain their results, outputs, and artifacts under their original retention periods. A retained failure still makes the workflow fail. Rerunning a producer rebuilds its downstream dynamic matrices.

Reruns keep the original commit, event, manual inputs, and saved reusable workflow revisions. Secrets and variables for jobs being rerun are resolved again under current policy. Only one attempt in the workflow's lineage may be active at a time. A pull request's head/base commits and approval must still be current; rerunning it does not grant access to managed configuration.

Use the Avrea console to inspect the run, its job dependencies, and step logs. Follow the check's details link from GitHub to the Avrea run. Workflow errors and warnings include source locations where available.

  • No run appears: check repository enablement, the workflow location at the event's commit, trigger filters, and whether a push commit requests CI skipping. For forks, check whether approval is pending.
  • The run fails before a job starts: review the workflow error against compatibility and limits, especially runner labels, reusable workflow calls, and configuration references.
  • A job stays queued: check its dependencies, concurrency group, and available runner capacity.
  • An action cannot authenticate: check whether it expects a GitHub token, OIDC, or secrets that are unavailable for that trigger.

For more on logs and job inspection, see Observability.