setup repository script - devonfw/hangar Wiki

Setting up a repository on Azure DevOps

By the end of this guide, a repository on Azure DevOps will be created in an automated way using a script.

Prerequisites

  • Have an Azure DevOps project already setup and Azure CLI installed and configured. If it is not the case, please go back to corresponding guide.

  • Install Git.

Creating repository using provided script

The script located at /scripts/repositories/azure-devops/create-repo.sh allows you to either:

  1. Create an empty repository with just a README file and clone it to your computer into the directory you set. Useful when starting a project from scratch.

  2. Import an already existing directory or Git repository into your project giving a path or an URL. Useful for taking to Azure DevOps the development of an existing project.

Usage

create-repo.sh \
    -a <action> \
    -d <local directory> \
    -o <organization> \
    -p <project> \
    [-n <repository name>] \
    [-g <giturl>] \
    [-b <branch>] \
    [-r] \
    [-s <branch strategy>] \
    [-f] \
    [--subpath <subpath to import>] \

Flags

-a, --action                [Required] Use case to fulfil: create, import.
-d, --directory             [Required] Path to the directory where your repository will be cloned or initialized.
-o, --org                   [Required] Name of the Azure DevOps organization.
-p, --project               [Required] Name of the Azure DevOps project.
-n, --name                             Name for the Azure DevOps repository. By default, the source repository or directory name (either new or existing, depending on use case) is used.
-g, --source-git-url                   Source URL of the Git repository to import.
-b, --source-branch                    Source branch to be used as a basis to initialize the repository on import, as master branch.
-r, --remove-other-branches            Removes branches other than the (possibly new) default one.
-s, --setup-branch-strategy            Creates branches and policies required for the desired workflow. Requires -b on import. Accepted values: gitflow.
-f, --force                            Skips any user confirmation.
    --subpath                          When combined with -g and -r, imports only the specified subpath of the source Git repository.

Typical use cases

Tip
This is non-exhaustive list. Make your own combination of flags if all of the following use cases does not fit your needs.

Creating an empty repository

./create-repo.sh -a create -o <organization> -p <project> -n <repository name> -d <local destination directory>

In case repository name is not specified, destination directory name will be used.

Creating an empty repository with Gitflow branching strategy

./create-repo.sh -a create -o <organization> -p <project> -n <repository name> -d <local destination directory> -s gitflow

Importing a remote Git repository

./create-repo.sh -a import -g <source git url> -o <organization> -p <project name> -n <repository name> -d <local destination directory>

In case repository name is not specified, source repository name (in URL) will be used.

Importing a specific remote Git repository branch as source for a new repository with Gitflow branching strategy

./create-repo.sh -a import -g <source git url> -b <source branch> -s gitflow -r -o <organization> -p <project name> -n <repository name> -d <local destination directory>

This will create master (and develop since a branching strategy is specified) from the <source branch>, removing any other branch (including <source branch>).

Importing local directory or Git repository

./create-repo.sh -a import -d <local source directory> -o <organization> -p <project name> -n <repository name>

In case repository name is not specified, source directory name will be used.

Importing a specific local Git repository branch as source for a new repository with Gitflow branching strategy

./create-repo.sh -a 'import' -d <local source directory> -b <source branch> -s gitflow -r -o <organization> -p <project name> -n <repository name>

This will create master (and develop since a branching strategy is specified) from the <source branch>, removing any other branch (including <source branch>).

Warning
This operation is destructive regarding branches on the local repository.
Note
Same command could also be used with a local directory, but then using -b and -r would be redundant.

Branching strategies

To ensure the quality of development, it is crucial to keep a clean Git workflow. The following branching strategies are supported (using -s flag):

Gitflow

This is not an explanation of Gitflow (there are plenty of them on the web), but the actions performed by the script to help you start using this worflow.

Branches

  • master is the initial (seed) branch.

  • develop branch is created from master branch.

Any other branch part the strategy (feature, release, and hotfix branches) will be created by developers during the lifecycle of the project.

Policies

In Azure DevOps it is possible to protect important branches against bad practices using branch policies.

The following branch policies are applied to master and develop branches:

  • Require a minimum number of reviewers: ON

    • Minimum number of reviewers: 1

    • Allow requestors to approve their own changes: ON

    • Prohibit the most recent pusher from approving their own changes: OFF

    • Allow completion even if some reviewers vote to wait or reject: OFF

    • When new changes are pushed: Reset all approval votes (does not reset votes to reject or wait)

  • Check for linked work items: OFF

  • Check for comment resolution: REQUIRED

  • Limit merge types: OFF

The above policies are defined in a configuration file located at /scripts/repositories/common/config/strategy.cfg. Feel free to adapt it to your needs.

Note
This is the bare minimum standard for any project. We do not prohibit the most recent pusher from approving their own changes, although being more than recommendable, because if we do, it will block the auto-approval of Pull Requests generated during pipelines creation on the following guides.

You can find more information about branch policies in the official documentation.

⚠️ **GitHub.com Fallback** ⚠️