How to set up a new GitLab repository¶
To start a new GitLab repository, go to the beautifulcanoe/projects page and click on the
New project button, near the top of the page.
Your project name and slug should be short and descriptive (just the name of the project is fine).
It is a good idea to add a short project description.
Your new project should be marked private and you should check the Initialize repository with a README box.
Next you should be taken to the project page.
At the top-right of the page you will see a button marked
Clone, use this to find the URL of the project, then you can checkout the repository on the command line, like this:
git clone firstname.lastname@example.org:beautifulcanoe/projects/<PROJECT-SLUG>.git
Set standard merge request settings¶
We use merge requests to ensure that all code and documentation in Beautiful Canoe is reviewed, to ensure that automatic tests are run over all our code and to reduce the likelihood of bugs being merged into
Each repository should be set up in a standard way, to ensure that our merge process is standardised throughout the company.
Settings->General->Merge requests and set your repository up like this:
Note that you should only check
Only allow merge requests to be merged if the pipeline succeeds if you have CI/CD pipelines set up.
Set default and protected branches¶
Next, we need to change some settings to ensure that we don't accidentally push to an important branch such as
master without going through a merge request.
Firstly, you need to create a branch called
On the command line, do this:
$ git branch # Just to check that we are on the right branch * master $ git checkout -b develop Switched to a new branch 'develop' $ git push origin develop Total 0 (delta 0), reused 0 (delta 0) remote: remote: To create a merge request for develop, visit: remote: https://gitlab.com/beautifulcanoe/projects/<PROJECT-SLUG>/merge_requests/new?merge_request%5Bsource_branch%5D=develop remote: To gitlab.com:beautifulcanoe/projects/<PROJECT-SLUG>.git * [new branch] develop -> develop
Now, go to
Settings->Repository in your project menu.
There are two settings we need to deal with here: default and protected branches.
At the top of the page, expand the
Default Branch section, select
develop and click on the
Save changes button.
Further down, expand the
Protected Branches section, and make
master selected branches, with only
Maintainers allowed to push or merge.
You should also add
release/* as a protected branch -- type
release/* into the text box and click on Create wildcard
release will be deployed on live servers, and are versioned (i.e.
release/1.1), so this will protect all the release branches.
Maintainers should be able to merge
release/* branches and push to them.
These branches are slightly different from
develop, which are created with the repository and never merged or deleted.
Instead, a new
release/* branch will be created periodically, so it must be possible to push a new branch.
When you are finished, the protected branch settings should look something like this:
Add standard documentation¶
Every repository should start with a standard set of documents and, which should be formatted in Markdown and committed to version control. In general, we should not use wikis for project documentation, and we should not duplicate information in these howtos -- but it is a good idea to link to them!
As a minimum, each repository should contain:
readme.md) which should be a document that can be understood by a non-developer, and should describe:
- what the project is intending to achieve,
- who the client is,
- who the (current and past) student developers are with their GitLab usernames,
- a link to the project Trello boards or other client-facing documentation, if there is any; and
- the URLs of the live and test deployments (if applicable).
contributing.md) which should be written specifically for developers, and should describe:
- which programming languages and frameworks are used in the project, with their major/minor version numbers (e.g. php5.6, php7.2),
- project dependencies only if these are not listed in
- how to set up a development environment for the project (e.g. will the developer need Homestead, Vagrant, phpbrew, etc.) -- this should include links to how-tos in this repository, rather than duplicating information here,
- how to set up any database that the project needs,
- how to set up a standard IDE (such as PhpStorm or IntelliJ) for the project,
- how to run the unit tests, and which test framework was used; and
- how to set up any Git hooks that the repository provides.
As usual, you should add this new documentation by creating an issue and raising a merge request.
Add a standard .gitignore file¶
.gitignore file should be placed in the root of the new repository, and checked into version control.
.gitignore tells Git which files in the repository should be ignored, to help developers avoid committing files that should not be in the repository (for example, backup files, auto-generated files, etc.).
The contents of
.gitignore will depend on the technology stack (an commonly used IDEs) for the project, but to begin with a standard file from gitignore.io should be used.
Now you have an initial repository, you can set up the rest of your workflow: