Intercom CI Integration

Overview

Set up CI/CD pipelines for Intercom integrations with GitHub Actions: unit

tests with a mocked SDK (fast, token-free, run on every PR), integration tests

against a dev workspace (gated to main pushes), webhook signature tests, and

encrypted secret management. This SKILL.md carries the workflow at a high level;

the full copy-ready workflow, secret setup, and complete test suites live in

references/ for progressive disclosure.

Prerequisites

• GitHub repository with Actions enabled
• Intercom dev workspace access token (separate from production)
• npm/pnpm project with intercom-client installed

Authentication

CI authenticates to Intercom with a dev workspace access token, never a

production one. Store it as an encrypted GitHub Actions secret

(INTERCOMDEVTOKEN) and expose it to the integration job as the

INTERCOMACCESSTOKEN environment variable. The Intercom SDK and the

/me connectivity check both send it as a bearer token in the

Authorization: Bearer header. The unit-test job never receives a token —

its SDK is fully mocked. Webhook verification uses a separate

INTERCOMWEBHOOKSECRET HMAC secret.

Instructions

Read your existing package.json to confirm the test, typecheck, and

test:integration scripts exist, then work through these steps. Write each

file to the path shown; the deep reference files hold the full contents.

Step 1: GitHub Actions workflow

Write .github/workflows/intercom-ci.yml with two jobs — unit-tests (every

push and PR) and integration-tests (gated to main pushes). The integration

job first probes https://api.intercom.io/me and fails fast on a non-200:

      - name: Verify Intercom connectivity
        run: |
          STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
            -H "Authorization: Bearer $INTERCOM_ACCESS_TOKEN" \
            https://api.intercom.io/me)
          if [ "$STATUS" != "200" ]; then exit 1; fi

Full workflow YAML: references/workflow.md.

Step 2: Configure secrets

Store the dev token (and, if you verify webhooks, the signing secret) with the

gh CLI, then confirm with gh secret list:

gh secret set INTERCOM_DEV_TOKEN --body "dG9rOmRldl90b2tlbl9oZXJl"
gh secret list

Details and the webhook secret: references/workflow.md.

Step 3: Unit tests with a mocked SDK

Write tests/unit/intercom-service.test.ts, mocking the entire

intercom-client module so unit tests are deterministic and need no token.

Cover the happy path plus SDK errors such as a 409 duplicate-contact conflict.

Full mocked suite: references/testing.md.

Step 4: Integration tests against the dev workspace

Write tests/integration/contacts.integration.test.ts using

describe.skipIf(!token) so the suite self-skips without a token, and track

every created contact for cleanup in afterAll. Full suite:

references/testing.md.

Step 5: Webhook signature test

Verify inbound webhook signatures with a constant-time comparison

(crypto.timingSafeEqual). No network needed. Full test:

references/testing.md.

Output

Applying this skill produces:

• .github/workflows/intercom-ci.yml — a two-job pipeline (unit + gated integration).
• tests/unit/intercom-service.test.ts — mocked-SDK unit tests.
• tests/integration/contacts.integration.test.ts — dev-workspace integration tests that self-skip without a token.
• A webhook signature verification test.
• Configured INTERCOMDEVTOKEN (and optional INTERCOMWEBHOOKSECRET) GitHub Actions secrets, confirmed via gh secret list.

On a green run, PRs pass unit tests token-free and main pushes additionally

run live integration tests and upload a coverage artifact.

Error Handling

Examples

Add Intercom CI to an existing repo. Run gh secret set INTERCOMDEVTOKEN,

write the workflow from Step 1, and add the mocked unit suite from Step 3. PRs

now run unit tests with no token; the first main push runs the integration

job against the dev workspace.

Verify webhook handling in CI. Store INTERCOMWEBHOOKSECRET, add the

Step 5 signature test, and CI proves both valid-signature acceptance and

invalid-signature rejection with no network call.

Full worked code for every example — workflow, secrets, and all three test

suites — is in references/workflow.md and

references/testing.md.

Resources

• references/workflow.md — full workflow YAML + secret setup
• references/testing.md — complete unit, integration, and webhook test suites
• GitHub Actions Docs
• GitHub Encrypted Secrets
• Vitest

Next Steps

For deployment patterns once CI is green, see the intercom-deploy-integration

skill, which covers promoting a verified build from the dev workspace to

production with the same secret-management discipline.