Getting started

You need an AWS account you can create a CloudFormation stack in with IAM capabilities, and admin rights on the GitHub account or organization whose repositories you want to build. If you would rather an agent did most of this, see Set up with a coding agent — the AWS and GitHub steps below are still yours to click.

1. Sign up and pick a region

Sign up at squidci.app. SquidCI works per organization, so create one, or accept an invitation to one.

The organization then chooses a region: where SquidCI keeps its data about your organization — runs, logs’ metadata, settings. This is SquidCI’s region, not where your builds run; that is the AWS region you choose in the next step, and the two need not match. The region picker is in the top bar.

2. Connect an AWS account

Open aws in the top bar.

1. Enter the aws account id (twelve digits) and the AWS region your builds should run in, then continue.
2. Under Finish setting up your account, follow open CloudFormation ↗. It opens the AWS console in that account and region with the stack filled in. Check the console really is in that account and region, then create the stack. It needs CAPABILITY_IAM: it creates the roles it lists, and nothing else. The link carries a one-time token, so don’t share it; it expires after a day, and the page offers a new one.
3. Back in SquidCI, the checklist ticks off as the stack reports in: stack created in your account, resources deployed, then challenge answered from your account. The account then shows ● connected.

If the stack was created in the wrong account or region, the page says so. Delete that stack where it is and open the same link again in the right place.

The stack gives SquidCI no credentials for your account: see Security for what it creates.

3. Add a worker group

A connected account has nowhere to run builds until it has a worker group. Under the account, choose + add a worker group:

• EC2 instances — jobs in containers is what most pipelines want. Choose an instance type (the default, c7i.large, has 2 vCPUs), a size of 0 to 4 instances, and on-demand or spot. Zero at the bottom means nothing runs, and nothing costs, while there is no work.
• Lambda — a function per job runs pipelines that ask for runner.lambda: short TypeScript or JavaScript steps, with no shell or Docker.

Create it. Instances start when jobs are queued and stop once idle. See Execution planes for the settings.

Note

A new AWS account can run only 10 Lambda functions at once in a region, and SquidCI’s own functions in your account share that. The account’s drawer shows the figure, and links to the AWS page to request more.

4. Connect GitHub

Open github and connect a GitHub account. GitHub asks where to install the SquidCI app and which repositories it may see. Back in SquidCI, the repositories you granted are listed: open one and enable builds.

SquidCI reads what changes in your repositories and reports checks back. Your code is cloned by the workers in your account, never by SquidCI.

5. Add a pipeline file

In the repository, create .squidci/pipelines.yaml. The smallest useful one:

# yaml-language-server: $schema=https://squidci.com/schema/pipelines.json
app:
  check:
    - make lint
  test:
    - make test

app is a component; check and test are sections, each a job, run at once. For a Node project using pnpm:

# yaml-language-server: $schema=https://squidci.com/schema/pipelines.json
web:
  check:
    - pnpm: lint
  test:
    - pnpm: test
  build:
    - pnpm: build

A pnpm step sets Node up as your .nvmrc pins it and installs the lockfile first. The first line lets editors with the YAML language server check the file as you type. The pipeline file covers the rest.

6. Push

Push to the default branch. The run appears on build within seconds, its jobs under each component, and their logs live on each job’s page. On GitHub, the commit gets a check per job.

A pull request runs its checks, tests and builds the same way. Pull requests from forks are not built yet.

Next

• Deploy to environments, in order, every version or by hand.
• Give jobs AWS access to the accounts they deploy to.
• Post deploys to Slack.