# What's supported GitCafe reads workflow files with GitHub's own workflow parser and expression engine, so [GitHub's workflow syntax reference](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax) applies. Jobs run on GitHub's official runner, which evaluates steps itself. This page lists where GitCafe differs: what is **not yet** supported, and what **never** will be because it belongs to github.com. Anything not listed works as on GitHub. To get started, see [run your GitHub Actions workflows](https://git.cafe/docs/ci/actions.md). ## Workflow files - Workflows are `.yml` or `.yaml` files directly in `.github/workflows/`. Subdirectories, symlinks and submodules there are skipped. - GitCafe reads the files at the exact commit being tested, sorted by path, at most 32 of them, each at most 64 KiB. - When a workflow is invalid, you get a failed run listing up to 20 problems, each with its location, as GitHub reports them. ## At a glance | Feature | Supported | Notes | | ------------------------------------------------------------------------------------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------- | | `name`, `env`, `defaults`, `permissions` | Yes | `permissions` is passed to the runner, but `GITHUB_TOKEN` can only read the repository ([tokens](https://git.cafe/docs/ci/workflow-syntax.md#the-github_token)). | | `run-name` | Accepted | Runs show the workflow's `name`. | | `on: push`, `pull_request`, `workflow_dispatch` | Yes | See [triggers](https://git.cafe/docs/ci/workflow-syntax.md#triggers). | | Other events (`schedule`, `release`, `issues`, `workflow_run`, ...) | Not yet | Accepted in the file, but never start a run. | | `on: pull_request_target`, runs for fork pull requests | Not yet | [Pull requests from forks](https://git.cafe/docs/ci/actions.md#pull-requests-from-forks) don't run. | | `on: workflow_call` (local reusable workflows) | Yes | `uses: ./.github/workflows/.yml` at the same commit, with `with`, `secrets` (or `inherit`) and outputs. | | Reusable workflows from other repositories (`owner/repo/...@ref`) | Not yet | Rejected with a message. | | `jobs..runs-on` labels, `runs-on.group` | Yes | [Where jobs run](https://git.cafe/docs/ci/actions.md#where-jobs-run). With `group`, the job runs on that runner group's runners. | | `needs`, `if`, job `outputs`, `strategy` (`matrix`, `fail-fast`, `max-parallel`) | Yes | `include`, `exclude` and `fromJSON` matrices too. | | `timeout-minutes`, `continue-on-error`, `cancel-timeout-minutes` | Yes | `timeout-minutes` at most 360. | | `concurrency` (workflow and job), `cancel-in-progress` | Yes | Groups apply within one repository. | | `environment` | Partly | The name is shown on the job; no protection rules, environment secrets or variables. | | `container`, `services` | Yes | Need Docker on the runner: GitCafe-hosted runners have it; your Linux runners need it installed. | | `jobs..snapshot` | Never | GitHub-hosted custom images; rejected. | | Steps: `run`, `shell`, `working-directory`, `env`, `if`, `id`, `name`, `continue-on-error`, `timeout-minutes` | Yes | Run by the runner as on GitHub. | | Steps: `uses` JavaScript, composite and Docker actions, `docker://` images | Yes | See [actions](https://git.cafe/docs/ci/workflow-syntax.md#actions). | | `GITHUB_OUTPUT`, `GITHUB_ENV`, `GITHUB_PATH`, step outputs | Yes | | | `GITHUB_STEP_SUMMARY` | Not yet | Accepted, not shown. | | Expressions, contexts and functions, `hashFiles()` | Yes | GitHub's expression engine; `vars`, `secrets`, `inputs`, `matrix`, `needs`, `strategy`, `job`, `steps`, `runner`, `github`. | | Artifacts (`actions/upload-artifact@v4`, `download-artifact@v4`) | Not yet | The actions refuse servers other than github.com. | | `actions/cache` | Not yet | No cache service. | | OIDC tokens (`id-token: write`) | Not yet | Jobs get no OIDC token. | ## Triggers - **`push`** runs for branches only, never for tags or deletions. `branches`, `branches-ignore`, `paths` and `paths-ignore` work as on GitHub, including `!` negations. When GitCafe can't tell which files a push changed, `paths` filters let the workflow run. - **`pull_request`** runs when a pull request is opened, reopened or its head branch moves. `branches` and `branches-ignore` match the base branch; path filters match the pull request's changes. Every event is the `synchronize` activity type, so a `types` list must include `synchronize` (the default does). - **`workflow_dispatch`** runs with `cafe ci dispatch`; the web UI has no **Run workflow** button yet. `inputs` are declared as on GitHub and take their `default` values; you can't type values yet. ## Actions `uses: owner/repo@ref` (and `owner/repo/path@ref`) downloads the action from public github.com, as GitHub does: pin a tag, a branch or a full commit SHA. JavaScript actions run on the runner's Node, composite actions run their steps, Docker actions build or pull their image on the runner. - `actions/checkout` clones from GitCafe with the job's `GITHUB_TOKEN`. - `actions/setup-node`, `setup-python` and other `setup-*` actions work; on GitCafe-hosted runners, Node and Python are preinstalled and others are downloaded. - Private actions on github.com can't be used: GitCafe downloads anonymously. - An action whose `owner/repo` is also the name of a GitCafe repository is refused for now. - Actions that call the GitHub API reach GitCafe's (`${{ github.api_url }}`), which implements few endpoints; see [what works differently](https://git.cafe/docs/ci/actions.md#what-works-differently). ## The `GITHUB_TOKEN` Each job gets a `GITHUB_TOKEN` (`${{ secrets.GITHUB_TOKEN }}`, `${{ github.token }}`) valid while the job runs. Whatever `permissions` say, it can only read the job's own repository: clone it, fetch it, and read the repository through GitHub's REST API as `actions/checkout` does. It can't push, comment or create releases. ## Variables and contexts The runner sets the usual `GITHUB_*` and `RUNNER_*` variables. On GitCafe: | Variable | Value | | ------------------- | --------------------------------------------------------- | | `GITHUB_SERVER_URL` | the GitCafe server, such as `https://git.cafe` | | `GITHUB_API_URL` | the server's `/api/v3`, such as `https://git.cafe/api/v3` | | `GITHUB_REF` | `refs/pull//head` for pull requests | | `GITHUB_SHA` | the commit being tested (a pull request's head commit) | | `GITHUB_RUN_ID` | a number, as on GitHub | `secrets` and `vars` hold the repository's and organization's [secrets and variables](https://git.cafe/docs/ci/secrets-and-variables.md). ## Limits | Limit | Value | | --------------------------------------------------------- | ------------------------------------------- | | Workflow files read per commit | 32 | | Workflow file size | 64 KiB | | Jobs per workflow | 256 | | Matrix combinations per job | 256 | | Concrete jobs per run (all matrices and called workflows) | 1,000; exceeding this fails startup | | Reusable workflow nesting | 4 levels, 20 called files per run | | `timeout-minutes` | default and maximum 360 | | Run wait for runners | 24 hours, on top of its jobs' time limits | | Job log kept | 4 MiB per job attempt; older output dropped | | Problems reported per invalid file | 20 |