diff options
Diffstat (limited to 'doc/user/project/repository')
16 files changed, 197 insertions, 44 deletions
diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md index f94ca7ac106..54979d1c4ce 100644 --- a/doc/user/project/repository/branches/index.md +++ b/doc/user/project/repository/branches/index.md @@ -1,4 +1,7 @@ --- +stage: Create +group: Source Code +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" type: concepts, howto --- @@ -63,7 +66,7 @@ By default, when you create a new project in GitLab, the initial branch is calle For self-managed instances, a GitLab administrator can customize the initial branch name to something else. This way, every new project created from then on will start from the custom branch name rather than `master`. To do so: -1. Go to the **{admin}** **Admin Area > Settings > Repository** and expand **Default initial +1. Go to the **Admin Area > Settings > Repository** and expand **Default initial branch name**. 1. Change the default initial branch to a custom name of your choice. 1. **Save Changes**. diff --git a/doc/user/project/repository/file_finder.md b/doc/user/project/repository/file_finder.md index ac10071e578..99319efbb7f 100644 --- a/doc/user/project/repository/file_finder.md +++ b/doc/user/project/repository/file_finder.md @@ -1,4 +1,7 @@ --- +stage: Create +group: Editor +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers disqus_identifier: 'https://docs.gitlab.com/ee/workflow/file_finder.html' --- @@ -37,6 +40,7 @@ the `app/controllers/admin/deploy_keys_controller.rb` file. Using a fuzzy search, we start by typing letters that get us closer to the file. -**Tip:** To narrow down your search, include `/` in your search terms. +TIP: **Tip:** +To narrow down your search, include `/` in your search terms.  diff --git a/doc/user/project/repository/forking_workflow.md b/doc/user/project/repository/forking_workflow.md index 75a84e36169..e90f0a7354c 100644 --- a/doc/user/project/repository/forking_workflow.md +++ b/doc/user/project/repository/forking_workflow.md @@ -1,4 +1,7 @@ --- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers disqus_identifier: 'https://docs.gitlab.com/ee/workflow/forking_workflow.html' --- @@ -26,7 +29,7 @@ Forking a project is, in most cases, a two-step process. NOTE: **Note:** The project path must be unique within the namespace. -  +  The fork is created. The permissions you have in the namespace are the permissions you will have in the fork. @@ -50,7 +53,7 @@ Without mirroring, to work locally you'll have to use `git pull` to update your with the upstream project, then push the changes back to your fork to update it. CAUTION: **Caution:** -With mirroring, before approving a merge request, you'll likely be asked to sync; hence automating it is recommend. +With mirroring, before approving a merge request, you'll likely be asked to sync; hence automating it is recommended. Read more about [How to keep your fork up to date with its origin](https://about.gitlab.com/blog/2016/12/01/how-to-keep-your-fork-up-to-date-with-its-origin/). @@ -61,7 +64,7 @@ When you are ready to send your code back to the upstream project, choose your forked project's branch. For **Target branch**, choose the original project's branch. NOTE: **Note:** -When creating a merge request, if the forked project's visibility is more restrictive than the parent project (for example the fork is private, parent is public), the target branch will default to the forked project's default branch. This prevents potentially exposing private code of the forked project. +When creating a merge request, if the forked project's visibility is more restrictive than the parent project (for example the fork is private, the parent is public), the target branch will default to the forked project's default branch. This prevents potentially exposing the private code of the forked project.  diff --git a/doc/user/project/repository/git_blame.md b/doc/user/project/repository/git_blame.md index e63b57747ef..6636463722e 100644 --- a/doc/user/project/repository/git_blame.md +++ b/doc/user/project/repository/git_blame.md @@ -1,4 +1,7 @@ --- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference, howto description: "Documentation on Git file blame." --- diff --git a/doc/user/project/repository/git_history.md b/doc/user/project/repository/git_history.md index b7375602a78..6cc05d2192f 100644 --- a/doc/user/project/repository/git_history.md +++ b/doc/user/project/repository/git_history.md @@ -1,4 +1,7 @@ --- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference, howto description: "Documentation on Git file history." --- diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md index 68b5c2651e1..5526828c969 100644 --- a/doc/user/project/repository/gpg_signed_commits/index.md +++ b/doc/user/project/repository/gpg_signed_commits/index.md @@ -1,4 +1,7 @@ --- +stage: Create +group: Source Code +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" type: concepts, howto --- diff --git a/doc/user/project/repository/img/file_finder_find_button_v12_10.png b/doc/user/project/repository/img/file_finder_find_button_v12_10.png Binary files differindex e93db946005..51545f63fde 100644 --- a/doc/user/project/repository/img/file_finder_find_button_v12_10.png +++ b/doc/user/project/repository/img/file_finder_find_button_v12_10.png diff --git a/doc/user/project/repository/img/file_finder_find_file_v12_10.png b/doc/user/project/repository/img/file_finder_find_file_v12_10.png Binary files differindex 1404ccc6d0b..e54de6a3065 100644 --- a/doc/user/project/repository/img/file_finder_find_file_v12_10.png +++ b/doc/user/project/repository/img/file_finder_find_file_v12_10.png diff --git a/doc/user/project/repository/img/forking_workflow_choose_namespace.png b/doc/user/project/repository/img/forking_workflow_choose_namespace.png Binary files differdeleted file mode 100644 index eb023ca85f2..00000000000 --- a/doc/user/project/repository/img/forking_workflow_choose_namespace.png +++ /dev/null diff --git a/doc/user/project/repository/img/forking_workflow_choose_namespace_v13_2.png b/doc/user/project/repository/img/forking_workflow_choose_namespace_v13_2.png Binary files differnew file mode 100644 index 00000000000..4843cc671ae --- /dev/null +++ b/doc/user/project/repository/img/forking_workflow_choose_namespace_v13_2.png diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index 0cf375009a0..a57806cf3ff 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -1,4 +1,7 @@ --- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: concepts, howto --- diff --git a/doc/user/project/repository/jupyter_notebooks/index.md b/doc/user/project/repository/jupyter_notebooks/index.md index 1948b12aacd..fe432e0d553 100644 --- a/doc/user/project/repository/jupyter_notebooks/index.md +++ b/doc/user/project/repository/jupyter_notebooks/index.md @@ -1,3 +1,9 @@ +--- +stage: Create +group: Source Code +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" +type: reference +--- # Jupyter Notebook Files > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/2508/) in GitLab 9.1. diff --git a/doc/user/project/repository/reducing_the_repo_size_using_git.md b/doc/user/project/repository/reducing_the_repo_size_using_git.md index baad5027703..8247f69c61a 100644 --- a/doc/user/project/repository/reducing_the_repo_size_using_git.md +++ b/doc/user/project/repository/reducing_the_repo_size_using_git.md @@ -32,15 +32,24 @@ Git LFS files can only be removed by an Administrator using a ## Purge files from repository history -To make cloning your project faster, rewrite branches and tags to remove unwanted files. +To reduce the size of your repository in GitLab, you must remove references to large files from branches, tags, and +other internal references (refs) that are automatically created by GitLab. These refs include: + +- `refs/merge-requests/*` for merge requests. +- `refs/pipelines/*` for + [pipelines](../../../ci/pipelines/index.md#troubleshooting-fatal-reference-is-not-a-tree). +- `refs/environments/*` for environments. + +Git doesn't usually download these refs to make cloning and fetch faster, but we can use the `--mirror` option to +download all the advertised refs. 1. [Install `git filter-repo`](https://github.com/newren/git-filter-repo/blob/main/INSTALL.md) using a supported package manager or from source. -1. Clone a fresh copy of the repository using `--bare`: +1. Clone a fresh copy of the repository using `--bare` and `--mirror`: ```shell - git clone --bare https://example.gitlab.com/my/project.git + git clone --bare --mirror https://example.gitlab.com/my/project.git ``` 1. Using `git filter-repo`, purge any files from the history of your repository. @@ -74,16 +83,10 @@ To make cloning your project faster, rewrite branches and tags to remove unwante [`git filter-repo` documentation](https://htmlpreview.github.io/?https://github.com/newren/git-filter-repo/blob/docs/html/git-filter-repo.html#EXAMPLES) for more examples and the complete documentation. -1. Running `git filter-repo` removes all remotes. To restore the remote for your project, run: - - ```shell - git remote add origin https://example.gitlab.com/<namespace>/<project_name>.git - ``` - 1. Force push your changes to overwrite all branches on GitLab: ```shell - git push origin --force --all + git push origin --force 'refs/heads/*' ``` [Protected branches](../protected_branches.md) will cause this to fail. To proceed, you must @@ -92,13 +95,21 @@ To make cloning your project faster, rewrite branches and tags to remove unwante 1. To remove large files from tagged releases, force push your changes to all tags on GitLab: ```shell - git push origin --force --tags + git push origin --force 'refs/tags/*' ``` [Protected tags](../protected_tags.md) will cause this to fail. To proceed, you must remove tag protection, push, and then re-enable protected tags. -1. Manually run [project housekeeping](../../../administration/housekeeping.md#manual-housekeeping) +1. To prevent dead links to commits that no longer exist, push the `refs/replace` created by `git filter-repo`. + + ```shell + git push origin --force 'refs/replace/*' + ``` + + Refer to the Git [`replace`](https://git-scm.com/book/en/v2/Git-Tools-Replace) documentation for information on how this works. + +1. Run a [repository cleanup](#repository-cleanup). NOTE: **Note:** Project statistics are cached for performance. You may need to wait 5-10 minutes @@ -106,26 +117,9 @@ to see a reduction in storage utilization. ## Purge files from GitLab storage -To reduce the size of your repository in GitLab, you must remove GitLab internal references to -commits that contain large files. Before completing these steps, -[purge files from your repository history](#purge-files-from-repository-history). +In addition to the refs mentioned above, GitLab also creates hidden `refs/keep-around/*`to prevent commits being deleted. Hidden refs are not advertised, which means we can't download them using Git, but these refs are included in a project export. -As well as [branches](branches/index.md) and tags, which are a type of Git ref, GitLab automatically -creates other refs. These refs prevent dead links to commits, or missing diffs when viewing merge -requests. [Repository cleanup](#repository-cleanup) can be used to remove these from GitLab. - -The following internal refs are not advertised: - -- `refs/merge-requests/*` for merge requests. -- `refs/pipelines/*` for - [pipelines](../../../ci/pipelines/index.md#troubleshooting-fatal-reference-is-not-a-tree). -- `refs/environments/*` for environments. - -This means they are not usually included when fetching, which makes fetching faster. In addition, -`refs/keep-around/*` are hidden refs to prevent commits with discussion from being deleted and -cannot be fetched at all. - -However, these refs can be accessed from the Git bundle inside a project export. +To purge files from GitLab storage: 1. [Install `git filter-repo`](https://github.com/newren/git-filter-repo/blob/main/INSTALL.md) using a supported package manager or from source. @@ -173,6 +167,39 @@ However, these refs can be accessed from the Git bundle inside a project export. [`git filter-repo` documentation](https://htmlpreview.github.io/?https://github.com/newren/git-filter-repo/blob/docs/html/git-filter-repo.html#EXAMPLES) for more examples and the complete documentation. +1. Because cloning from a bundle file sets the `origin` remote to the local bundle file, delete this `origin` remote, and set it to the URL to your repository: + + ```shell + git remote remove origin + git remote add origin https://gitlab.example.com/<namespace>/<project_name>.git + ``` + +1. Force push your changes to overwrite all branches on GitLab: + + ```shell + git push origin --force 'refs/heads/*' + ``` + + [Protected branches](../protected_branches.md) will cause this to fail. To proceed, you must + remove branch protection, push, and then re-enable protected branches. + +1. To remove large files from tagged releases, force push your changes to all tags on GitLab: + + ```shell + git push origin --force 'refs/tags/*' + ``` + + [Protected tags](../protected_tags.md) will cause this to fail. To proceed, you must remove tag + protection, push, and then re-enable protected tags. + +1. To prevent dead links to commits that no longer exist, push the `refs/replace` created by `git filter-repo`. + + ```shell + git push origin --force 'refs/replace/*' + ``` + + Refer to the Git [`replace`](https://git-scm.com/book/en/v2/Git-Tools-Replace) documentation for information on how this works. + 1. Run a [repository cleanup](#repository-cleanup). ## Repository cleanup @@ -187,16 +214,27 @@ references to these objects. You can use To clean up a repository: 1. Go to the project for the repository. -1. Navigate to **{settings}** **Settings > Repository**. -1. Upload a list of objects. For example, a `commit-map` file. +1. Navigate to **Settings > Repository**. +1. Upload a list of objects. For example, a `commit-map` file created by `git filter-repo` which is located in the + `filter-repo` directory. + + If your `commit-map` file is larger than 10MB, the file can be split and uploaded piece by piece: + + ```shell + split -l 100000 filter-repo/commit-map filter-repo/commit-map- + ``` + 1. Click **Start cleanup**. This will: - Remove any internal Git references to old commits. -- Run `git gc` against the repository. +- Run `git gc` against the repository to remove unreferenced objects. Repacking your repository will temporarily + cause the size of your repository to increase significantly, because the old pack files are not removed until the + new pack files have been created. +- Recalculate the size of your repository on disk. -You will receive an email once it has completed. +You will receive an email notification with the recalculated repository size after the cleanup has completed. When using repository cleanup, note: diff --git a/doc/user/project/repository/repository_mirroring.md b/doc/user/project/repository/repository_mirroring.md index bdf13100a6a..bbb673b74b0 100644 --- a/doc/user/project/repository/repository_mirroring.md +++ b/doc/user/project/repository/repository_mirroring.md @@ -1,4 +1,7 @@ --- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers disqus_identifier: 'https://docs.gitlab.com/ee/workflow/repository_mirroring.html' --- @@ -114,14 +117,92 @@ After the mirror is created, this option can currently only be modified via the To set up a mirror from GitLab to GitHub, you need to follow these steps: -1. Create a [GitHub personal access token](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) with the `public_repo` box checked. +1. Create a [GitHub personal access token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) with the `public_repo` box checked. 1. Fill in the **Git repository URL** field using this format: `https://<your_github_username>@github.com/<your_github_group>/<your_github_project>.git`. 1. Fill in **Password** field with your GitHub personal access token. 1. Click the **Mirror repository** button. The mirrored repository will be listed. For example, `https://*****:*****@github.com/<your_github_group>/<your_github_project>.git`. -The repository will push soon. To force a push, click the appropriate button. +The repository will push soon. To force a push, click the **Update now** (**{retry}**) button. + +## Setting up a push mirror from GitLab to AWS CodeCommit + +AWS CodeCommit push mirroring is currently the best way to connect GitLab repositories to AWS CodePipeline, as GitLab is not yet supported as one of their Source Code Management (SCM) providers. + +Each new AWS Codepipeline needs significant AWS infrastructure setup. It also requires an individual pipeline per branch. + +If AWS CodeDeploy is the final step of a CodePipeline, you can, instead, leverage GitLab CI/CD pipelines and simply use the AWS CLI in the final job in `.gitlab-ci.yml` to deploy to CodeDeploy. + +NOTE: **Note:** +GitLab-to-AWS-CodeCommit push mirroring cannot use SSH authentication until [GitLab issue 34014](https://gitlab.com/gitlab-org/gitlab/-/issues/34014) is resolved. + +To set up a mirror from GitLab to AWS CodeCommit: + +1. In the AWS IAM console, create an IAM user. +1. Add the following least privileges permissions for repository mirroring as an "inline policy". + + The Amazon Resource Names (ARNs) must explicitly include the region and account. The IAM policy + below grants privilege for mirroring access to two sample repositories. These permissions have + been tested to be the minimum (least privileged) required for mirroring: + + ```json + { + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "MinimumGitLabPushMirroringPermissions", + "Effect": "Allow", + "Action": [ + "codecommit:GitPull", + "codecommit:GitPush" + ], + "Resource": [ + "arn:aws:codecommit:us-east-1:111111111111:MyDestinationRepo", + "arn:aws:codecommit:us-east-1:111111111111:MyDemo*" + ] + } + ] + } + ``` + +1. After the user was created, click the AWS IAM user name. +1. Click the **Security credentials** tab. +1. Under **HTTPS Git credentials for AWS CodeCommit** click **Generate credentials**. + + NOTE: **Note:** + This Git user ID and password is specific to communicating with CodeCommit. Do + not confuse it with the IAM user ID or AWS keys of this user. + +1. Copy or download special Git HTTPS user ID and password. +1. In the AWS CodeCommit console, create a new repository to mirror from your GitLab repo. +1. Open your new repository and click **Clone URL > Clone HTTPS** (not **Clone HTTPS (GRC)**). +1. In GitLab, open the repository to be push-mirrored. +1. Click **Settings > Repository** and expand **Mirroring repositories**. +1. Fill in the **Git repository URL** field using this format: + + ```plaintext + https://<your_aws_git_userid>@git-codecommit.<aws-region>.amazonaws.com/v1/repos/<your_codecommit_repo> + ``` + + Replace `<your_aws_git_userid>` with the AWS **special HTTPS Git user ID** from the IAM Git + credentials created earlier. Replace `<your_codecommit_repo>` with the name of your repo in CodeCommit. + +1. For **Mirror direction**, select **Push**. +1. For **Authentication method**, select **Password** and fill in the **Password** field with the special IAM Git clone user ID **password** created earlier in AWS. +1. The option **Only mirror protected branches** should be good for CodeCommit as it pushes more + frequently (from every five minutes to every minute). + CodePipeline requires individual pipeline setups for named branches you wish to have a AWS CI setup for. Since feature branches that have dynamic names will not be supported anyway, configuring **Only mirror protected branches** does not cause flexibility problems with CodePipeline integration as long as you are also willing to protect all the named branches you want to build CodePipelines for. + +1. Click **Mirror repository**. You should see the mirrored repository appear: + + ```plaintext + https://*****:*****@git-codecommit.<aws-region>.amazonaws.com/v1/repos/<your_codecommit_repo> + ``` + +To test mirroring by forcing a push, click the half-circle arrows button (hover text is **Update now**). +If **Last successful update** shows a date, you have configured mirroring correctly. +If it is not working correctly a red `error` tag appears and shows the error message as hover text. ## Setting up a push mirror to another GitLab instance with 2FA activated @@ -232,7 +313,7 @@ fingerprints in the open for you to check: - [AWS CodeCommit](https://docs.aws.amazon.com/codecommit/latest/userguide/regions.html#regions-fingerprints) - [Bitbucket](https://support.atlassian.com/bitbucket-cloud/docs/configure-ssh-and-two-step-verification/) -- [GitHub](https://help.github.com/en/github/authenticating-to-github/githubs-ssh-key-fingerprints) +- [GitHub](https://docs.github.com/en/github/authenticating-to-github/githubs-ssh-key-fingerprints) - [GitLab.com](../../gitlab_com/index.md#ssh-host-keys-fingerprints) - [Launchpad](https://help.launchpad.net/SSHFingerprints) - [Savannah](http://savannah.gnu.org/maintenance/SshAccess/) diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index 59fedacb2ca..452955b327c 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -1,4 +1,7 @@ --- +stage: Create +group: Editor +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: howto --- @@ -46,7 +49,7 @@ has already been created, which creates a link to the license itself.  ->**Note:** +NOTE: **Note:** The **Set up CI/CD** button will not appear on an empty repository. You have to at least add a file in order for the button to show up. diff --git a/doc/user/project/repository/x509_signed_commits/index.md b/doc/user/project/repository/x509_signed_commits/index.md index ffbad4e0989..972a46ee7a3 100644 --- a/doc/user/project/repository/x509_signed_commits/index.md +++ b/doc/user/project/repository/x509_signed_commits/index.md @@ -1,4 +1,7 @@ --- +stage: Create +group: Source Code +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" type: concepts, howto --- |
