Working with GitHub Integration

1. Connecting GitHub Repository

Step	Action	Description
1	`Access CircleCI Dashboard`	Navigate to your CircleCI dashboard and sign in with your GitHub account.
2	`Go to Project Settings`	Select the project you want to configure and go to its settings page.
3	`Enable GitHub Integration`	Ensure that the GitHub integration is enabled in your CircleCI project settings.
4	`Configure Webhooks`	Set up webhooks in your GitHub repository to trigger builds on push or pull request events.

Example: GitHub Webhook Configuration

curl -X POST https://api.github.com/repos/ORG/REPO/hooks \
  -H "Authorization: token GITHUB_TOKEN" \
  -d '{"name":"web","active":true,"events":["push","pull_request"],"config":{"url":"https://circleci.com/api/v1.1/project/github/ORG/REPO/webhook","content_type":"json"}}'

Note: Ensure that the webhook URL is correctly configured to point to your CircleCI project endpoint.

2. Configuring Status Checks

Setting	Description	Default	Notes
github.status_checks	Enables or disables GitHub status checks for CircleCI builds	`false`	Required for integration with GitHub branch protection rules
github.status_checks.context	Custom context for the status check	`ci/circleci`	Used to differentiate multiple CI systems

Example: Enabling GitHub Status Checks

version: 2.1
jobs:
  build:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run: npm install
      - run: npm test

workflows:
  version: 2
  build-and-test:
    jobs:
      - build

# Enable GitHub status checks in config.yml
github:
  status_checks: true
  status_checks_context: ci/circleci

Note: Status checks must be enabled in the CircleCI project settings for this configuration to take effect.

3. Using GitHub Checks API

Property	Description	Values	Notes
check_name	Name of the check run	`CircleCI Build`	Displayed in GitHub UI
status	Current status of the check	`queued`, `in_progress`, `completed`	Must be updated as build progresses
conclusion	Final result of the check	`success`, `failure`, `neutral`, `cancelled`	Required when status is `completed`
output.title	Title of the check output	`Build Passed`	Can be customized in config
output.summary	Summary of the check run	`CircleCI build completed successfully`	Markdown supported

Example: Posting GitHub Check Run

const { Octokit } = require("@octokit/rest");

const octokit = new Octokit({ auth: process.env.GITHUB_TOKEN });

await octokit.rest.checks.create({
  owner: "circleci",
  repo: "example-repo",
  name: "CircleCI Build",
  head_sha: "abc123def456",
  status: "in_progress",
  output: {
    title: "Build in Progress",
    summary: "CircleCI is running the build."
  }
});

Example: Updating GitHub Check Run

await octokit.rest.checks.update({
  owner: "circleci",
  repo: "example-repo",
  check_run_id: 123456789,
  status: "completed",
  conclusion: "success",
  output: {
    title: "Build Passed",
    summary: "All tests passed in CircleCI."
  }
});

Note: GitHub Checks API requires a personal access token with checks:write scope.

Warning: Check run IDs are not persistent across builds. Always fetch the latest check run ID for a given commit SHA.

4. Setting Up Branch Protection

Branch	Protection Rules	Notes
main	`required`	Protects the main branch from direct pushes
develop	`required`	Protects the develop branch from direct pushes

Example: GitHub Branch Protection Configuration

branch_protection:
  main:
    required_status_checks:
      contexts:
        - circleci
    required_pull_request_reviews:
      required_approving_review_count: 1

Note: Ensure that CircleCI is configured to run on protected branches.

5. Configuring Webhooks

Field	Description	Value
webhook.url	URL to send webhook events	`https://circleci.com/webhook`
webhook.events	Event types to trigger webhook	`push, pull_request, tag`
webhook.secret	Secret for webhook signature verification	`circleci-webhook-secret`

Example: Webhook Configuration

version: 2.1
jobs:
  build:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run: echo "Building..."
      - webhook:
          url: https://circleci.com/webhook
          events: [push, pull_request]
          secret: circleci-webhook-secret

Note: Webhooks must be enabled in your GitHub repository settings to receive events from CircleCI.

6. Using PR-Only Workflows

PR-only workflows in CircleCI allow you to run jobs exclusively when a pull request is created or updated, helping to avoid unnecessary resource consumption and ensure that only relevant changes are tested.

Property	Description	Default Value
when	Condition to determine whether the job runs. Set to `pull_request` to run only on PRs.	`always`
branches	Branches to include or exclude from the workflow. Use `only` to restrict to PRs.	All branches

Example: Configuring a PR-Only Workflow

version: 2.1
jobs:
  test-pr:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run: npm test

workflows:
  version: 2
  pr-only-workflow:
    jobs:
      - test-pr:
          when: pull_request

Note: The when: pull_request condition ensures that the job runs only when a new pull request is created or updated, not on regular branch pushes.

7. Triggering on PR Events

Event	Description	Configuration	Notes
pull_request	Triggers on pull request creation, update, or merge	`pull_request:`	Supports `opened`, `synchronized`, `merged`
pull_request.opened	Triggers when a PR is opened	`pull_request:` `opened: true`	Useful for initial CI checks
pull_request.synchronized	Triggers when a PR branch is updated (e.g., new commits)	`pull_request:` `synchronized: true`	Ensures CI runs on latest changes
pull_request.merged	Triggers when a PR is merged into the target branch	`pull_request:` `merged: true`	Can be used for deployment or cleanup tasks

Example: Configuring PR Triggers

version: 2.1
jobs:
  build:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run: npm test

workflows:
  version: 2
  pr-workflow:
    jobs:
      - build:
          filters:
            pull_request:
              branches:
                only: [main]

Note: By default, CircleCI runs on all PRs. Use filters to limit which branches or events trigger workflows.

8. Commenting on PRs

Field	Description	Values
comment	Comment to post on the PR	`<string>`
on_success	Post comment on successful build	`true` \| `false`
on_fail	Post comment on failed build	`true` \| `false`

Example: Comment on PR

version: 2.1
jobs:
  build:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run:
          name: Post PR Comment
          command: |
            curl -X POST "https://api.github.com/repos/<owner>/<repo>/issues/<pr_number>/comments" \
              -H "Authorization: token $GITHUB_TOKEN" \
              -d '{"body": "Build successful on CircleCI!"}'

Note: Requires GITHUB_TOKEN with appropriate permissions to post comments on GitHub issues.

9. Syncing Organization Settings

Setting	Description	Sync Status	Notes
github_app_installation	Installation status of the GitHub App	NEW	Required for organization-level sync
webhook_url	URL for GitHub webhook events	DEPRECATED	Replaced by GitHub App integration
sync_branches	Branches to sync with CircleCI	NEW	Supports regex patterns

Example: Configure Branch Sync

version: 2.1
orbs:
  github-app: circleci/github-app@1.0
jobs:
  sync-branches:
    docker:
      - image: circleci/python:3.9
    steps:
      - github-app/sync-branches:
          branches: "main|develop"

Note: Organization settings sync requires admin permissions on the GitHub organization.

10. Debugging Integration Issues

Issue	Possible Cause	Solution
Repository not showing up in CircleCI	Missing permissions or incorrect repository visibility	Ensure the GitHub user has admin access to the repo and that it's set to public or private in CircleCI settings
Builds not triggering on push	Webhook not configured or GitHub app permissions missing	Reinstall the CircleCI GitHub App and verify webhook is active in GitHub repo settings
Builds failing with permission errors	Missing or incorrect GitHub token in CircleCI project settings	Regenerate the GitHub token in CircleCI and update it in project settings
Builds stuck in queue or never start	Insufficient resources or build limit reached	Check CircleCI dashboard for resource limits and cancel pending builds if needed

Example: Checking Webhook Status in GitHub

curl -H "Authorization: token <GITHUB_TOKEN>" \
  https://api.github.com/repos/<ORG>/<REPO>/hooks

Note: Ensure that the GitHub webhook URL matches the one configured in CircleCI.

Warning: If the repository is private, make sure CircleCI has proper access to read and write to it.