Back to table of contents

Join DASH-IF on Slack!

Administrator Guide

To set up a new document, follow this guide. You are expected to be casually familiar with GitHub and Azure DevOps.

Prerequisites

To set up a new document, you need:

All these resources can be reused for multiple documents, except for the repository - each document must be in a separate repository.

Associate build bot with Azure DevOps

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.

Associate comment bot with Azure DevOps

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.

Associate publishing point with Azure DevOps

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.

Create build definition

Clone an existing document build definition in Azure DevOps (e.g. the one used by DocumentAuthoringExample) and update the following data:

After verifying that all the data is valid for the new document, save the build definition. Automated builds should now be active.

Assign editors

Give the editors write-level collaborator access to the document repository.

Configure publishing website

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>