Task 03: Configure Project Settings
DOCUMENT CATEGORY: Runbook Step
SCOPE: Source control project configuration
PURPOSE: Configure repository settings, branch protection, and merge/pull request approvals MASTER REFERENCE: Azure DevOps Project Settings
Status: Active
Objective
Configure required settings for the source control project. Most settings are replicated from the template, but must be verified. Select your platform below for platform-specific instructions.
Prerequisites
- Source control project created (Task 02)
- Admin / Maintainer role in the project
Procedure
Branch Protection
Protect the main branch to prevent direct pushes and require reviews before merging.
- GitHub
- GitLab
- Azure DevOps
- Navigate to Settings → Branches
- Click Add branch protection rule
- Set Branch name pattern to
main - Enable the following:
| Setting | Value |
|---|---|
| Require a pull request before merging | ✅ |
| Require approvals | ✅ (see Approval Rules below) |
| Dismiss stale pull request approvals when new commits are pushed | ✅ |
| Require status checks to pass before merging | ✅ |
| Require conversation resolution before merging | ✅ |
| Do not allow bypassing the above settings | ✅ |
| Restrict who can push to matching branches | ✅ (No direct pushes) |
| Allow force pushes | ❌ Disabled |
| Allow deletions | ❌ Disabled |
- Click Save changes
References: GitHub — Branch protection rules
- Navigate to Settings → Repository → Protected Branches
- Configure
main:
| Setting | Value |
|---|---|
| Allowed to merge | Developers + Maintainers |
| Allowed to push and merge | No one |
| Allowed to force push | ❌ Disabled |
| Code owner approval | ❌ Disabled |
References: GitLab — Protected branches
- Navigate to Repos → Branches
- Click the
...menu onmain→ Branch policies - Enable the following:
| Setting | Value |
|---|---|
| Require a minimum number of reviewers | ✅ (see Approval Rules below) |
| Check for linked work items | ✅ |
| Check for comment resolution | ✅ Required |
| Limit merge types | ✅ Squash merge only |
| Build validation | ✅ Add build policy for CI pipeline |
| Automatically included reviewers | Add required reviewer groups |
References: Azure DevOps — Branch policies
Push Rules / Security Settings
- GitHub
- GitLab
- Azure DevOps
GitHub handles push security via branch protection (configured above) and repository settings:
- Navigate to Settings → Code security and analysis
- Enable:
- ✅ Secret scanning — detect committed secrets
- ✅ Push protection — block pushes containing secrets
- Navigate to Settings → General → Pull Requests
- ✅ Allow squash merging (set default commit message)
- ❌ Disable merge commits and rebase merging (optional — enforce squash)
- Navigate to Settings → Repository → Push Rules
- Enable the following:
| Setting | Enabled |
|---|---|
| Reject unverified users | ✅ |
| Reject inconsistent user name | ✅ |
| Reject unsigned commits | ✅ |
| Do not allow users to remove Git tags with git push | ✅ |
| Check whether the commit author is a GitLab user | ✅ |
| Prevent pushing secret files | ✅ |
| Maximum file size (MB) | 1 |
- Navigate to Project Settings → Repositories → select your repo
- Under Policies, configure:
| Setting | Value |
|---|---|
| Commit author email validation | ✅ Enable pattern matching |
| File path validation | ✅ Block paths matching secret patterns |
| File size restriction | ✅ Max 1 MB |
| Reserved names restriction | ✅ |
- Under Security, set permissions for the
mainbranch:- Contributors: Deny Force push and Remove others' locks
Merge / Pull Request Approvals
- GitHub
- GitLab
- Azure DevOps
Configure required approvals in Settings → Branches → branch protection rule for main:
| Project Type | Required Approvals | Reviewers |
|---|---|---|
| Sandbox/Lab | 0 | — |
| Core repos | 3 | @AzureLocal/cicd team |
| Deployment repos | 2 | @AzureLocal/pcie team |
| All others | 2 | @AzureLocal/cicd team |
Optionally, add a CODEOWNERS file to the repository root to auto-assign reviewers:
# Default reviewers for all files
* @AzureLocal/cicd
References: GitHub — CODEOWNERS
- Navigate to Settings → Merge Requests → Merge request approvals
| Setting | Value |
|---|---|
| Merge method | Merge commit with semi-linear history |
| Squash commits | Require |
Merge options — enable only:
- ✅ Show link to create or view a merge request when pushing
- ✅ Enable "Delete source branch" option by default
Merge checks — enable only:
- ✅ Pipelines must succeed
- ✅ All threads must be resolved
- Add approval rule:
| Project Type | Required Approvals | Group |
|---|---|---|
| Sandbox/Lab | 0 | — |
| Core repos | 3 | CI/CD |
| All others | 2 | CI/CD |
- Click Add approval rule
- Rule name:
CI/CD - Target branch:
All protected branches - Required approvals: (per table above)
- Groups: Search and select the appropriate group
- Save changes
Configure in Repos → Branches → main branch policies:
- Minimum number of reviewers:
| Project Type | Required Approvals | Reviewer Group |
|---|---|---|
| Sandbox/Lab | 0 | — |
| Core repos | 3 | [Project]\CI-CD |
| Deployment repos | 2 | [Project]\PCIE |
| All others | 2 | [Project]\CI-CD |
-
Additional settings:
- ✅ Prohibit the most recent pusher from approving their own changes
- ✅ Reset code reviewer votes when there are new changes
- ✅ Allow requestors to approve their own changes: No
-
Automatically included reviewers — click Add automatic reviewers:
- Reviewers: Select the appropriate group
- For pull requests affecting these paths:
*(all paths) - Activity: Required
References: Azure DevOps — Branch policies
Verification
-
mainbranch protected — no direct pushes allowed - Push rules / security scanning configured
- Merge/PR approval rules added with correct reviewer counts
- Squash merge enforced (or preferred merge strategy set)
Next Steps
References
Variables from variables.yml
| Variable | Config Path | Example |
|---|---|---|
| Default Branch | cicd.project.default_branch | main |
| Branch Policy | cicd.project.branch_policy | require-pr |
| Pipeline Path | cicd.project.pipeline_path | /pipelines |
Scripts for this task are located in the azurelocal-toolkit repository under scripts/deploy/ in the appropriate task folder.
Alternatives
The procedures in this task use the scripted methods shown in the tabs above. Additional deployment methods including Azure CLI and Bash scripts are available in the azurelocal-toolkit repository under scripts/deploy/.
| Method | Description |
|---|---|
| Azure CLI | PowerShell-based Azure CLI scripts for Azure resource operations |
| Bash | Linux/macOS compatible shell scripts for pipeline environments |
Navigation
| Previous | Up | Next |
|---|---|---|
| ← Task 02: Create source control project | Phase 01: CI/CD Setup | Task 04: Create Environments -> |
Troubleshooting
| Issue | Cause | Resolution |
|---|---|---|
| Branch policies not applying | Insufficient project admin permissions | Verify user has Project Administrator role |
| Pipeline configuration fails | Invalid YAML syntax in pipeline definition | Validate YAML syntax using pipeline editor |
Version Control
| Version | Date | Author | Changes |
|---|---|---|---|
| 1.0.0 | 2025-03-25 | Azure Local Cloud | Initial release |