| title | description | ms.topic | ms.assetid | ms.author | author | ms.date | monikerRange |
|---|---|---|---|---|---|---|---|
Build GitHub repositories |
Using a GitHub repository with Azure Pipelines |
reference |
96a52d0d-5e01-4b30-818d-1893387522cd |
vijayma |
vijayma |
09/08/2023 |
azure-devops |
[!INCLUDE version-eq-azure-devops]
Azure Pipelines can automatically build and validate every pull request and commit to your GitHub repository. This article describes how to configure the integration between GitHub and Azure Pipelines.
If you're new to pipelines integration with GitHub, follow the steps in Create your first pipeline. Come back to this article to learn more about configuring and customizing the integration between GitHub and Azure Pipelines.
GitHub and Azure Pipelines are two independent services that integrate well together. Each of them have their own organization and user management. This section makes a recommendation on how to replicate the organization and users from GitHub to Azure Pipelines.
GitHub's structure consists of organizations and user accounts that contain repositories. See GitHub's documentation.
Azure DevOps' structure consists of organizations that contain projects. See Plan your organizational structure.
Azure DevOps can reflect your GitHub structure with:
- A DevOps organization for your GitHub organization or user account
- DevOps Projects for your GitHub repositories
To set up an identical structure in Azure DevOps:
- Create a DevOps organization named after your GitHub organization or user account. It will have a URL like
https://dev.azure.com/your-organization. - In the DevOps organization, create projects named after your repositories. They’ll have URLs like
https://dev.azure.com/your-organization/your-repository. - In the DevOps Project, create pipelines named after the GitHub organization and repository they build, such as
your-organization.your-repository. Then, it's clear which repositories they're for.
Following this pattern, your GitHub repositories and Azure DevOps Projects will have matching URL paths. For example:
| Service | URL |
|---|---|
| GitHub | https://github.com/python/cpython |
| Azure DevOps | https://dev.azure.com/python/cpython |
Your GitHub users don’t automatically get access to Azure Pipelines. Azure Pipelines is unaware of GitHub identities. For this reason, there’s no way to configure Azure Pipelines to automatically notify users of a build failure or a PR validation failure using their GitHub identity and email address. You must explicitly create new users in Azure Pipelines to replicate GitHub users. Once you create new users, you can configure their permissions in Azure DevOps to reflect their permissions in GitHub. You can also configure notifications in DevOps using their DevOps identity.
GitHub organization member roles are found at https://github.com/orgs/your-organization/people (replace your-organization).
DevOps organization member permissions are found at https://dev.azure.com/your-organization/_settings/security (replace your-organization).
Roles in a GitHub organization and equivalent roles in an Azure DevOps organization are shown below.
| GitHub organization role | DevOps organization equivalent |
|---|---|
| Owner | Member of Project Collection Administrators |
| Billing manager | Member of Project Collection Administrators |
| Member | Member of Project Collection Valid Users. By default, the Member group lacks permission to create new projects. To change the permission, set the group's Create new projects permission to Allow, or create a new group with permissions you need. |
A GitHub user account has one role, which is ownership of the account.
DevOps organization member permissions are found at https://dev.azure.com/your-organization/_settings/security (replace your-organization).
The GitHub user account role maps to DevOps organization permissions as follows.
| GitHub user account role | DevOps organization equivalent |
|---|---|
| Owner | Member of Project Collection Administrators |
GitHub repository permissions are found at https://github.com/your-organization/your-repository/settings/collaboration (replace your-organization and your-repository).
DevOps project permissions are found at https://dev.azure.com/your-organization/your-project/_settings/security (replace your-organization and your-project).
Equivalent permissions between GitHub repositories and Azure DevOps Projects are as follows.
| GitHub repository permission | DevOps project equivalent |
|---|---|
| Admin | Member of Project Administrators |
| Write | Member of Contributors |
| Read | Member of Readers |
If your GitHub repository grants permission to teams, you can create matching teams in the Teams section of your Azure DevOps project settings. Then, add the teams to the security groups above, just like users.
To grant permissions to users or teams for specific pipelines in a DevOps project, follow these steps:
- Visit the project's Pipelines page (for example,
https://dev.azure.com/your-organization/your-project/_build). - Select the pipeline for which to set specific permissions.
- From the '...' context menu, select Security.
- Select Add... to add a specific user, team, or group and customize their permissions for the pipeline.
You create a new pipeline by first selecting a GitHub repository and then a YAML file in that repository. The repository in which the YAML file is present is called self repository. By default, this is the repository that your pipeline builds.
You can later configure your pipeline to check out a different repository or multiple repositories. To learn how to do this, see multi-repo checkout.
You create a new pipeline by first selecting GitHub for repository type, and then one of the repositories you have access to.
Azure Pipelines must be granted access to your repositories to trigger their builds, and fetch their code during builds.
There are three authentication types for granting Azure Pipelines access to your GitHub repositories while creating a pipeline.
| Authentication type | Pipelines run using | Works with GitHub Checks |
|---|---|---|
| 1. GitHub App | The Azure Pipelines identity | Yes |
| 2. OAuth | Your personal GitHub identity | No |
| 3. Personal access token (PAT) | Your personal GitHub identity | No |
The Azure Pipelines GitHub App is the recommended authentication type for continuous integration pipelines. After you install the GitHub App in your GitHub account or organization, your pipeline will run without using your personal GitHub identity. Builds and GitHub status updates will be performed using the Azure Pipelines identity. The app works with GitHub Checks to display build, test, and code coverage results in GitHub.
To use the GitHub App, install it in your GitHub organization or user account for some or all repositories. The GitHub App can be installed and uninstalled from the app's homepage.
After installation, the GitHub App will become Azure Pipelines' default method of authentication to GitHub (instead of OAuth) when pipelines are created for the repositories.
If you install the GitHub App for all repositories in a GitHub organization, you don't need to worry about Azure Pipelines sending mass emails or automatically setting up pipelines on your behalf. As an alternative to installing the app for all repositories, repository admins can install it one at a time for individual repositories. This requires more work for admins, but has no advantage nor disadvantage.
Installation of Azure Pipelines GitHub app requires you to be a GitHub organization owner or repository admin. In addition, to create a pipeline for a GitHub repository with continuous integration and pull request triggers, you must have the required GitHub permissions configured. Otherwise, the repository will not appear in the repository list while creating a pipeline. Depending on the authentication type and ownership of the repository, ensure that the appropriate access is configured.
-
If the repo is in your personal GitHub account, install the Azure Pipelines GitHub App in your personal GitHub account, and you’ll be able to list this repository when creating the pipeline in Azure Pipelines.
-
If the repo is in someone else's personal GitHub account, the other person must install the Azure Pipelines GitHub App in their personal GitHub account. You must be added as a collaborator in the repository's settings under "Collaborators". Accept the invitation to be a collaborator using the link that is emailed to you. Once you’ve done so, you can create a pipeline for that repository.
-
If the repo is in a GitHub organization that you own, install the Azure Pipelines GitHub App in the GitHub organization. You must also be added as a collaborator, or your team must be added, in the repository's settings under "Collaborators and teams".
-
If the repo is in a GitHub organization that someone else owns, a GitHub organization owner or repository admin must install the Azure Pipelines GitHub App in the organization. You must be added as a collaborator, or your team must be added, in the repository's settings under "Collaborators and teams". Accept the invitation to be a collaborator using the link that is emailed to you.
The GitHub App requests the following permissions during installation:
| Permission | How Azure Pipelines uses the permission |
|---|---|
| Write access to code | Only upon your deliberate action, Azure Pipelines will simplify creating a pipeline by committing a YAML file to a selected branch of your GitHub repository. |
| Read access to metadata | Azure Pipelines will retrieve GitHub metadata for displaying the repository, branches, and issues associated with a build in the build's summary. |
| Read and write access to checks | Azure Pipelines will read and write its own build, test, and code coverage results to be displayed in GitHub. |
| Read and write access to pull requests | Only upon your deliberate action, Azure Pipelines will simplify creating a pipeline by creating a pull request for a YAML file that was committed to a selected branch of your GitHub repository. Pipelines retrieves request metadata to display in build summaries associated with pull requests. |
GitHub may display an error such as:
You do not have permission to modify this app on your-organization. Please contact an Organization Owner.
This means that the GitHub App is likely already installed for your organization. When you create a pipeline for a repository in the organization, the GitHub App will automatically be used to connect to GitHub.
Once the GitHub App is installed, pipelines can be created for the organization's repositories in different Azure DevOps organizations and projects. However, if you create pipelines for a single repository in multiple Azure DevOps organizations, only the first organization's pipelines can be automatically triggered by GitHub commits or pull requests. Manual or scheduled builds are still possible in secondary Azure DevOps organizations.
OAuth is the simplest authentication type to get started with for repositories in your personal GitHub account. GitHub status updates will be performed on behalf of your personal GitHub identity. For pipelines to keep working, your repository access must remain active. Some GitHub features, like Checks, are unavailable with OAuth and require the GitHub App.
To use OAuth, select Choose a different connection below the list of repositories while creating a pipeline. Then, select Authorize to sign into GitHub and authorize with OAuth. An OAuth connection will be saved in your Azure DevOps project for later use, and used in the pipeline being created.
To create a pipeline for a GitHub repository with continuous integration and pull request triggers, you must have the required GitHub permissions configured. Otherwise, the repository will not appear in the repository list while creating a pipeline. Depending on the authentication type and ownership of the repository, ensure that the appropriate access is configured.
-
If the repo is in your personal GitHub account, at least once, authenticate to GitHub with OAuth using your personal GitHub account credentials. This can be done in Azure DevOps project settings under Pipelines > Service connections > New service connection > GitHub > Authorize. Grant Azure Pipelines access to your repositories under "Permissions" here.
-
If the repo is in someone else's personal GitHub account, at least once, the other person must authenticate to GitHub with OAuth using their personal GitHub account credentials. This can be done in Azure DevOps project settings under Pipelines > Service connections > New service connection > GitHub > Authorize. The other person must grant Azure Pipelines access to their repositories under "Permissions" here. You must be added as a collaborator in the repository's settings under "Collaborators". Accept the invitation to be a collaborator using the link that is emailed to you.
-
If the repo is in a GitHub organization that you own, at least once, authenticate to GitHub with OAuth using your personal GitHub account credentials. This can be done in Azure DevOps project settings under Pipelines > Service connections > New service connection > GitHub > Authorize. Grant Azure Pipelines access to your organization under "Organization access" here. You must be added as a collaborator, or your team must be added, in the repository's settings under "Collaborators and teams".
-
If the repo is in a GitHub organization that someone else owns, at least once, a GitHub organization owner must authenticate to GitHub with OAuth using their personal GitHub account credentials. This can be done in Azure DevOps project settings under Pipelines > Service connections > New service connection > GitHub > Authorize. The organization owner must grant Azure Pipelines access to the organization under "Organization access" here. You must be added as a collaborator, or your team must be added, in the repository's settings under "Collaborators and teams". Accept the invitation to be a collaborator using the link that is emailed to you.
After authorizing Azure Pipelines to use OAuth, to later revoke it and prevent further use, visit OAuth Apps in your GitHub settings. You can also delete it from the list of GitHub service connections in your Azure DevOps project settings.
PATs are effectively the same as OAuth, but allow you to control which permissions are granted to Azure Pipelines. Builds and GitHub status updates will be performed on behalf of your personal GitHub identity. For builds to keep working, your repository access must remain active.
To create a PAT, visit Personal access tokens in your GitHub settings.
The required permissions are repo, admin:repo_hook, read:user, and user:email. These are the same permissions required when using OAuth above. Copy the generated PAT to the clipboard and paste it into a new GitHub service connection in your Azure DevOps project settings.
For future recall, name the service connection after your GitHub username. It will be available in your Azure DevOps project for later use when creating pipelines.
To create a pipeline for a GitHub repository with continuous integration and pull request triggers, you must have the required GitHub permissions configured. Otherwise, the repository will not appear in the repository list while creating a pipeline. Depending on the authentication type and ownership of the repository, ensure that the following access is configured.
-
If the repo is in your personal GitHub account, the PAT must have the required access scopes under Personal access tokens:
repo,admin:repo_hook,read:user, anduser:email. -
If the repo is in someone else's personal GitHub account, the PAT must have the required access scopes under Personal access tokens:
repo,admin:repo_hook,read:user, anduser:email. You must be added as a collaborator in the repository's settings under "Collaborators". Accept the invitation to be a collaborator using the link that is emailed to you. -
If the repo is in a GitHub organization that you own, the PAT must have the required access scopes under Personal access tokens:
repo,admin:repo_hook,read:user, anduser:email. You must be added as a collaborator, or your team must be added, in the repository's settings under "Collaborators and teams". -
If the repo is in a GitHub organization that someone else owns, the PAT must have the required access scopes under Personal access tokens:
repo,admin:repo_hook,read:user, anduser:email. You must be added as a collaborator, or your team must be added, in the repository's settings under "Collaborators and teams". Accept the invitation to be a collaborator using the link that is emailed to you.
After authorizing Azure Pipelines to use a PAT, to later delete it and prevent further use, visit Personal access tokens in your GitHub settings. You can also delete it from the list of GitHub service connections in your Azure DevOps project settings.
Continuous integration (CI) triggers cause a pipeline to run whenever you push an update to the specified branches or you push specified tags.
[!INCLUDE ci-triggers]
[!INCLUDE ci-triggers]
[!INCLUDE ci-triggers]
[!INCLUDE ci-triggers]
You can also tell Azure Pipelines to skip running a pipeline that a push would normally trigger. Just include [skip ci] in the message or description of any of the commits that are part of a push, and Azure Pipelines will skip running CI for this push. You can also use any of the following variations.
[skip ci]or[ci skip]skip-checks: trueorskip-checks:true[skip azurepipelines]or[azurepipelines skip][skip azpipelines]or[azpipelines skip][skip azp]or[azp skip]***NO_CI***
[!INCLUDE ci-triggers]
Pull request (PR) triggers cause a pipeline to run whenever a pull request is opened with one of the specified target branches, or when updates are made to such a pull request.
You can specify the target branches when validating your pull requests.
For example, to validate pull requests that
target main and releases/*, you can use the following pr trigger.
pr:
- main
- releases/*This configuration starts a new run the first time a new pull request is created, and after every update made to the pull request.
You can specify the full name of the branch (for example, main) or a wildcard (for example, releases/*).
Note
You cannot use variables in triggers, as variables are evaluated at runtime (after the trigger has fired).
Note
If you use templates to author YAML files, then you can only specify triggers in the main YAML file for the pipeline. You cannot specify triggers in the template files.
GitHub creates a new ref when a pull request is created. The ref points to a merge commit, which is the merged code between the source and target branches of the pull request. The PR validation pipeline builds the commit that this ref points to. This means that the YAML file that is used to run the pipeline is also a merge between the source and the target branch. As a result, the changes you make to the YAML file in source branch of the pull request can override the behavior defined by the YAML file in target branch.
If no pr triggers appear in your YAML file, pull request validations are automatically enabled for all
branches, as if you wrote the following pr trigger. This configuration triggers a build when any
pull request is created, and when commits come into the source branch of any active pull request.
pr:
branches:
include:
- '*' # must quote since "*" is a YAML reserved character; we want a stringImportant
When you specify a pr trigger with a subset of branches, a pipeline is triggered only when updates are pushed to those branches.
For more complex triggers that need to exclude certain branches, you must use the full syntax as shown in the following example. In this example, pull requests are validated that target main or releases/* and the branch releases/old* is excluded.
# specific branch
pr:
branches:
include:
- main
- releases/*
exclude:
- releases/old*You can specify file paths to include or exclude. For example:
# specific path
pr:
branches:
include:
- main
- releases/*
paths:
include:
- docs
exclude:
- docs/README.mdTips:
- Azure Pipelines posts a neutral status back to GitHub when it decides not to run a validation build because of a path exclusion rule. This provides a clear direction to GitHub indicating that Azure Pipelines has completed its processing. For more information, see Post neutral status to GitHub when a build is skipped.
- Wild cards are now supported with path filters.
- Paths are always specified relative to the root of the repository.
- If you don't set path filters, then the root folder of the repo is implicitly included by default.
- If you exclude a path, you cannot also include it unless you qualify it to a deeper folder. For example if you exclude /tools then you could include /tools/trigger-runs-on-these
- The order of path filters doesn't matter.
- Paths in Git are case-sensitive. Be sure to use the same case as the real folders.
- You cannot use variables in paths, as variables are evaluated at runtime (after the trigger has fired).
- Azure Pipelines posts a neutral status back to GitHub when it decides not to run a validation build because of a path exclusion rule.
You can specify whether more updates to a PR should cancel in-progress validation runs for the same PR. The default is true.
# auto cancel false
pr:
autoCancel: false
branches:
include:
- mainBy default, pull request triggers fire on draft pull requests and pull requests that are ready for review. To disable pull request triggers for draft pull requests, set the drafts property to false.
pr:
autoCancel: boolean # indicates whether additional pushes to a PR should cancel in-progress runs for the same PR. Defaults to true
branches:
include: [ string ] # branch names which will trigger a build
exclude: [ string ] # branch names which will not
paths:
include: [ string ] # file paths which must match to trigger a build
exclude: [ string ] # file paths which will not trigger a build
drafts: boolean # whether to build draft PRs, defaults to trueYou can opt out of pull request validation entirely by specifying pr: none.
# no PR triggers
pr: noneFor more information, see PR trigger in the YAML schema.
Note
If your pr trigger isn't firing, follow the troubleshooting steps in the FAQ.
Note
Draft pull requests do not trigger a pipeline.
Select the Pull request validation trigger and check the Enable pull request validation check box to enable builds on pull requests.
You can specify branches to include and exclude. Select a branch name from the drop-down menu and select Include or Exclude as appropriate. For included branches, a build will be triggered on each push to a pull request targeting that branch.
If you have an open PR and you push changes to its source branch, multiple pipelines may run:
- The pipelines that have a PR trigger on the PR's target branch will run on the merge commit (the merged code between the source and target branches of the pull request), regardless if there exist pushed commits whose messages or descriptions contain
[skip ci](or any of its variants). - The pipelines triggered by changes to the PR's source branch, if there are no pushed commits whose messages or descriptions contain
[skip ci](or any of its variants). If at least one pushed commit contains[skip ci], the pipelines will not run.
Finally, after you merge the PR, Azure Pipelines will run the CI pipelines triggered by pushes to the target branch, if the merge commit's message or description doesn't contain [skip ci] (or any of its variants).
You can run a validation build with each commit or pull request that targets a branch, and even prevent pull requests from merging until a validation build succeeds.
To configure mandatory validation builds for a GitHub repository, you must be its owner, a collaborator with the Admin role, or a GitHub organization member with the Write role.
-
First, create a pipeline for the repository and build it at least once so that its status is posted to GitHub, thereby making GitHub aware of the pipeline's name.
-
Next, follow GitHub's documentation for configuring protected branches in the repository's settings.
For the status check, select the name of your pipeline in the Status checks list.
Important
If your pipeline doesn't show up in this list, please ensure the following:
- You are using GitHub app authentication
- Your pipeline has run at least once in the last week
If your GitHub repository is open source, you can make your Azure DevOps project public so that anyone can view your pipeline's build results, logs, and test results without signing in. When users outside your organization fork your repository and submit pull requests, they can view the status of builds that automatically validate those pull requests.
You should keep in mind the following considerations when using Azure Pipelines in a public project when accepting contributions from external sources.
Be aware of the following access restrictions when you're running pipelines in Azure DevOps public projects:
- Secrets: By default, secrets associated with your pipeline aren’t made available to pull request validations of forks. See Validate contributions from forks.
- Cross-project access: All pipelines in an Azure DevOps public project run with an access token restricted to the project. Pipelines in a public project can access resources such as build artifacts or test results only within the project and not in other projects of the Azure DevOps organization.
- Azure Artifacts packages: If your pipelines need access to packages from Azure Artifacts, you must explicitly grant permission to the Project Build Service account to access the package feeds.
Important
These settings affect the security of your pipeline.
When you create a pipeline, it’s automatically triggered for pull requests from forks of your repository. You can change this behavior, carefully considering how it affects security. To enable or disable this behavior:
- Go to your Azure DevOps project. Select Pipelines, locate your pipeline, and select Edit.
- Select the Triggers tab. After enabling the Pull request trigger, enable or disable the Build pull requests from forks of this repository check box.
By default with GitHub pipelines, secrets associated with your build pipeline aren’t made available to pull request builds of forks. These secrets are enabled by default with GitHub Enterprise Server pipelines. Secrets include:
- A security token with access to your GitHub repository.
- These items, if your pipeline uses them:
- Service connection credentials
- Files from the secure files library
- Build variables marked secret
To bypass this precaution on GitHub pipelines, enable the Make secrets available to builds of forks check box. Be aware of this setting's effect on security.
Note
When you enable fork builds to access secrets, Azure Pipelines by default restricts the access token used for fork builds. It has more limited access to open resources than a normal access token. To give fork builds the same permissions as regular builds, enable the Make fork builds have the same permissions as regular builds setting.
For more information, see Repository protection - Forks.
You can define centrally how pipelines build PRs from forked GitHub repositories using the Limit building pull requests from forked GitHub repositories control. It's available at organization and project level. You can choose to:
- Disable building pull requests from forked repositories
- Securely build pull requests from forked repositories
- Customize rules for building pull requests from forked repositories
:::image type="content" source="media/centralized-pipeline-control.png" alt-text="Screenshot of centralized control settings for how pipelines build PRs from forked GitHub repositories.":::
When you choose the Securely build pull requests from forked repositories option, all pipelines, organization or project-wide, cannot make secrets available to builds of PRs from forked repositories, cannot make these builds have the same permissions as normal builds, and must be triggered by a PR comment. Projects can still decide to not allow pipelines to build such PRs.
When you choose the Customize option, you can define how to restrict pipeline settings. For example, you can ensure that all pipelines require a comment in order to build a PR from a forked GitHub repo, when the PR belongs to non-team members and non-contributors. But, you can choose to allow them to make secrets available to such builds. Projects can decide to not allow pipelines to build such PRs, or to build them securely, or have even more restrictive settings than what is specified at the organization level.
The control is off for existing organizations. Starting September 2023, new organizations have Securely build pull requests from forked repositories turned on by default.
A GitHub user can fork your repository, change it, and create a pull request to propose changes to your repository. This pull request could contain malicious code to run as part of your triggered build. Such code can cause harm in the following ways:
-
Leak secrets from your pipeline. To mitigate this risk, don’t enable the Make secrets available to builds of forks check box if your repository is public or untrusted users can submit pull requests that automatically trigger builds. This option is disabled by default.
-
Compromise the machine running the agent to steal code or secrets from other pipelines. To mitigate this:
-
Use a Microsoft-hosted agent pool to build pull requests from forks. Microsoft-hosted agent machines are immediately deleted after they complete a build, so there’s no lasting impact if they're compromised.
-
If you must use a self-hosted agent, don’t store any secrets or perform other builds and releases that use secrets on the same agent, unless your repository is private and you trust pull request creators.
-
Repository collaborators can comment on a pull request to manually run a pipeline. Here are a few common reasons for why you might want to do this:
- You may not want to automatically build pull requests from unknown users until their changes can be reviewed. You want one of your team members to first review their code and then run the pipeline. This is commonly used as a security measure when building contributed code from forked repositories.
- You may want to run an optional test suite or one more validation build.
To enable comment triggers, you must follow the following two steps:
- Enable pull request triggers for your pipeline, and make sure that you didn’t exclude the target branch.
- In the Azure Pipelines web portal, edit your pipeline and choose More actions, Triggers. Then, under Pull request validation, enable Require a team member's comment before building a pull request.
- Choose On all pull requests to require a team member's comment before building a pull request. With this workflow, a team member reviews the pull request and triggers the build with a comment once the pull request is deemed safe.
- Choose Only on pull requests from non-team members to require a team member's comment only when a PR is made by a non-team member. In this workflow, a team member doesn't need a secondary team member's review to trigger a build.
With these two changes, the pull request validation build won’t be triggered automatically, unless Only on pull requests from non-team members is selected and the PR is made by a team member. Only repository owners and collaborators with 'Write' permission can trigger the build by commenting on the pull request with /AzurePipelines run or /AzurePipelines run <pipeline-name>.
The following commands can be issued to Azure Pipelines in comments:
| Command | Result |
|---|---|
/AzurePipelines help |
Display help for all supported commands. |
/AzurePipelines help <command-name> |
Display help for the specified command. |
/AzurePipelines run |
Run all pipelines that are associated with this repository and whose triggers don’t exclude this pull request. |
/AzurePipelines run <pipeline-name> |
Run the specified pipeline unless its triggers exclude this pull request. |
Note
For brevity, you can comment using /azp instead of /AzurePipelines.
Important
Responses to these commands will appear in the pull request discussion only if your pipeline uses the Azure Pipelines GitHub App.
If you have the necessary repository permissions, but pipelines aren't getting triggered by your comments, make sure that your membership is public in the repository's organization, or directly add yourself as a repository collaborator. Pipelines can’t see private organization members unless they are direct collaborators or belong to a team that is a direct collaborator. You can change your GitHub organization membership from private to public here (replace Your-Organization with your organization name): https://github.com/orgs/Your-Organization/people.
[!INCLUDE informational-runs]
Learn more about informational runs.
[!INCLUDE ci-triggers]
When you build a GitHub repository, most of the predefined variables are available to your jobs. However, since Azure Pipelines doesn’t recognize the identity of a user making an update in GitHub, the following variables are set to system identity instead of user's identity:
Build.RequestedForBuild.RequestedForIdBuild.RequestedForEmail
There are two types of statuses that Azure Pipelines posts back to GitHub - basic statuses and GitHub Check Runs. GitHub Checks functionality is only available with GitHub Apps.
Pipeline statuses show up in various places in the GitHub UI.
- For PRs, they’re displayed on the PR conversations tab.
- For individual commits, they’re displayed when hovering over the status mark after the commit time on the repo's commits tab.
For pipelines using PAT or OAuth GitHub connections, statuses are posted back to the commit/PR that triggered the run. The GitHub status API is used to post such updates. These statuses contain limited information: pipeline status (failed, success), URL to link back to the build pipeline, and a brief description of the status.
Statuses for PAT or OAuth GitHub connections are only sent at the run level. In other words, you can have a single status updated for an entire run. If you have multiple jobs in a run, you can’t post a separate status for each job. However, multiple pipelines can post separate statuses to the same commit.
For pipelines set up using the Azure Pipelines GitHub app, the status is posted back in the form of GitHub Checks. GitHub Checks allow for sending detailed information about the pipeline status and test, code coverage, and errors. The GitHub Checks API can be found here.
For every pipeline using the GitHub App, Checks are posted back for the overall run and each job in that run.
GitHub allows three options when one or more Check Runs fail for a PR/commit. You can choose to "rerun" the individual Check, rerun all the failing Checks on that PR/commit, or rerun all the Checks, whether they succeeded initially or not.
Clicking on the "Rerun" link next to the Check Run name will result in Azure Pipelines retrying the run that generated the Check Run. The resultant run will have the same run number and will use the same version of the source code, configuration, and YAML file as the initial build. Only those jobs that failed in the initial run and any dependent downstream jobs will be run again. Clicking on the "Rerun all failing checks" link will have the same effect. This is the same behavior as clicking "Retry run" in the Azure Pipelines UI. Clicking on "Rerun all checks" will result in a new run, with a new run number and will pick up changes in the configuration or YAML file.
[!INCLUDE limitations]
Problems related to GitHub integration fall into the following categories:
- Connection types: I’m not sure what connection type I’m using to connect my pipeline to GitHub.
- Failing triggers: My pipeline isn’t being triggered when I push an update to the repo.
- Failing checkout: My pipeline is being triggered, but it fails in the checkout step.
- Wrong version: My pipeline runs, but it’s using an unexpected version of the source/YAML.
- Missing status updates: My GitHub PRs are blocked because Azure Pipelines didn’t report a status update.
Troubleshooting problems with triggers very much depends on the type of GitHub connection you use in your pipeline. There are two ways to determine the type of connection - from GitHub and from Azure Pipelines.
-
From GitHub: If a repo is set up to use the GitHub app, then the statuses on PRs and commits will be Check Runs. If the repo has Azure Pipelines set up with OAuth or PAT connections, the statuses will be the "old" style of statuses. A quick way to determine if the statuses are Check Runs or simple statuses is to look at the "conversation" tab on a GitHub PR.
- If the "Details" link redirects to the Checks tab, it’s a Check Run and the repo is using the app.
- If the "Details" link redirects to the Azure DevOps pipeline, then the status is an "old style" status and the repo isn’t using the app.
-
From Azure Pipelines: You can also determine the type of connection by inspecting the pipeline in Azure Pipelines UI. Open the editor for the pipeline. Select Triggers to open the classic editor for the pipeline. Then, select YAML tab and then the Get sources step. You'll notice a banner Authorized using connection: indicating the service connection that was used to integrate the pipeline with GitHub. The name of the service connection is a hyperlink. Select it to navigate to the service connection properties. The properties of the service connection will indicate the type of connection being used:
- Azure Pipelines app indicates GitHub app connection
- oauth indicates OAuth connection
- personalaccesstoken indicates PAT authentication
Using a GitHub app instead of OAuth or PAT connection is the recommended integration between GitHub and Azure Pipelines. To switch to GitHub app, follow these steps:
- Navigate here and install the app in the GitHub organization of your repository.
- During installation, you'll be redirected to Azure DevOps to choose an Azure DevOps organization and project. Choose the organization and project that contain the classic build pipeline you want to use the app for. This choice associates the GitHub App installation with your Azure DevOps organization. If you choose incorrectly, you can visit this page to uninstall the GitHub app from your GitHub org and start over.
- In the next page that appears, you don’t need to proceed creating a new pipeline.
- Edit your pipeline by visiting the Pipelines page (e.g., https://dev.azure.com/YOUR_ORG_NAME/YOUR_PROJECT_NAME/_build), selecting your pipeline, and clicking Edit.
- If this is a YAML pipeline, select the Triggers menu to open the classic editor.
- Select the "Get sources" step in the pipeline.
- On the green bar with text "Authorized using connection", select "Change" and select the GitHub App connection with the same name as the GitHub organization in which you installed the app.
- On the toolbar, select "Save and queue" and then "Save and queue". Select the link to the pipeline run that was queued to make sure it succeeds.
- Create (or close and reopen) a pull request in your GitHub repository to verify that a build is successfully queued in its "Checks" section.
Depending on the authentication type and ownership of the repository, specific permissions are required.
- If you're using the GitHub App, see GitHub App authentication.
- If you're using OAuth, see OAuth authentication.
- If you're using PATs, see Personal access token (PAT) authentication.
When I select a repository during pipeline creation, I get an error "The repository {repo-name} is in use with the Azure Pipelines GitHub App in another Azure DevOps organization."
This means that your repository is already associated with a pipeline in a different organization. CI and PR events from this repository won't work as they’ll be delivered to the other organization. Here are the steps you should take to remove the mapping to the other organization before proceeding to create a pipeline.
-
Open a pull request in your GitHub repository, and make the comment
/azp where. This reports back the Azure DevOps organization that the repository is mapped to. -
To change the mapping, uninstall the app from the GitHub organization, and reinstall it. As you reinstall it, make sure to select the correct organization when you’re redirected to Azure DevOps.
[!INCLUDE qa]
-
Are you using the GitHub app connection to connect the pipeline to GitHub? See Connection types to determine the type of connection you have. If you’re using a GitHub app connection, follow these steps:
-
Is the mapping set up properly between GitHub and Azure DevOps? Open a pull request in your GitHub repository, and make the comment
/azp where. This reports back the Azure DevOps organization that the repository is mapped to.-
If no organizations are set up to build this repository using the app, go to
https://github.com/<org_name>/<repo_name>/settings/installationsand complete the configuration of the app. -
If a different Azure DevOps organization is reported, then someone has already established a pipeline for this repo in a different organization. We currently have the limitation that we can only map a GitHub repo to a single DevOps org. Only the pipelines in the first Azure DevOps org can be automatically triggered. To change the mapping, uninstall the app from the GitHub organization, and reinstall it. As you reinstall it, make sure to select the correct organization when you’re redirected to Azure DevOps.
-
-
-
Are you using OAuth or PAT to connect the pipeline to GitHub? See Connection types to determine the type of connection you have. If you’re using a GitHub connection, follow these steps:
-
OAuth and PAT connections rely on webhooks to communicate updates to Azure Pipelines. In GitHub, navigate to the settings for your repository, then to Webhooks. Verify that the webhooks exist. Usually you should see three webhooks - push, pull_request, and issue_comment. If you don't, then you must re-create the service connection and update the pipeline to use the new service connection.
-
Select each of the webhooks in GitHub and verify that the payload that corresponds to the user's commit exists and was sent successfully to Azure DevOps. You may see an error here if the event couldn’t be communicated to Azure DevOps.
-
-
The traffic from Azure DevOps could be throttled by GitHub. When Azure Pipelines receives a notification from GitHub, it tries to contact GitHub and fetch more information about the repo and YAML file. If you have a repo with a large number of updates and pull requests, this call may fail due to such throttling. In this case, see if you can reduce the frequency of builds by using batching or stricter path/branch filters.
[!INCLUDE qa]
[!INCLUDE qa]
[!INCLUDE qa]
remote: Repository not found.
fatal: repository <repo> not found
This could be caused by an outage of GitHub. Try to access the repository in GitHub and make sure that you’re able to.
[!INCLUDE qa]
This could be a transient error that resulted in Azure DevOps not being able to communicate with GitHub. Retry the check-in GitHub if you use the GitHub app. Or, make a trivial update to the PR to see if the problem can be resolved.