To show, review and create the pull requests of a repository, the extension needs a personal access token (PAT) for its organisation or collection. You give it once for each workspace folder.

To set up the reviews and approvals of model changes, see Track and approve model changes.

You need:

• a repository on Azure DevOps (dev.azure.com or visualstudio.com), or on Azure DevOps Server 2022.1 or later;
• the workspace folder cloned from that repository with Git.

Create a personal access token

1. Open your organisation, such as https://dev.azure.com/your-organisation, or your Azure DevOps Server collection, such as https://your-server/tfs/DefaultCollection, in the browser.

2. Open User settings (the icon next to your picture, at the top right) and pick Personal access tokens.

3. Select New Token. Give it a name, such as Pywr for VS Code, pick your organisation (on Azure DevOps Server, the collection) and an expiration date.

4. Select Custom defined and tick these scopes:

   • Code: Read & write, to list, review, vote on and complete pull requests;
   • Work Items: Read & write, to search work items and link them to pull requests;
   • Pull Request Threads: Read & write, to read, start, answer and resolve the comment threads of pull requests.

5. Select Create and copy the token. Azure DevOps shows it only once.

Caution

Treat the token like a password. Anyone who has it can do with your repositories what the scopes allow until it expires.

Connect the folder

1. Open the folder of the repository and run Pywr: Connect to Azure DevOps from the Command Palette. With several workspace folders, pick the folder first.

2. Check the address of the repository. It is filled in from the address the folder was cloned from, in the form of the address of the repository in the browser, such as:

   • https://dev.azure.com/your-organisation/your-project/_git/your-repository
   • https://your-server/tfs/DefaultCollection/your-project/_git/your-repository

3. Paste the token and press Enter. The box stays open while you switch to the browser to copy it.

The extension checks the token and the repository with Azure DevOps before saving them. When it works, it says which repository it connected to and as whom. You do not need to give a username: Azure DevOps finds you from the token.

Use an address that starts with https. With http, the token is sent unencrypted to the server at each request.

Where the token is kept

The address and the token are saved encrypted in the file .vscode/pywr-azure-devops.enc of the folder. The key that decrypts the file is not in the folder: it is kept in the keychain of your computer (the Keychain on macOS, the Credential Manager on Windows, the secret service on Linux) through VS Code.

• The file is added to the .gitignore of the repository before it is written, so it is not shown as a change to commit. The extension tells you when it adds the line: commit the change to .gitignore.
• A copy of the file on another computer, or in a backup, cannot be read without your keychain. On another computer, connect again.
• The key belongs to the path of the folder. After moving or renaming the folder, the extension cannot read the file any more and asks you to connect again.

To use a new token, for example when the old one expires, run Pywr: Update the Azure DevOps token. To remove the connection, run Pywr: Disconnect from Azure DevOps: it deletes both the file and the key.

When the connection does not work

The message says what went wrong:

• rejected the personal access token: the token is wrong, has expired, or was made for another organisation or collection. Create a new one and run Pywr: Update the Azure DevOps token.
• The personal access token cannot do this: the token does not have the scopes above. Edit it in the browser to add them.
• was not found: check the project and the repository in the address.
• The certificate of … is not trusted: your Azure DevOps Server uses a certificate of your organisation. Ask your IT team to add it to the trusted certificates of your computer.
• needs Azure DevOps Server 2022.1 or later: the server is older. The extension uses version 7.1 of the REST API, which older servers do not have.
• moved the request to: the server answered from another address, for example https instead of http. Connect with the address in the message.