Add a workflow

Write a workflow file, check it with the same parser a push runs, and commit it to the repository.

Last updated 18 November 2026View as Markdown

A workflow is a file in the repository: committing it is a push like any other, refused by the same branch protection rules. Every key of the native format is in Workflow syntax.

Prerequisites

  • git:PushRepository on the repository to commit the file. In the console, without it the Add a workflow page shows an access-denied notice.
  • In the console, also git:GetRepository on the repository (without it the page is not found) and ci:ListRuns on the repository to open its CI tab. Without git:PushRepository the tab does not offer Add a workflow.
  • To check a file, in the console as through the CLI or the API, ci:ListRuns on all of CI (rn:ews::<organization id>:ci:*). Without it the console's check reads "Could not check this file: …"; you can still commit the file.
  • A repository that is not archived, a mirror or still importing: those refuse every commit.

Write, check and commit the file

  1. Open the repository, then open its CI tab.
  2. Choose Add a workflow.
  3. Under Start from a template, choose Test on every pull request, Build and push an image or Build on macOS; or convert a file you have (see Convert a workflow); or write the file yourself.
  4. For File path, keep the proposed path or enter another .yml or .yaml file directly in .dcloud/workflows/ (or .ews/workflows/). The console adds native-format files only; commit a GitHub-syntax file with Git.
  5. Edit the file under Workflow file. Below it the page says "This file parses. It runs when its triggers match.", or lists the problems.
  6. Choose Commit to main (the repository's default branch).
  7. (Optional) For Commit message, enter a message.
  8. Choose Commit. For a file with problems the button reads Commit anyway; every run of such a file is refused until they are fixed.

The console opens the CI tab. If you leave the page before committing, what you wrote is kept for the next time.

Result

The file is on the default branch. It starts a run from the next event its triggers match; a push trigger on that branch matches the commit that added it. A file that does not parse never blocks a push, but starts no run.

The console's Add a workflow is offered on a repository's CI tab when the tab lists runs, or when the repository has no workflow yet.

Did this page help you?