Using GitLab CI/CD with a GitHub repository

DETAILS: Tier: Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

GitLab CI/CD can be used with GitHub.com and GitHub Enterprise by creating a CI/CD project to connect your GitHub repository to GitLab.

Watch a video on Using GitLab CI/CD pipelines with GitHub repositories.

NOTE: Because of GitHub limitations, GitHub OAuth cannot be used to authenticate with GitHub as an external CI/CD repository.

Connect with personal access token

Personal access tokens can only be used to connect GitHub.com repositories to GitLab, and the GitHub user must have the owner role.

To perform a one-off authorization with GitHub to grant GitLab access your repositories:

1. In GitHub, create a token:
   1. Open https://github.com/settings/tokens/new.
   2. Create a personal access token.
   3. Enter a Token description and update the scope to allow repo and admin:repo_hook so that GitLab can access your project, update commit statuses, and create a web hook to notify GitLab of new commits.
2. In GitLab, create a project:
   1. On the left sidebar, at the top, select Create new ({plus}) and New project/repository.
   2. Select Run CI/CD for external repository.
   3. Select GitHub.
   4. For Personal access token, paste the token.
   5. Select List Repositories.
   6. Select Connect to select the repository.
3. In GitHub, add a .gitlab-ci.yml to configure GitLab CI/CD.

GitLab:

1. Imports the project.
2. Enables Pull Mirroring.
3. Enables GitHub project integration.
4. Creates a web hook on GitHub to notify GitLab of new commits.

Connect manually

To use GitHub Enterprise with GitLab.com, use this method.

To manually enable GitLab CI/CD for your repository:

1. In GitHub, create a token:

   1. Open https://github.com/settings/tokens/new.
   2. Create a personal access token.
   3. Enter a Token description and update the scope to allow repo so that GitLab can access your project and update commit statuses.

2. In GitLab, create a project:

   1. On the left sidebar, at the top, select Create new ({plus}) and New project/repository.
   2. Select Run CI/CD for external repository and Repository by URL.
   3. In the Git repository URL field, enter the HTTPS URL for your GitHub repository. If your project is private, use the personal access token you just created for authentication.
   4. Fill in all the other fields and select Create project. GitLab automatically configures polling-based pull mirroring.

3. In GitLab, enable GitHub project integration:

   1. On the left sidebar, select Settings > Integrations.
   2. Select the Active checkbox.
   3. Paste your personal access token and HTTPS repository URL into the form and select Save.

4. In GitLab, create a personal access token with API scope to authenticate the GitHub web hook notifying GitLab of new commits.

5. In GitHub, from Settings > Webhooks, create a web hook to notify GitLab of new commits.

   The web hook URL should be set to the GitLab API to trigger pull mirroring, using the GitLab personal access token we just created:

   https://gitlab.com/api/v4/projects/<NAMESPACE>%2F<PROJECT>/mirror/pull?private_token=<PERSONAL_ACCESS_TOKEN>

   Select the Let me select individual events option, then check the Pull requests and Pushes checkboxes. These settings are needed for pipelines for external pull requests.

6. In GitHub, add a .gitlab-ci.yml to configure GitLab CI/CD.