# Getting started

> From signing up to a first green run — create an organization, connect an AWS account and GitHub, add a pipeline file, and push.

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](/docs/with-an-agent/) — the AWS and
GitHub steps below are still yours to click.

## 1. Sign up and pick a region

Sign up at [squidci.app](https://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](/docs/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](/docs/concepts/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
# 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
# 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](/docs/pipelines/guide/) 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](/docs/concepts/environments/), in order, every
  version or by hand.
- [Give jobs AWS access](/docs/pipelines/aws/) to the accounts they deploy to.
- [Post deploys to Slack](/docs/slack/).