CI - docs

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.

Setting this up requires the org:service-accounts and org:trusts org scopes, plus your organization id. See Required Synthetiq permissions and check yours with synthetiq whoami.

Issue the two certificates

Request both ACM certs, add the 2 validation CNAMEs at your DNS provider, and wait for ISSUED. Note the two ARNs. See Certificates. (Validation can take a while — start it first.)

Create the GitHub repo

Create a private repo from SynthetiqAI/infra-template — it ships the workflow, a pinned @synthetiq/cli, the private-registry .npmrc, and an _infra/ skeleton:

gh repo create <github-org>/synthetiq-infra \
  --template SynthetiqAI/infra-template --private

Or use Use this template in the GitHub UI.Then add the SYNTHETIQ_NPM_KEY repo secret (Settings → Secrets and variables → Actions → Repository secrets).

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

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

Create the Synthetiq service account

Find the role id for CI Provision Apply:

synthetiq role list

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

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:

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

See Service Account.

Set up the repo locally

Clone the repo:

gh repo clone <github-org>/synthetiq-infra
cd synthetiq-infra

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

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:

    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 for the full workflow it wraps.

Author the config and open the PR

On a branch, generate the config:

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.Commit the workflow edit, the lockfile, and the config together, then push and open the PR:

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.

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 for more details.

To update later: edit the config — or let a dependency bot like Renovate or Dependabot open the version-bump PR — and the same PR → review → merge loop applies it.