- Motivation
- Data-Mining Modes
- Usage
- Action Configuration
- Action Outputs
- How-to
- Contribution Guidelines
Addresses the need for continuously updated documentation accessible to all team members and stakeholders. Achieves this by extracting information directly from Azure DevOps and providing it in a JSON format, which can be easily transformed into various documentation formats. This approach ensures that the documentation is always up-to-date and relevant, reducing the burden of manual updates and improving overall project transparency.
This Collector supports multiple mining modes, each with its own unique functionality. Read more about the modes at their respective links:
Before we begin, ensure you have fulfilled the following prerequisites:
- Azure DevOps Personal Access Token (PAT) with read permission on the target organizations and projects.
- Python version 3.14 or higher.
See the default action step definition:
- name: Living Documentation Collector for Azure DevOps
id: living_doc_collector_ad
uses: AbsaOSS/living-doc-collector-ad@v0.1.0
with:
ADO-TOKEN: ${{ secrets.ADO_ACCESS_TOKEN }}
# modes de/activation
work-items: falseSee the default action step definitions for each mode:
See the full example of action step definition (in the example, non-default values are used):
- name: Living Documentation Collector for Azure DevOps
id: living_doc_collector_ad
uses: AbsaOSS/living-doc-collector-ad@v0.1.0
with:
ADO-TOKEN: ${{ secrets.ADO_ACCESS_TOKEN }}
work-items: true # Work Items mode de/activation
verbose-logging: true # Optional: verbose (debug) logging de/activation
# 'Work Items' mode required configuration
work-items-organizations: |
[
{
"organization-name": "your-ado-organization",
"projects-name-filter": []
},
{
"organization-name": "your-another-ado-organization",
"projects-name-filter": ["Project Alpha", "Project Beta"]
}
]This section outlines the essential parameters that are common to all modes a user can define. Configure the action by customizing the following parameters based on your needs:
This action does not use environment variables directly. Pass the ADO token via the ADO-TOKEN input as shown in the examples above.
Note: Unlike some GitHub Actions, this action accepts the
ADO-TOKENas awith:input rather than anenv:variable to keep the configuration explicit and self-contained.
These inputs are common to all modes.
| Input Name | Description | Required | Default | Usage |
|---|---|---|---|---|
ADO-TOKEN |
Azure DevOps Personal Access Token for authentication. | Yes | Pass via with:. |
|
work-items |
Enables or disables Work Items mode. |
Yes | false |
Set to true to activate. |
verbose-logging |
Enables or disables verbose (debug) logging. | No | false |
Set to true to activate. |
with:
ADO-TOKEN: ${{ secrets.ADO_ACCESS_TOKEN }}
work-items: true # Activation of Work Items mode
verbose-logging: true # Activation of verbose (debug) loggingMode-specific inputs and outputs are detailed in the respective mode's documentation:
The action provides a main output path that allows users to locate and access the generated JSON files easily. This output can be utilized in various ways within your CI/CD pipeline to ensure the documentation is effectively distributed and accessible.
output-path- Description: The root output path to the directory where all generated living documentation files are stored.
- Usage:
- name: Living Documentation Collector for Azure DevOps id: living_doc_collector_ad ... rest of the action definition ... - name: Output Documentation Path run: echo "ADO Collector root output path: ${{ steps.living_doc_collector_ad.outputs.output-path }}"
Each mode generates its output files, which are stored in the
output-pathdirectory with clear naming conventions.
See this Developer Guide for more technical, development-related information.
This section aims to help the user walk through different processes, such as:
- Sign in to your Azure DevOps organization (
https://dev.azure.com/{yourorganization}). - Click on your profile icon in the top-right corner and select Personal access tokens.
- Click New Token.
- Give the token a name and choose expiration date.
- Select the following scopes (minimum required):
- Work Items → Read
- Project and Team → Read
- Build → Read (if pipelines mode will be used)
- Click Create and copy the token value — you will not be able to see it again.
- Go to the GitHub repository from which you want to run this GitHub Action.
- Click on the
Settingstab in the top bar. - In the left sidebar, click on
Secrets and variables>Actions. - Click on the
New repository secretbutton. - Name the secret
ADO_ACCESS_TOKENand paste the token value.
We welcome contributions to the Living Documentation Collector! Whether you're fixing bugs, improving documentation, or proposing new features, your help is appreciated.
Before contributing, please review our contribution guidelines for more detailed information.
This project is licensed under the Apache License 2.0. It is a liberal license that allows you great freedom in using, modifying, and distributing this software, while also providing an express grant of patent rights from contributors to users.
For more details, see the LICENSE file in the repository.
If you need help with using or contributing to the Living Documentation Collector Action, or if you have any questions or feedback, don't hesitate to reach out:
- Issue Tracker: For technical issues or feature requests, use the GitHub Issues page.
- Discussion Forum: For general questions and discussions, join our GitHub Discussions forum.