# 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

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

```yaml title=".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.

| 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

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](/avrea-ci/compatibility/#fork-pull-requests)
before approving a run.

## Manual runs

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:

```yaml title=".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.

### 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](/avrea-ci/secrets/) in Avrea instead.
An `environment` input does not add an approval gate or configure secret scopes.

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

```yaml title=".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.

## Reusable workflows

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

```yaml title=".avrea/workflows/test.yml"
name: Tests
on: push

jobs:
  test:
    uses: ./.avrea/workflows/test-shared.yml
    with:
      suite: unit
```

```yaml title=".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](/avrea-ci/secrets/#reusable-workflow-configuration)
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

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

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

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

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](/avrea-ci/compatibility/), 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](/observability/).