ELITEA Toolkit Guide: Azure DevOps Wiki, Boards, and Plans Integration

Introduction

Purpose of the Guide

This guide is your comprehensive resource for integrating and utilizing the Azure DevOps (ADO) Wiki, Boards, and Plans toolkits within ELITEA. It provides detailed, step-by-step instructions, from setting up your Azure DevOps Personal Access Token to configuring these toolkits in ELITEA and seamlessly incorporating them into your Agents. By following this guide, you will unlock the power of automated knowledge management, streamlined project planning, and enhanced workflow automation within Azure DevOps, all directly from the ELITEA platform. This integration empowers you to leverage AI-driven automation to optimize your DevOps processes, enhance team collaboration, and improve overall project visibility within the Azure DevOps ecosystem.

Brief Overview of Azure DevOps (ADO) Services for Wiki, Boards, and Plans

ELITEA's integration with Azure DevOps focuses on empowering users to leverage key Azure DevOps services for enhanced project management, knowledge sharing, and workflow automation. This guide specifically covers integration with:

ELITEA's integration with ADO Wiki, Boards, and Plans allows you to bring these powerful Azure DevOps services directly into your AI-driven workflows, enabling agents to:

Toolkit's Account Setup and Configuration

Account Creation and Access

Account Setup

If you do not yet have an Azure DevOps account and organization, please follow these steps to create one, ensuring you have access to Azure DevOps Wiki, Boards, and Plans services:

  1. Visit Azure DevOps Website: Open your web browser and navigate to the Azure DevOps website: https://azure.devops.com/.
  2. Start Free or Sign In: Click on the "Start free" button to create a new Azure DevOps organization, or click "Sign in to Azure DevOps" if you already have an organization and wish to sign in.
  3. Create an Organization (If Needed):
    • If you are creating a new organization, click "Create an Organization" and follow the prompts to set up your new Azure DevOps organization. You will typically need to provide an organization name, choose a hosting region, and link it to an Azure account (if you have one).
    • If you are signing into an existing organization, click "Sign in to Azure DevOps" and log in using your Microsoft account credentials.
  4. Enter Account Details: Provide the required details as prompted during the organization creation or sign-in process. This may include your email address, organization name, and region for hosting your Azure DevOps organization.
  5. Email Verification (If Prompted): Verify your email address if prompted by the Azure DevOps signup process. This usually involves clicking a confirmation link sent to your email inbox.
  6. Log In to Azure DevOps: Log in to the Azure DevOps dashboard using your newly created or existing Microsoft account credentials.
  7. Enable Basic Subscription (Essential for Boards, Plans and Wiki): Ensure that you have a Basic Azure DevOps subscription enabled for your account. The Basic subscription is required to access Azure Boards, Azure Repos, Azure Pipelines, Azure Test Plans, and Azure Artifacts. For new organizations, the Basic subscription is typically enabled by default. For existing organizations, you may need to verify or enable it in the organization settings to ensure access to all required services.
  8. Add Users and Assign Basic Subscription (If Needed): To grant access to other users within your organization who will be using ELITEA integrations with Azure DevOps Wiki, Boards, and Plans, navigate to your organization settings:
    • Go to https://dev.azure.com/{YourOrganizationName}/_settings/users (replace {YourOrganizationName} with your actual Azure DevOps organization name).
    • Click "Add users".
    • Enter the user's email address or Microsoft account.
    • Select "Basic" from the "Access level" dropdown to assign a Basic subscription to the user, granting them access to Boards, Plans and Wiki services.
    • Choose the relevant project(s) to grant the user access to.
    • Click "Add" to add the user to your Azure DevOps organization.
  9. Add User to Project Member Group (If Needed): To ensure newly added users have the necessary permissions within a specific project to access and utilize Wiki, Boards, and Plans:
    • Navigate to "Project settings" for your desired project (located at the bottom left of the Azure DevOps interface).
    • Select "Groups" under "Security" in the Project settings menu.
    • Locate the "Project Valid Users" group (or a relevant group for your project's members) and click on the group name.
    • Click on the "Members" tab within the group details.
    • Click "Add users or groups".
    • Enter the email address or name of the user you want to add to the project member group and click "Add".
  10. Verify Wiki, Boards and Plans Access: After completing user setup, refresh the Azure DevOps page and ensure that the "Boards", "Wiki" and "Test Plans" features are now enabled and visible for your account within your Azure DevOps project. You should see "Boards", "Repos", "Pipelines", "Test Plans", and "Wiki" in the left-hand sidebar of your project. This confirms that you have successfully set up your Azure DevOps account and have access to Azure DevOps Services required for ELITEA integration.

Note: If the "Boards", "Wiki", or "Test Plans" features are not available, you may need to create a new project within your Azure DevOps organization or verify that these services are enabled for your organization and project in the Azure DevOps organization settings under "General" -> "Services".

Token/API Key Generation: Creating a Personal Access Token in Azure DevOps

For secure integration with ELITEA, it is essential to use an Azure DevOps Personal Access Token (PAT). This method is significantly more secure than using your primary Azure DevOps account password directly and allows you to precisely control the permissions granted to ELITEA for accessing Azure DevOps Wiki, Boards, and Plans services.

Follow these steps to generate a Personal Access Token (PAT) in Azure DevOps:

  1. Log in to Azure DevOps: Access your Azure DevOps organization by navigating to https://dev.azure.com/ and logging in with your credentials.
  2. Access User Settings: Click on the User settings icon, typically located in the top right corner of the Azure DevOps interface, next to your profile picture. From the dropdown menu, select "Personal access tokens".
  3. Generate New Token: On the "Personal Access Tokens" page, click the "+ New Token" button to create a new PAT.

  4. Configure Token Details: In the "Create a new personal access token" panel, configure the following settings:

    • Name: In the "Name" field, enter a descriptive label for your token. For example, use "ELITEA Wiki Boards Plans Token" or "ELITEA Agent Access for ADO Services." This label will help you easily identify the purpose of this token in the future.
    • Organization (Optional): Select the Azure DevOps organization for which this token will be valid. In most cases, you will select "All accessible organizations" to allow the token to access resources across your organizations.
    • Expiration (Recommended): For enhanced security, it is highly recommended to set an Expiration date for your token. Choose a reasonable validity period that aligns with your security policies. Shorter expiration periods are generally more secure.

    • Scopes - Grant Least Privilege (Crucial for Security): Carefully and deliberately select the scopes or permissions you grant to this token. It is paramount to grant only the minimum necessary permissions required for your ELITEA Agent's intended interactions with Azure DevOps Wiki, Boards, and Plans. Overly permissive tokens pose a significant security risk. For typical ELITEA integration with ADO Wiki, Boards, and Plans, consider these minimal scopes, selecting "Custom defined" and then choosing granular scopes:

      • Minimal Scopes for Common Use Cases:

        • Work items: Expand the "Work items" section and select:
          • Read: (If your Agent only needs to retrieve information from Azure Boards, select "Read")
          • Write: (If your Agent needs to create, update, or manage work items in Azure Boards, select "Write". Only include this if your Agent needs to modify Boards content.)
        • Wiki: Expand the "Wiki" section and select:
          • Read & write: (Grants read and write access to Azure DevOps Wiki, allowing Agents to both retrieve and modify wiki content. If your Agent only needs to read Wiki content, you can select "Read" for tighter security.)
        • Test Management: Expand the "Test Management" section and select:
          • Read: (If your Agent only needs to retrieve information from Azure Test Plans, select "Read")
          • Read & write: (If your Agent needs to create, update, or manage test plans, test suites, or test cases in Azure Test Plans, select "Read & write". Only include write access if your Agent needs to modify Test Plans content.)

      • Important Scope Considerations:

        • Granular Scopes: Whenever possible, opt for granular scopes (e.g., "Work items - Read", "Wiki - Read") over broader scopes (e.g., "Work items - Full access", "Wiki - Read & write") to adhere to the principle of least privilege.
        • Tool-Specific Scopes: Select scopes based on the specific Azure DevOps toolkits you intend to use in ELITEA. If you are only using the ADO Wiki toolkit, you only need to grant Wiki scopes, and so on. Avoid granting scopes for toolkits you are not using.

    Important Security Best Practices:

    • Principle of Least Privilege: Strictly adhere to the principle of least privilege. Grant only the absolute minimum set of scopes necessary for your ELITEA Agent to perform its specific, intended tasks with Azure DevOps Wiki, Boards, and Plans. Avoid granting broad or unnecessary permissions.
    • Avoid Full Access Scopes: Avoid granting full access scopes like "Full access" unless absolutely necessary and with a clear and thorough understanding of the significant security implications. Full access scopes provide extensive administrative privileges and should be avoided for integration purposes whenever possible.
    • Regular Token Review and Rotation: Implement a process for regularly reviewing the Personal Access Tokens you have generated, their associated scopes, and their usage. Rotate tokens periodically (generate new tokens and revoke older ones) as a proactive security measure, especially for integrations that handle sensitive data or critical operations within Azure DevOps.
    • Secure Storage: Store the generated Personal Access Token securely, preferably using ELITEA's built-in Secrets Management feature, rather than hardcoding it directly in Agent configurations or less secure storage locations.

  5. Create Token: Click the "Create" button at the bottom of the panel to generate your Personal Access Token.

  6. Securely Copy and Store the Token: Immediately copy the generated token that is displayed in the "Success!" pop-up window. This is the only time you will be able to view and copy the full token value. Store it securely using a robust password manager or, ideally, ELITEA's built-in Secrets feature for enhanced security within the ELITEA platform. You will require this token to configure the Azure DevOps Wiki, Boards, and Plans toolkits within ELITEA.

System Integration with ELITEA

Overview and Usage of Azure DevOps (ADO) Toolkits Integration with ELITEA

ELITEA's integration with Azure DevOps provides a suite of toolkits that allow your AI Agents to seamlessly interact with various Azure DevOps services, including Wiki, Boards, and Test Plans. This integration empowers your Agents to:

Integration Steps: Configuring Azure DevOps (ADO) Toolkits in ELITEA

To integrate Azure DevOps Wiki, Boards, and Test Plans with ELITEA and enable your Agents to interact with these services, follow these configuration steps within ELITEA:

  1. Navigate to Agents Menu: In ELITEA, go to the Agents menu and either create a new Agent or edit an existing Agent that you want to integrate with Azure DevOps services.
  2. Access Toolkits Section: Within the Agent configuration, scroll down to the "Tools" section.
  3. Add Toolkit: Click the "+" icon under the "TOOLS" section to add a new toolkit.
  4. Select Azure DevOps Toolkit: From the dropdown list of available toolkits, choose the specific Azure DevOps toolkit you want to configure:
    • "Azure Wiki (ADO Wiki)" (for Azure DevOps Wiki)
    • "Azure Boards (ADO Board)" (for Azure DevOps Boards)
    • "Azure Test Plans (ADO Test Plan)" (for Azure DevOps Test Plans)

  5. Configure Azure DevOps Toolkit Settings: Fill in the configuration fields for the selected Azure DevOps toolkit. The configuration steps are similar for all ADO toolkits:

    • Name: Enter a descriptive Name for your Azure DevOps toolkit instance. This name will be used to reference the toolkit within your Agent's instructions (e.g., "MyAzureWiki", "ProjectBoardAccess", "TestPlanManager").
    • Description: Provide a brief Description of the toolkit's purpose or the specific Azure DevOps service it will access (e.g., "Access to Project Alpha Wiki", "Work item management for Project Beta").
    • ADO Organization URL: Enter your Azure DevOps organization URL. Ensure you use the correct format, including your organization name: https://dev.azure.com/{YourOrganizationName} (Replace {YourOrganizationName} with your actual Azure DevOps organization name).
    • Project Name: Enter the Project Name within your Azure DevOps organization that contains the Wiki, Boards, or Test Plans you want to access (e.g., MyProject).
    • Personal Access Token: Paste the Personal Access Token you generated in Azure DevOps (during the "Software-Specific Setup" section of this guide) into the "Personal Access Token" field. Important Security Note: For enhanced security, consider using the "Secret" option instead and storing your Personal Access Token securely as a Secret within Secrets feature.

    ADO-Wiki_Configuration_Toolkit

    ADO-Board_Configuration_Toolkit

    ADO-Plan_Configuration_Toolkit

  6. Enable Desired Tools: In the "Tools" section within the Azure DevOps toolkit configuration, check the boxes next to the specific Azure DevOps tools you want to enable for your Agent. Select only the tools that your Agent will actually need to use to minimize unnecessary permissions and maintain security. The available tools vary depending on the specific Azure DevOps toolkit you are configuring (Wiki, Boards, or Test Plans). Refer to the "Tool Overview" section below for details on the tools available for each toolkit type.

  7. Complete Setup: Click the arrow icon (located at the top right of the toolkit configuration section) to complete the Azure DevOps toolkit setup and return to the main Agent configuration menu.

3.3 Tool Overview: Azure DevOps (ADO) Toolkit Functionalities

Once the Azure DevOps toolkits are configured and added to your Agent, you can leverage the following tools within your Agent's instructions to interact with Azure DevOps services:

ADO Wiki Tools:

ADO Board Tools:

ADO Test Plan Tools:

4. Instructions and Prompts for Using the Azure DevOps (ADO) Toolkits

To effectively utilize the Azure DevOps toolkits within your ELITEA Agents, you need to provide clear instructions within the Agent's "Instructions" field, telling the Agent how and when to use these tools.

General Instruction Structure:

When instructing your Agent to use an Azure DevOps toolkit, you will typically follow this pattern:

Use the "[tool_name]" tool to [describe the action you want to perform] in ADO [Wiki/Boards/Test Plans].
Provide the following parameters:
- Parameter 1: <value or description of value>
- Parameter 2: <value or description of value>
- ...

Example Agent Instructions for Azure DevOps (ADO) Toolkits Tools:

Important Considerations for Agent Instructions:

Best Practices and Use Cases for Azure DevOps (ADO) Integration

Best Practices for Efficient Integration

Use Cases

The Azure DevOps toolkits open up a wide range of automation possibilities for project management, documentation, and testing workflows within ELITEA. Here are some compelling use cases categorized by toolkit type:

ADO Wiki Toolkit Use Cases:

ADO Board Tools Use Cases:

ADO Test Plan Tools Use Cases:

Troubleshooting and Support

Troubleshooting Common Issues

FAQs

  1. Q: Can I use my regular Azure DevOps password for the ELITEA integration?
    • A: No, it is strongly recommended to use an Azure DevOps Personal Access Token instead of your main account password for security reasons. Personal Access Tokens provide a more secure and controlled way to grant access to external applications like ELITEA.
  2. Q: What scopes/permissions should I grant to the Azure DevOps Personal Access Token?
    • A: Grant only the minimum necessary scopes required for your ELITEA Agent's intended interactions with Azure DevOps services. For typical integration with ADO Wiki, Boards, and Test Plans, the vso.work_full, vso.wiki_full, and vso.test_full scopes are commonly needed. Avoid granting "Full access" or unnecessary permissions.
  3. Q: What is the correct format for the Azure DevOps Organization URL in the toolkit configuration?
    • A: The Azure DevOps URL should be entered in the format https://dev.azure.com/{YourOrganizationName}. Replace {YourOrganizationName} with your actual Azure DevOps organization name.
  4. Q: Why is my Agent getting "Permission Denied" errors even though I think I have configured everything correctly?
    • A: Double-check the scopes/permissions granted to your Azure DevOps Personal Access Token. Ensure that the token has the specific scopes required for the Azure DevOps tools your Agent is trying to use (e.g., vso.work_write scope for creating work items, vso.wiki_write for modifying wiki pages, vso.test_write for managing test plans). Also, verify that the Azure DevOps account associated with the token has the necessary access to the target project and the specific Azure DevOps services (Wiki, Boards, Test Plans).

Support and Contact Information

If you encounter any issues, have questions, or require further assistance beyond what is covered in this guide regarding the Azure DevOps integration or ELITEA Agents in general, please do not hesitate to contact our dedicated ELITEA Support Team. We are here to help you resolve any problems quickly and efficiently and ensure you have a smooth and productive experience with ELITEA.

How to Reach ELITEA Support:

Best Practices for Effective Support Requests:

To help us understand and resolve your issue as quickly as possible, please ensure you provide the following information in your support email:

Before Contacting Support:

We encourage you to first explore the resources available within this guide and the broader ELITEA documentation. You may find answers to common questions or solutions to known issues in the documentation.

To further enhance your understanding and skills in integrating Azure DevOps with ELITEA, here are some helpful resources: