# How SquidCI works

> The parts of SquidCI and how a push becomes jobs — organizations and regions, execution planes, runs, components, sections and jobs, checks and environments.

## Organizations and regions

Everything in SquidCI belongs to an **organization**: its members, the GitHub
accounts and AWS accounts it has connected, its runs. You sign in as yourself
and work in one organization at a time, switched from the top bar.

An organization works in a **region**: a SquidCI deployment, in one place,
holding the organization's data. The region picker in the top bar chooses
it. A region is about where SquidCI keeps your organization's records, not
where your builds run — they run in your AWS account, in whatever AWS region
you chose for it. What you set up in one region stays in that region.

## Your AWS account: the execution plane

Builds run in **your** AWS account, in an **execution plane**: the
CloudFormation stack you create from the **aws** page. It holds the roles and
functions SquidCI's work needs, and the **worker groups** jobs run on — pools
of EC2 instances, or Lambda functions. Workers ask SquidCI for work; nothing
in your account accepts connections from outside. See
[Execution planes](/docs/concepts/execution-planes/).

## GitHub

The SquidCI GitHub App tells SquidCI about pushes and pull requests to the
repositories you grant it, and lets it mint short-lived tokens your workers
clone with. Builds are enabled per repository, on the **github** page.

## From a push to jobs

1. **A push to an enabled repository's default branch**, or a pull request to
   it, makes a **run** of that commit.
2. SquidCI reads the commit's `.squidci/pipelines.yaml`. A file it cannot use
   ends the run as an **invalid pipeline**, saying why.
3. The file names **components** — a part of the repository built on its own,
   like `web` or `infra` — each with steps under **sections**: `check`, `test`,
   `build`, `publish`, `run` and `deploy`. **Each section of each component is
   one job**, its steps run in order.
4. Jobs run at once unless something orders them: `publish` waits for its
   component's build, check and test; `deploy` waits for every check, test
   and build in the run;
   `needs` and `after` make one component wait for others.
5. A job goes to a worker group of the right kind, in an execution plane that
   offers what the job needs, and runs there in a container — or as code in a
   Lambda function.
6. Each job is a **check** on the commit in GitHub, and its log is live on its
   page in SquidCI.

A component whose files have not changed since it last succeeded is not run
again: its jobs end **unchanged**, which counts as passing. Deploys always run.

## Pull requests

A pull request's head commit runs the file's `check`, `test` and `build`
sections and nothing else: no `publish`, `run` or `deploy`, and no AWS access,
because until someone merges it the file is its author's. A new push to the
pull request cancels its runs still going. Pull requests from forks are not
built.

## Versions and environments

Every push to the default branch whose checks, tests, builds and publishes all
pass is a **version**. Versions are deployed to **environments** — dev,
staging, prod — in an order you declare, each with its own AWS access. The
**deploy** page shows what each environment runs and deploys any version by
hand. See [Environments and deploys](/docs/concepts/environments/).