# Add a workflow

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

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](/docs/workflows).

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

**Console**
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](convert-a-workflow.md)); 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.

**CLI**
Check the file, then commit and push it with Git:

```sh
dcloud ci workflows validate --source "$(cat .dcloud/workflows/ci.yml)"
git add .dcloud/workflows/ci.yml && git commit -m "Add CI" && git push
```

For a GitHub-syntax file, add `--path .github/workflows/ci.yml` so it is checked as GitHub
Actions.

**API**
```http
POST /ci/api/workflows/validate
{ "source": "name: CI\non:\n  push:\n    branches: [main]\njobs:\n  test:\n    steps:\n      - run: make test\n" }
```

The answer is `200` with `{ valid, issues }`, also for an invalid file; each issue names the key
and, where it can, the line. A `path` under `.github/workflows/` checks the file as GitHub Actions.

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

## Related

- [Convert a workflow](convert-a-workflow.md)
- [Workflows and runs](workflows-and-runs.md)
- `ci.workflows.validate` · `dcloud ci workflows validate`
