> ## Documentation Index
> Fetch the complete documentation index at: https://synthetiq.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CI

> Repo, review, merge — the production setup

Config in git, plan on PR, apply on merge — no stored credentials, and the config author needs no AWS access. Each step links to the page with the details; full background: [CI Integration](https://synthetiq.com/docs/platform-docs/deployments/byoi/ci-integration.md).

> [!NOTE]
>
> Setting this up requires the `org:service-accounts` and `org:trusts` org scopes, plus your [organization id](https://synthetiq.com/docs/platform-docs/deployments/byoi/prerequisites.md#finding-your-organization-id). See [Required Synthetiq permissions](https://synthetiq.com/docs/platform-docs/deployments/byoi/prerequisites.md#required-synthetiq-permissions) and check yours with `synthetiq whoami`.

**1. Issue the two certificates**

Request both ACM certs, add their validation CNAMEs at your DNS provider, and wait for `ISSUED`. Note the two ARNs. See [Certificates](https://synthetiq.com/docs/platform-docs/deployments/byoi/certificates.md). (Validation can take a while — start it first.)

The API certificate only needs `*.api.<domain>` to get started. Optionally, also list the spare shard names `*.s1.api` through `*.s9.api` (one extra validation CNAME each) to plan for capacity: the installation can then [scale past 100 apps](https://synthetiq.com/docs/platform-docs/deployments/byoi/alb-shards.md) with a config pull request, without a new certificate per shard. See [Optional: add spare shard names](https://synthetiq.com/docs/platform-docs/deployments/byoi/certificates.md#optional-add-spare-shard-names-to-the-api-certificate).

**2. Create the GitHub repo**

Create a **private** repo from [`SynthetiqAI/infra-template`](https://github.com/SynthetiqAI/infra-template) — it ships the workflow, a pinned `@synthetiq/cli`, the private-registry `.npmrc`, and an `_infra/` skeleton:

```bash theme={"system"}
gh repo create <github-org>/synthetiq-infra \
  --template SynthetiqAI/infra-template --private
```

Or use [**Use this template**](https://github.com/SynthetiqAI/infra-template/generate) in the GitHub UI.

Then add the **`SYNTHETIQ_NPM_KEY`** repo secret (Settings → Secrets and variables → Actions → Repository secrets).

**3. Create the two AWS roles**

In the target AWS account, create two roles trusting GitHub OIDC, each scoped to the repo you just created. Replace `<github-org>/<repo>` with it — e.g. `acme/synthetiq-infra`:

* **plan** — trusts `repo:<github-org>/<repo>:pull_request`; policy from `synthetiq infra permissions --stage generate`
* **apply** — trusts `repo:<github-org>/<repo>:ref:refs/heads/main`; policy from `synthetiq infra permissions --stage provision`

> [!WARNING]
>
> Some organizations emit **ID-qualified** subjects — `repo:<github-org>@<org-id>/<repo>@<repo-id>:pull_request`. The trust is matched exactly, so the plain form above is then rejected with a bare `Not authorized to perform sts:AssumeRoleWithWebIdentity`. Trust both forms: see [Check the subject your organization sends](https://synthetiq.com/docs/platform-docs/deployments/byoi/ci-integration.md#check-the-subject-your-organization-sends).

Note both role ARNs — you'll add them to the workflow when you set up the repo locally.

**4. Create the Synthetiq service account**

Find the role id for **CI Provision Apply**:

```bash theme={"system"}
synthetiq role list
```

Create the service account with that role (e.g. name it `CI Provisioner`):

```bash theme={"system"}
synthetiq service-account create <name> --role-id <role-id>
```

Create the OIDC trust so CI can authenticate as it — use the same repo as the apply role:

```bash theme={"system"}
synthetiq trust create \
  --service-account-id <service-account-id> \
  --issuer https://token.actions.githubusercontent.com \
  --subject "repo:<github-org>/<repo>:ref:refs/heads/main"
```

The same subject caveat as step 3 applies here, with a different error — `invalid_grant: No OIDC trust is configured for this issuer and subject`. Create a second trust for the ID-qualified form if your organization sends one.

See [Service Account](https://synthetiq.com/docs/platform-docs/deployments/byoi/service-account.md).

**5. Set up the repo locally**

Clone the repo:

```bash theme={"system"}
gh repo clone <github-org>/synthetiq-infra
cd synthetiq-infra
```

Install the pinned CLI (this also generates the lockfile CI installs from):

```bash theme={"system"}
SYNTHETIQ_NPM_KEY=<key> npm install
```

Fill the three values in `.github/workflows/synthetiq-infra.yml` — the two role ARNs (use the ARNs you noted from the roles step; `<your-aws-account-id>` is your 12-digit account number) and your org id:

```yaml theme={"system"}
    with:
      plan-role-arn: arn:aws:iam::<your-aws-account-id>:role/synthetiq-infra-plan
      apply-role-arn: arn:aws:iam::<your-aws-account-id>:role/synthetiq-infra-apply
      organization-id: <your-org-id>
```

See [CI Integration](https://synthetiq.com/docs/platform-docs/deployments/byoi/ci-integration.md) for the full workflow it wraps.

> [accordion] Keeping the infra root in a subdirectory
>
> To nest `package.json`, `.npmrc`, and `_infra/` under a subdirectory (e.g. `partner/synthetiq/`) instead of the repo root — useful inside a shared infrastructure monorepo — move them there together, add `working-directory: partner/synthetiq` to the workflow's `with:` block, and prefix the trigger `paths:` with the same directory. Run the `npm install` and `synthetiq infra` commands in the following steps from inside that directory, and adjust the `git add` paths to match. See [Nested directory layout](https://synthetiq.com/docs/platform-docs/deployments/byoi/ci-integration.md#nested-directory-layout).

**6. Author the config and open the PR**

On a branch, generate the config:

```bash theme={"system"}
git checkout -b add-infra-config
npx synthetiq infra init --domain apps.yourcompany.com
```

With no AWS credentials, init runs in offline mode: enter your VPC and public subnet ids and the two certificate ARNs. See [Generating synthetiq.yaml](https://synthetiq.com/docs/platform-docs/deployments/byoi/configuration.md).

Commit the workflow edit, the lockfile, and the config **together**, then push and open the PR:

```bash theme={"system"}
git add .github/workflows/synthetiq-infra.yml package-lock.json _infra/synthetiq.yaml
git commit -m "Configure Synthetiq infra"
git push -u origin add-infra-config
```

The pull request CI job runs against the real account and posts the proposed CloudFormation diff plus a summary of the proposed changeset as a PR comment.

**7. Review & merge**

Review the diff, then merge. On merge the CI applies the changeset on the target AWS account. The job log ends with the **3 app DNS records** that you will need to configure to finalize the provisioning — this is a one-time setup, only needed on the initial provisioning (unless you later change the `domain` configuration for Synthetiq apps). See [DNS setup](https://synthetiq.com/docs/platform-docs/deployments/byoi/dns.md) for more details.

To update later: edit the config — or let a dependency bot like **Renovate** or **Dependabot** open the [version-bump PR](https://synthetiq.com/docs/platform-docs/deployments/byoi/ci-integration.md#staying-current) — and the same PR → review → merge loop applies it.

When deploys warn that load balancer capacity is low, add a shard the same way: a PR adding `- 1` (then `- 2`, …) under `alb_shards`, then the one DNS record the apply job prints. See [Scaling past 100 apps](https://synthetiq.com/docs/platform-docs/deployments/byoi/alb-shards.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.