Azure DevOps Integration

Source control integrations can be configured for Self-Hosted Runners. You can set up a Azure DevOps integration during runner creation or in the runner settings. Self-hosted Azure DevOps instances are supported by changing the Host during setup.

Configuring Azure DevOps Access

Note: You can skip this step if someone has already set up the runner for you and SCM integration with Azure DevOps has already been configured. In that case, you can go directly to Authorizing Azure DevOps Access. This step allows administrators to configure what authorization methods (OAuth, PATs) and SCM providers (GitHub, Azure DevOps, Bitbucket, Azure DevOps) will be available for authorization.

Self-Hosted Runners

For self-hosted runners (like AWS), Azure DevOps integration is configured during runner creation or in the runner settings.

There are two ways to integrate with Azure DevOps. Both can be used simultaneously:

1. OAuth App (Recommended): Using an OAuth app allows users to sign in more quickly. You’ll need to set up an OAuth app within Gitpod.
2. Personal Access Token (PAT): Each user will need to create a Personal Access Token. They will be provided with a deep link to do so on their first environment creation.

Using OAuth

Note: Your organization can set policies that disallow the usage of OAuth Apps. While you will be able to create an OAuth App, the authentication flow will fail with an invalid scope error message. If you encounter this error please contact the administrator for your Azure DevOps organization. The policiy can be found under Organization Settings -> Security -> Policies -> Third-party application access with OAuth.

1. Go to Settings > Runners and select the runner for which you want to configure OAuth.
2. Navigate to the “Configure repository access” section and click “Add a new provider”.
3. Select Azure DevOps from the list of providers.
4. In the modal that opens, toggle “Enable OAuth”.
5. Follow the instructions in Azure DevOps’s docs to create an OAuth app.
   • The company and app name can be any name you like
   • For the application website you can use https://app.gitpod.io/
   • You can get the callback URL from the SCM configuration dialog
   • Select the required scopes
     • The Code (read and write) scope is required so that the context url can be parsed, your environment can clone the repository and changes can be pushed from your environment to the repository
6. After creating the OAuth app, provide the App ID and Client Secret in the runner configuration dialog. The client secret will be encrypted with the runner’s public key, ensuring only the runner can read it.
7. Save your changes

Using Personal Access Tokens (PATs)

1. Go to Settings > Runners and select the runner for which you want to configure the PAT.
2. Navigate to the “Configure repository access” section and click “Add a new provider”.
3. Select Azure DevOps from the list of providers.
4. In the modal that opens, toggle “Enable Personal Access Token”.
5. Save your changes

Authorizing Azure DevOps Access

Using OAuth

1. When creating your first environment, you will be asked to authorize the new application. To use OAuth press the Connect button. A new window will open that directs you to Azure DevOps to authorize the OAuth app. The requested scopes are Code (read and write).

   • The Code (read and write) scope is required so that the context url can be parsed, your environment can clone the repository and changes can be pushed from your environment to the repository

2. After you have authorized Gitpod, you can close the window. After a few seconds the you should get a confirmation that Azure DevOps is now connected.

Using Personal Access Tokens (PATs)

1. When creating your first environment, you will be asked to authorize the new application. Select Provide a Personal Access Token.

   • Follow the instructions of the Azure documentation to create a PAT
   • The name of the token and all required scopes are pre-set.
   • By default, the token is valid for 30 days, but you can change the duration if needed.

2. After creating the token, return to the dialog and paste the token.

3. The environment will now be created using the provided token.