Working with Bitbucket and GitLab Integration

1. Connecting Bitbucket Repository

Step	Description	Action
1	Log into CircleCI	Navigate to `circleci.com` and sign in with your Bitbucket account.
2	Authorize CircleCI app in Bitbucket	Grant permissions to CircleCI for accessing repositories.
3	Select Repository	Choose the Bitbucket repository to configure in CircleCI.
4	Enable Project	Toggle the project to enable builds in CircleCI.

Example: Enabling a Bitbucket Project in CircleCI

curl -X POST https://circleci.com/api/v2/project/bitbucket/ORG/REPO/branch/main

Note: Ensure the repository is public or that you have appropriate permissions to access it.

2. Connecting GitLab Repository

Step	Description	Action
1	Log into your CircleCI account	Visit `circleci.com` and sign in
2	Navigate to Project Settings	Go to the project's settings page in CircleCI dashboard
3	Enable GitLab Integration	Select GitLab as the VCS provider in project settings
4	Authorize CircleCI Access	Grant CircleCI permissions to access your GitLab repositories
5	Configure Webhooks	Set up webhooks in GitLab to trigger CircleCI builds on push events

Example: GitLab Webhook Configuration

curl -X POST "https://gitlab.example.com/api/v4/projects/12345/hooks" \
  -H "PRIVATE-TOKEN: your-gitlab-token" \
  -d "url=https://circleci.com/api/v2/project/gh/your-org/your-repo/webhook" \
  -d "push_events=true"

Note: Ensure that the GitLab project is properly linked to your CircleCI project and that the webhook URL matches your project's configuration.

3. Configuring Webhooks (automatic triggers)

Webhook Type	Trigger Event	Configuration	Notes
Push	Code pushed to a branch	`push`	Triggers build on every commit to a branch
Pull Request	PR created or updated	`pull_request`	Triggers build on PR changes
Tag	Tag created or pushed	`tag`	Triggers build on tag creation
Manual	Manual trigger via API or UI	`manual`	Builds can be triggered manually

Example: Webhook Configuration in CircleCI

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

workflows:
  version: 2
  build-and-test:
    jobs:
      - build
    triggers:
      - push:
          branches:
            only:
              - main
      - pull_request:
          branches:
            only:
              - main

Note: Webhooks must be configured in your Git provider (Bitbucket or GitLab) to point to CircleCI's webhook endpoint.

4. Setting Up Status Checks

Field	Description	Example
status	Defines the status check to be added to the commit	`success`, `failure`
context	Unique identifier for the status check	`ci/circleci: build`
description	Short description of the status check	`Build and tests passed`
target_url	URL to the build or test results page	`https://circleci.com/gh/ORG/REPO/123`

Example: Configuring Status Checks in CircleCI

version: 2.1
jobs:
  build:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run:
          name: Run Tests
          command: npm test
      - run:
          name: Update Status Check
          command: |
            curl -X POST "https://api.github.com/repos/ORG/REPO/statuses/$CIRCLE_SHA1" \
              -H "Authorization: token $GITHUB_TOKEN" \
              -d '{
                "state": "success",
                "target_url": "https://circleci.com/gh/ORG/REPO/123",
                "description": "Build and tests passed",
                "context": "ci/circleci: build"
              }'

Note: The GITHUB_TOKEN must have the appropriate permissions to update commit statuses on the repository.

5. Using Branch Restrictions

Restriction Type	Description	Configuration	Notes
Branch Pattern	Allows or blocks specific branch names using glob patterns	`branches:`	Supports wildcards like `*` and `?`
Branch Protection	Prevents changes to protected branches (e.g., `main`, `master`)	`branches:`	Can be configured to require approval or status checks
Regex Matching	Enables regex patterns for branch name matching	`branches:`	Useful for complex naming conventions

Example: Restricting Branch Access

version: 2.1
jobs:
  build:
    docker:
      - image: circleci/python:3.9
    steps:
      - checkout
      - run:
          name: Run Tests
          command: python -m pytest

workflows:
  version: 2
  build-and-test:
    jobs:
      - build:
          filters:
            branches:
              ignore: /^release\/.*$/

Note: Branch restrictions can be applied at the project level in CircleCI settings or via configuration files.

6. Triggering on PR Events

Event Type	Description	Configuration	Notes
pull_request	Triggers on creation, update, or merge of a pull request	`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 with 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:
              opened: true
              synchronized: true

Note: By default, CircleCI does not run workflows on PRs unless explicitly configured to do so.

7. Commenting on Merge Requests

Field	Description	Values
comment	Comment to post on the merge request	`string`
level	Severity level of the comment	`info`, `warning`, `error`
target	Target merge request or branch	`merge_request`, `branch`

Example: Post a comment on a merge request

version: 2.1
jobs:
  post-comment:
    docker:
      - image: circleci/python:3.9
    steps:
      - checkout
      - run:
          name: Post comment to Bitbucket
          command: |
            curl -X POST "https://api.bitbucket.org/2.0/repositories/<workspace>/<repo>/pullrequests/<pr-id>/comments" \
              -H "Authorization: Bearer $BITBUCKET_TOKEN" \
              -d '{"content": {"raw": "Build successful!"}}'

Note: Ensure that the BITBUCKET_TOKEN environment variable is set with appropriate permissions to post comments on merge requests.

Warning: Comments are not supported in GitLab integration directly; use gitlab API endpoints or external tools.

8. Using Repository Variables

Variable	Type	Description	Usage
CIRCLE_PROJECT_REPONAME	Environment	Name of the repository	`<project-name>`
CIRCLE_PROJECT_USERNAME	Environment	Username of the repository owner	`<username>`
CIRCLE_REPOSITORY_URL	Environment	URL of the repository	`<repo-url>`
CIRCLE_SHA1	Environment	Git commit SHA	`<commit-sha>`
CIRCLE_BRANCH	Environment	Branch name	`<branch-name>`
CIRCLE_TAG	Environment	Tag name if build is from a tag	`<tag-name>`

Example: Using Repository Variables in a Build Script

#!/bin/bash
echo "Building repository: $CIRCLE_PROJECT_REPONAME"
echo "Commit SHA: $CIRCLE_SHA1"
echo "Branch: $CIRCLE_BRANCH"

Note: Repository variables are automatically set by CircleCI and can be used in configuration files or build scripts without any additional setup.

9. Managing Multiple VCS Providers

Example: Configuring Bitbucket and GitLab in the Same Project

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

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

Provider	Configuration Method	Notes
Bitbucket	`circleci config process`	Use Bitbucket Pipelines integration for builds
GitLab	`circleci config process`	Use GitLab CI integration for builds

Managing Multiple VCS Providers

CircleCI supports both Bitbucket and GitLab integration
Each provider requires specific configuration in the config.yml
Use environment variables to manage provider-specific settings

10. Debugging Integration Issues

Common Debugging Steps

Check Webhook Configuration: Ensure the webhook URL is correctly set in Bitbucket or GitLab settings.
Verify Repository Permissions: Confirm that the CircleCI project has read/write access to the repository.
Review Build Logs: Examine logs for error messages related to integration failures or missing data.
Validate Token Permissions: Make sure the API token used has sufficient permissions for repository access.
Test Manual Trigger: Try triggering a build manually to isolate whether the issue is with the integration or the pipeline itself.

Issue Type	Potential Cause	Solution
Webhook Not Received	`404` or `500` errors from Bitbucket/GitLab	Reconfigure webhook URL in repository settings; check for network restrictions
Build Not Triggered	Incorrect branch filter or trigger condition	Review `filter` settings in `circleci/config.yml`
Permission Denied	Missing or incorrect API token	Regenerate and re-add the token in CircleCI project settings

Example: Checking Build Logs for Errors

curl -H "Circle-Token: <your-token>" \
  https://circleci.com/api/v2/project/bitbucket/<org>/<repo>/pipeline

Note: Use the CircleCI API to inspect pipeline status and logs for detailed error information.