# What is CI?

CI runs the workflow files in your repositories on every push, pull request, tag or manual start, on machines the platform creates or on machines you own.

A workflow is a file in your repository. When a push, a pull request, a merge queue build or a
manual start matches its triggers, CI starts a **run**: it plans the file at that commit, gets a
machine, executes the jobs, streams their logs to the console and reports the result on the commit,
where branch protection can require it before a merge.

CI reads two formats side by side:

- **The native format**, in `.dcloud/workflows/` (and `.ews/workflows/` in repositories set up
  before the rename; a file in `.dcloud/workflows/` wins over one of the same name). Every key it
  accepts is listed in [Workflow syntax](/docs/workflows).
- **GitHub Actions**, in `.github/workflows/`, run as they are, with `uses:` actions, matrices,
  environments, variables and OIDC tokens. See [Run GitHub Actions workflows](run-github-actions-workflows.md).

## When to use it

- Test every pull request and make the result a required check.
- Build a container image from the default branch or a version tag and push it to your registry.
- Keep running the GitHub Actions workflows a repository already has, without rewriting them.
- Run macOS or iOS builds on a Mac you own, or GPU jobs on your own machine.

## Concepts

| Term         | Meaning                                                                                                                                                          |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Workflow     | A YAML or JSON file in a workflow folder of the repository. See [Workflows and runs](workflows-and-runs.md).                                                     |
| Run          | One execution of one workflow at one commit, numbered per repository.                                                                                            |
| Job          | A named group of steps in a workflow. Jobs with no `needs` between them run at the same time.                                                                    |
| Runner       | A machine you registered that takes work matching its labels. See [Runners and runner groups](runners-and-groups.md).                                            |
| Runner group | Which repositories, refs and events may reach the runners in it.                                                                                                 |
| Runner pool  | Machines the platform starts in your organization for GitHub-syntax jobs whose labels the pool carries, and stops when the work is done.                         |
| Environment  | A deployment target of a repository, with branch rules, reviewers and a wait timer, for GitHub-syntax jobs. See [Protect a deployment](protect-a-deployment.md). |
| Run identity | The service account a run acts as: one per repository, named `ci-` and the first eight characters of the repository's id.                                        |

## Pricing

- **Job minutes**: every started minute of a platform machine that runs your workflow.
- **Self-hosted runner minutes**: minutes on runners you registered are recorded, at €0.
- **Runner pools**: their machines are instances of your organization and are billed as instances.
- **Logs, artifacts and caches** the organization keeps are measured daily as stored data.

Your organization's price list on **Pricing** has the rates.

## Interfaces

- The console: **Runs** and **Runners** under CI, and each repository's **CI** tab.
- The CLI: `dcloud ci …` (see the _CLI Command Reference_).
- The API under `/ci/api` (see the _API Reference_).
- Terraform: `dcloud_ci_runner_group`.

Workflow files themselves are commits in a repository: add one with `git push` or in the console
(see [Add a workflow](add-a-workflow.md)).

## Next steps

- [Getting started](getting-started.md)
- [Add a workflow](add-a-workflow.md)
- [Register a runner](register-a-runner.md)
