Run workflows
Avrea CI reads .yml and .yaml files directly inside .avrea/workflows/.
Use GitHub Actions YAML for jobs, steps, expressions, and supported triggers.
Push and pull request triggers
Section titled “Push and pull request triggers”This workflow runs tests for pushes to main, pull requests targeting main,
and manual invocations:
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.shReplace ./scripts/test.sh with your project's test command. Standard checkout
of the workflow's repository works without adding a GitHub token.
| Trigger | Behavior |
|---|---|
push | Runs from the pushed branch or tag. Supports branch, tag, and path filters. Deleting a branch or tag does not start a run. |
pull_request | Defaults to opened, synchronized, and reopened pull requests. Use types for other supported pull request activities. Branch filters match the target branch. |
workflow_dispatch | Runs 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.
Approve fork pull requests
Section titled “Approve fork pull requests”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:
- 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. - Select the pending request for the commits you reviewed. Read its
admission_id,expires_at, andpull_request_context. - Send
POST /orgs/{org_id}/repos/{repo_id}/workflow-admissions/{admission_id}/approvalswith a JSON body containing the exacthead_shaandbase_shafrom that request'spull_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.
Manual runs
Section titled “Manual runs”- Add
workflow_dispatchand commit the workflow to the repository's default branch. The selected branch or tag must also contain that workflow withworkflow_dispatchdeclared. - Open the repository's Workflows tab in the Avrea console.
- Find the workflow labeled Avrea CI, choose Run workflow, select the branch or tag, and fill in its inputs.
- 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:
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.
Managed configuration
Section titled “Managed configuration”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.
Jobs, outputs, and matrices
Section titled “Jobs, outputs, and matrices”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:
name: Matrix testson: 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.
Reusable workflows
Section titled “Reusable workflows”Push workflows can call local or authorized cross-repository workflows with
job-level uses. The called workflow must declare workflow_call:
name: Testson: push
jobs: test: uses: ./.avrea/workflows/test-shared.yml with: suite: uniton: 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.
Concurrency
Section titled “Concurrency”Use a concurrency group to avoid running obsolete work on the same branch:
concurrency: group: ci-${{ github.workflow }}-${{ github.ref }} cancel-in-progress: trueGroups 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.
Rerun a workflow
Section titled “Rerun a workflow”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.
Inspect and troubleshoot runs
Section titled “Inspect and troubleshoot runs”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.