> For the complete documentation index, see [llms.txt](https://engine.sygnal.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://engine.sygnal.com/devproxy/configurations/controlling-deployment-flow.md).

# Controlling deployment flow

You can use features like Github's branch protections;

<https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches>

## Example Config

To ensure that development occurs only on the `dev` branch and to protect against accidental edits and pushes to the `test` and `main` branches, you can use GitHub's branch protection rules and enforce a pull request-based workflow. Here's how you can set it up:

#### Step-by-Step Guide

1. **Create and Push Branches**:
   * Make sure you have `dev`, `test`, and `main` branches pushed to your GitHub repository.
2. **Set Up Branch Protection Rules**:
   * Go to your GitHub repository.
   * Navigate to **Settings** > **Branches**.
   * Under **Branch protection rules**, click **Add rule**.
3. **Protect the `test` Branch**:
   * Under **Branch name pattern**, enter `test`.
   * Check the following options:
     * **Require pull request reviews before merging**: This ensures that all changes must be reviewed before being merged.
     * **Require status checks to pass before merging**: Ensure that all CI checks pass before allowing a merge.
     * **Include administrators**: Apply these rules to administrators as well.
     * **Restrict who can push to matching branches**: Select specific people or teams who can push to the `test` branch directly. Typically, you'd restrict this to maintainers or a CI/CD system.
   * Click **Create** or **Save changes**.
4. **Protect the `main` Branch**:
   * Repeat the same steps for the `main` branch.
5. **Workflow for Merging Branches**:
   * Ensure that merges from `dev` to `test` and `test` to `main` are done through pull requests (PRs).

#### Detailed Steps in GitHub

1. **Navigate to Branch Protection Rules**:
   * Go to your repository's **Settings**.
   * Click on **Branches** in the left sidebar.
   * Click on **Add rule**.
2. **Set Up Protection for `test`**:
   * Enter `test` in the **Branch name pattern** field.
   * Select the following protection settings:
     * **Require pull request reviews before merging**: Set the number of required reviewers.
     * **Require status checks to pass before merging**: Select the status checks that must pass before merging.
     * **Restrict who can push to matching branches**: Add the specific users or teams allowed to push directly (if any).
   * Click **Create** or **Save changes**.
3. **Set Up Protection for `main`**:
   * Enter `main` in the **Branch name pattern** field.
   * Select the same protection settings as for `test`.

#### Example of Branch Protection Rule

Here's an example of what the settings might look like for the `test` branch:

* **Branch name pattern**: `test`
* **Require pull request reviews before merging**:
  * [x] Require pull request reviews before merging
  * [x] Dismiss stale pull request approvals when new commits are pushed
  * [x] Require review from Code Owners (if applicable)
  * [ ] Number of required reviewers: 1 (or more, depending on your team's workflow)
* **Require status checks to pass before merging**:
  * [x] Require status checks to pass before merging
  * [x] Require branches to be up to date before merging
  * [ ] Select the specific checks that need to pass (e.g., `build`, `test`)
* **Restrict who can push to matching branches**:
  * [x] Restrict who can push to matching branches
  * [ ] Add specific teams or users who are allowed to push directly (typically, this might be a CI/CD system or a very limited number of maintainers)
* **Include administrators**: \[x]

#### Workflow Enforcement

1. **Development in `dev`**:
   * All development work is done in the `dev` branch.
   * Developers commit and push changes to `dev`.
2. **Merging to `test`**:
   * Create a pull request to merge changes from `dev` to `test`.
   * Ensure all reviewers approve the PR and all status checks pass.
   * Merge the PR to `test`.
3. **Merging to `main`**:
   * Create a pull request to merge changes from `test` to `main`.
   * Ensure all reviewers approve the PR and all status checks pass.
   * Merge the PR to `main`.

By following these steps, you can ensure that your `test` and `main` branches are protected from direct commits and that all changes go through a review and testing process before being merged. This setup enforces a disciplined workflow and helps maintain the stability of your codebase.