To set up a new document, follow this guide. You are expected to be casually familiar with GitHub and Azure DevOps.
To set up a new document, you need:
- A GitHub repository for the document. This must be owned by an organization (not a personal account).
- A GitHub user with admin rights in the document repository (not your own user account, to limit access to minimum required).
- A GitHub user account with no special rights assigned, for posting automated build reports on pull requests.
- Admin access to an Azure DevOps account to be used for build automation.
- A web server for publishing build output PDF/HTML files and the corresponding FTP/SSH credentials.
All these resources can be reused for multiple documents, except for the repository - each document must be in a separate repository.
The build bot is the GitHub account with admin rights to the document repository.
You only need to perform this setup once per bot account. If you are reusing an account, simply grant it admin rights to the new repository and skip this section.
Log in to GitHub with this account and add a new Personal Access Token with the following scopes: repo, read:user, user:email, admin:repo_hook.
In Azure DevOps, add a new service connection to the account. Specify GitHub as the type and enter the token that you just created.
You will need to reference this service connection later, so remember its name.
The comment bot is the GitHub account with no special rights assigned.
You only need to perform this setup once per bot account. If you are reusing an account, skip this section.
Log in to GitHub with this account and add a new Personal Access Token with the following scopes: public_repo.
In Azure DevOps, add a new variable group with the following variables:
GitHubBotUsername - GitHub username of the account.
GitHubToken - the created token. Mark this variable as secret (click the lock icon).
You will need to reference this variable group later, so remember its name.
Add a new service connection to the account. Specify Generic as the type and enter the FTP/SSH connection details.
You will need to reference this service connection later, so remember its name.
Clone an existing document build definition in Azure DevOps (e.g. the one used by DocumentAuthoringExample) and update the following data:
- GitHub service connection (in Get Sources task)
- repository name (in Get Sources task)
- publishing point service connection (in FTP publisher task)
- publishing point root directory path (in FTP publisher task)
- comment bot variable group reference (in Variables)
- any other variables listed in the Variables tab
After verifying that all the data is valid for the new document, save the build definition. Automated builds should now be active.
Give the editors write-level collaborator access to the document repository.
Consider disabling caching and enabling directory browsing on the website you use to host the documents. This ensures that updates are seen immediately and that the directory structure can be easily browsed without having to look up URLs.
If you use Azure Websites then the following web.config file in the root directory will accomplish this:
<configuration>
<system.webServer>
<staticContent>
<clientCache cacheControlMode="DisableCache" />
</staticContent>
<directoryBrowse enabled="true" />
</system.webServer>
</configuration>