How SquidCI works

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.

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.