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
(INTERCOM_DEV_TOKEN) and expose it to the integration job as the
INTERCOM_ACCESS_TOKEN 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
INTERCOM_WEBHOOK_SECRET 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
INTERCOM_DEV_TOKEN (and optional INTERCOM_WEBHOOK_SECRET) 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
| CI Issue | Cause | Solution |
|---|
INTERCOM_DEV_TOKEN not found | Secret not configured | gh secret set INTERCOM_DEV_TOKEN |
| Integration tests timeout | Rate limited or slow API | Increase timeout, add delays |
| 401 in CI | Token expired or rotated | Update secret with new token |
| Flaky tests | Shared dev workspace state | Use unique names, clean up after |
Examples
Add Intercom CI to an existing repo. Run gh secret set INTERCOM_DEV_TOKEN,
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 INTERCOM_WEBHOOK_SECRET, 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
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.
