Skip to main content

Creating a Brand-New Mono-Repository on GitHub Using DX Tools

This guide provides step-by-step instructions for creating and setting up a new mono-repository on GitHub using DX tools.

info

Currently, only projects with a single environment powered by Azure are supported. Additional tooling to support other scenarios is under development.

Setup GitHub Repository​

Start by creating the repository on GitHub:

gh repo create <org>/<repo-name> \
  --add-readme \
  --description <some-text> \
  --disable-wiki \
  --public \
  --clone

Then, follow these steps to complete the configuration.

Ensure an Appropriate Repository Access Control​

To ensure proper access control, follow these steps:

Define CODEOWNERS​

Define a CODEOWNERS file to manage repository ownership.

See https://help.github.com/en/articles/about-code-owners#example-of-a-codeowners-file

Create Dot Files​

Create the following dotfiles at the root of your repository:

  • .terraform-version: Specify the Terraform version to use (typically the latest available).
  • .gitignore: Add rules to manage Terraform files.
  • .pre-commit-config.yaml: Define pre-commit hooks.
  • .editorconfig: Enforce consistent coding styles.
  • .tflint.hcl: Configure TFLint for Terraform linting.
  • .trivyignore: Define rules for Trivy vulnerability scanning.

Authenticating with GitHub for Terraform Operations​

Changes to your repository via Terraform are applied from your local machine using the terraform apply command. This requires authentication with GitHub to ensure that the changes are applied correctly.

Before proceeding, ensure that you and your team have the required permissions to make changes to the repository.

Then, use one of the following methods to authenticate with GitHub:

  1. Using the GitHub CLI (recommended)
  2. Using a Personal Access Token (PAT)

Open your shell and run the command:


gh auth login

Follow the instructions on screen and you are ready to go.

Authenticate with PAT token​

To apply changes to your repository via Terraform, you can authenticate using a Personal Access Token (PAT). A single PAT with the following permissions is required for all repositories managed through Terraform:

  • read: metadata
  • read+write: variables, administration, environments, secrets

If you already have a PAT configured with these permissions, you may skip the next section.

Create the GitHub PAT​

If you do not already have a Personal Access Token (PAT), follow these steps:

  1. Go to your GitHub settings, under Developer settings, and create a new fine-grained PAT:
    • Add these permissions:
      • read: metadata
      • read+write: variables, administration, environments, secrets
    • Select Only select repositories and add the new repository.
    • Add a meaningful description like "PAT to manage GitHub locally via Terraform."
  2. In your local environment, set the GITHUB_TOKEN variable to the value of the generated PAT.
Add a new repository to the GitHub PAT​

If you already have the PAT in both your GitHub account and your CLI profile, ensure that the new repository is accessible from that PAT.

  1. Go to your GitHub settings, under Developer settings, and select the existing fine-grained PAT.
  2. Under Only select repositories, add your new repository.
warning

PATs have an expiration date. Be sure to renew them periodically.

Follow GitHub best practices and connect your repository to Azure using the azure-github-environment-bootstrap Terraform module.

  1. Create a folder named infra/bootstrapper at the root of your repository.
  2. Define the module in this folder. Refer to the module README for detailed instructions.

For more information, see the related blog post and the IAM Framework documentation.