diff options
Diffstat (limited to 'doc/user/project/pages/getting_started')
7 files changed, 547 insertions, 130 deletions
diff --git a/doc/user/project/pages/getting_started/fork_sample_project.md b/doc/user/project/pages/getting_started/fork_sample_project.md index de9bd97b262..250e90f0302 100644 --- a/doc/user/project/pages/getting_started/fork_sample_project.md +++ b/doc/user/project/pages/getting_started/fork_sample_project.md @@ -1,56 +1,5 @@ --- -type: reference, howto -stage: Release -group: Release Management -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 +redirect_to: 'pages_forked_sample_project.md' --- -# Create a Pages website from a forked sample - -GitLab provides [sample projects for the most popular Static Site Generators](https://gitlab.com/pages). -You can fork one of the sample projects and run the CI/CD pipeline to generate a Pages website. - -Fork a sample project when you want to test GitLab Pages or start a new project that's already -configured to generate a Pages site. - -<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a [video tutorial](https://www.youtube.com/watch?v=TWqh9MtT4Bg) of how this works. - -To fork a sample project and create a Pages website: - -1. View the sample projects by going to the [GitLab Pages examples](https://gitlab.com/pages) group. -1. Click the name of the project you want to [fork](../../../../gitlab-basics/fork-project.md). -1. In the top right, click the **Fork** button, and then choose a namespace to fork to. -1. Go to your project's **CI/CD > Pipelines** and click **Run pipeline**. - GitLab CI/CD builds and deploys your site. - -The site can take approximately 30 minutes to deploy. -When the pipeline is finished, go to **Settings > Pages** to find the link to your website from your project. - -For every change pushed to your repository, GitLab CI/CD runs a new pipeline -that immediately publishes your changes to the Pages site. - -You can take some **optional** further steps: - -- _Remove the fork relationship._ If you want to contribute to the project you forked from, - you can keep this relationship. Otherwise, go to your project's **Settings > General**, - expand **Advanced settings**, and scroll down to **Remove fork relationship**: - -  - -- _Change the URL to match your namespace._ If your Pages site is hosted on GitLab.com, - you can rename it to `<namespace>.gitlab.io`, where `<namespace>` is your GitLab namespace - (the one you chose when you forked the project). - - - Go to your project's **Settings > General** and expand **Advanced**. Scroll down to - **Change path** and change the path to `<namespace>.gitlab.io`. - - For example, if your project's URL is `gitlab.com/gitlab-tests/jekyll`, your namespace is - `gitlab-tests`. - - If you set the repository path to `gitlab-tests.gitlab.io`, - the resulting URL for your Pages website is `https://gitlab-tests.gitlab.io`. - -  - - - Now go to your SSG's configuration file and change the [base URL](../getting_started_part_one.md#urls-and-baseurls) - from `"project-name"` to `""`. The project name setting varies by SSG and may not be in the config file. +This document was moved to [pages_forked_sample_project.md](pages_forked_sample_project.md). diff --git a/doc/user/project/pages/getting_started/new_or_existing_website.md b/doc/user/project/pages/getting_started/new_or_existing_website.md index 5d7126ab22e..86f36447b93 100644 --- a/doc/user/project/pages/getting_started/new_or_existing_website.md +++ b/doc/user/project/pages/getting_started/new_or_existing_website.md @@ -1,49 +1,5 @@ --- -type: reference, howto -stage: Release -group: Release Management -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 +redirect_to: 'pages_ci_cd_template.md' --- -# Create a Pages website by using a CI/CD template - -GitLab provides `.gitlab-ci.yml` templates for the most popular Static Site Generators (SSGs). -You can create your own `.gitlab-ci.yml` file from one of these templates, and run -the CI/CD pipeline to generate a Pages website. - -Use a `.gitlab-ci.yml` template when you have an existing project that you want to add a Pages site to. - -Your GitLab repository should contain files specific to an SSG, or plain HTML. -After you complete these steps, you may need to do additional -configuration for the Pages site to generate properly. - -1. In the left sidebar, click **Project overview**. -1. Click **Set up CI/CD**. - -  - - If this button is not available, CI/CD is already configured for - your project. You may want to browse the `.gitlab-ci.yml` files - [in these projects instead](https://gitlab.com/pages). - -1. From the **Apply a template** list, choose a template for the SSG you're using. - You can also choose plain HTML. - -  - - If you don't find a corresponding template, you can view the - [GitLab Pages group of sample projects](https://gitlab.com/pages). - These projects contain `.gitlab-ci.yml` files that you can modify for your needs. - You can also [learn how to write your own `.gitlab-ci.yml` - file for GitLab Pages](../getting_started_part_four.md). - -1. Save and commit the `.gitlab-ci.yml` file. - -If everything is configured correctly, the site can take approximately 30 minutes to deploy. - -You can watch the pipeline run by going to **CI / CD > Pipelines**. -When the pipeline is finished, go to **Settings > Pages** to find the link to -your Pages website. - -For every change pushed to your repository, GitLab CI/CD runs a new pipeline -that immediately publishes your changes to the Pages site. +This document was moved to [pages_ci_cd_template.md](pages_ci_cd_template.md). diff --git a/doc/user/project/pages/getting_started/pages_bundled_template.md b/doc/user/project/pages/getting_started/pages_bundled_template.md index cfa4e0910db..bc706105606 100644 --- a/doc/user/project/pages/getting_started/pages_bundled_template.md +++ b/doc/user/project/pages/getting_started/pages_bundled_template.md @@ -1,34 +1,5 @@ --- -type: reference, howto -stage: Release -group: Release Management -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 +redirect_to: 'pages_new_project_template.md' --- -# Create a Pages website from a new project template - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/47857) in GitLab 11.8. - -GitLab provides templates for the most popular Static Site Generators (SSGs). -You can create a new project from a template and run the CI/CD pipeline to generate a Pages website. - -Use a template when you want to test GitLab Pages or start a new project that's already -configured to generate a Pages site. - -1. From the top navigation, click the **+** button and select **New project**. -1. Select **Create from Template**. -1. Next to one of the templates starting with **Pages**, click **Use template**. - -  - -1. Complete the form and click **Create project**. -1. From the left sidebar, navigate to your project's **CI/CD > Pipelines** - and click **Run pipeline** to trigger GitLab CI/CD to build and deploy your - site. - -The site can take approximately 30 minutes to deploy. -When the pipeline is finished, go to **Settings > Pages** to find the link to -your Pages website. - -For every change pushed to your repository, GitLab CI/CD runs a new pipeline -that immediately publishes your changes to the Pages site. +This document was moved to [pages_new_project_template.md](pages_new_project_template.md). diff --git a/doc/user/project/pages/getting_started/pages_ci_cd_template.md b/doc/user/project/pages/getting_started/pages_ci_cd_template.md new file mode 100644 index 00000000000..906ffe43285 --- /dev/null +++ b/doc/user/project/pages/getting_started/pages_ci_cd_template.md @@ -0,0 +1,49 @@ +--- +type: reference, howto +stage: Release +group: Release Management +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 +--- + +# Create a Pages website by using a CI/CD template + +GitLab provides `.gitlab-ci.yml` templates for the most popular Static Site Generators (SSGs). +You can create your own `.gitlab-ci.yml` file from one of these templates, and run +the CI/CD pipeline to generate a Pages website. + +Use a `.gitlab-ci.yml` template when you have an existing project that you want to add a Pages site to. + +Your GitLab repository should contain files specific to an SSG, or plain HTML. +After you complete these steps, you may need to do additional +configuration for the Pages site to generate properly. + +1. In the left sidebar, click **Project overview**. +1. Click **Set up CI/CD**. + +  + + If this button is not available, CI/CD is already configured for + your project. You may want to browse the `.gitlab-ci.yml` files + [in these projects instead](https://gitlab.com/pages). + +1. From the **Apply a template** list, choose a template for the SSG you're using. + You can also choose plain HTML. + +  + + If you don't find a corresponding template, you can view the + [GitLab Pages group of sample projects](https://gitlab.com/pages). + These projects contain `.gitlab-ci.yml` files that you can modify for your needs. + You can also [learn how to write your own `.gitlab-ci.yml` + file for GitLab Pages](pages_from_scratch.md). + +1. Save and commit the `.gitlab-ci.yml` file. + +If everything is configured correctly, the site can take approximately 30 minutes to deploy. + +You can watch the pipeline run by going to **CI / CD > Pipelines**. +When the pipeline is finished, go to **Settings > Pages** to find the link to +your Pages website. + +For every change pushed to your repository, GitLab CI/CD runs a new pipeline +that immediately publishes your changes to the Pages site. diff --git a/doc/user/project/pages/getting_started/pages_forked_sample_project.md b/doc/user/project/pages/getting_started/pages_forked_sample_project.md new file mode 100644 index 00000000000..de9bd97b262 --- /dev/null +++ b/doc/user/project/pages/getting_started/pages_forked_sample_project.md @@ -0,0 +1,56 @@ +--- +type: reference, howto +stage: Release +group: Release Management +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 +--- + +# Create a Pages website from a forked sample + +GitLab provides [sample projects for the most popular Static Site Generators](https://gitlab.com/pages). +You can fork one of the sample projects and run the CI/CD pipeline to generate a Pages website. + +Fork a sample project when you want to test GitLab Pages or start a new project that's already +configured to generate a Pages site. + +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a [video tutorial](https://www.youtube.com/watch?v=TWqh9MtT4Bg) of how this works. + +To fork a sample project and create a Pages website: + +1. View the sample projects by going to the [GitLab Pages examples](https://gitlab.com/pages) group. +1. Click the name of the project you want to [fork](../../../../gitlab-basics/fork-project.md). +1. In the top right, click the **Fork** button, and then choose a namespace to fork to. +1. Go to your project's **CI/CD > Pipelines** and click **Run pipeline**. + GitLab CI/CD builds and deploys your site. + +The site can take approximately 30 minutes to deploy. +When the pipeline is finished, go to **Settings > Pages** to find the link to your website from your project. + +For every change pushed to your repository, GitLab CI/CD runs a new pipeline +that immediately publishes your changes to the Pages site. + +You can take some **optional** further steps: + +- _Remove the fork relationship._ If you want to contribute to the project you forked from, + you can keep this relationship. Otherwise, go to your project's **Settings > General**, + expand **Advanced settings**, and scroll down to **Remove fork relationship**: + +  + +- _Change the URL to match your namespace._ If your Pages site is hosted on GitLab.com, + you can rename it to `<namespace>.gitlab.io`, where `<namespace>` is your GitLab namespace + (the one you chose when you forked the project). + + - Go to your project's **Settings > General** and expand **Advanced**. Scroll down to + **Change path** and change the path to `<namespace>.gitlab.io`. + + For example, if your project's URL is `gitlab.com/gitlab-tests/jekyll`, your namespace is + `gitlab-tests`. + + If you set the repository path to `gitlab-tests.gitlab.io`, + the resulting URL for your Pages website is `https://gitlab-tests.gitlab.io`. + +  + + - Now go to your SSG's configuration file and change the [base URL](../getting_started_part_one.md#urls-and-baseurls) + from `"project-name"` to `""`. The project name setting varies by SSG and may not be in the config file. diff --git a/doc/user/project/pages/getting_started/pages_from_scratch.md b/doc/user/project/pages/getting_started/pages_from_scratch.md new file mode 100644 index 00000000000..7278c734b07 --- /dev/null +++ b/doc/user/project/pages/getting_started/pages_from_scratch.md @@ -0,0 +1,402 @@ +--- +last_updated: 2020-01-06 +type: reference, howto +stage: Release +group: Release Management +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 +--- + +# Create a GitLab Pages website from scratch + +This tutorial shows you how to create a Pages site from scratch. You will start with +a blank project and create your own CI file, which gives instruction to the +[GitLab Runner](https://docs.gitlab.com/runner/). When your CI/CD +[pipeline](../../../../ci/pipelines/index.md) runs, the Pages site is created. + +This example uses the [Jekyll](https://jekyllrb.com/) Static Site Generator (SSG). +Other SSGs follow similar steps. You do not need to be familiar with Jekyll or SSGs +to complete this tutorial. + +## Prerequisites + +To follow along with this example, start with a blank project in GitLab. +Create three files in the root (top-level) directory. + +- `.gitlab-ci.yml` A YAML file that contains the commands you want to run. + For now, leave the file's contents blank. + +- `index.html` An HTML file you can populate with whatever HTML content you'd like, + for example: + + ```html + <html> + <head> + <title>Home</title> + </head> + <body> + <h1>Hello World!</h1> + </body> + </html> + ``` + +- [`Gemfile`](https://bundler.io/gemfile.html) A file that describes dependencies for Ruby programs. + Populate it with this content: + + ```ruby + source "https://rubygems.org" + + gem "jekyll" + ``` + +## Choose a Docker image + +In this example, the Runner uses a [Docker image](../../../../ci/docker/using_docker_images.md) +to run scripts and deploy the site. + +This specific Ruby image is maintained on [DockerHub](https://hub.docker.com/_/ruby). + +Edit your `.gitlab-ci.yml` and add this text as the first line. + +```yaml +image: ruby:2.7 +``` + +If your SSG needs [NodeJS](https://nodejs.org/) to build, you must specify an +image that contains NodeJS as part of its file system. For example, for a +[Hexo](https://gitlab.com/pages/hexo) site, you can use `image: node:12.17.0`. + +## Install Jekyll + +To run [Jekyll](https://jekyllrb.com/) locally, you would open your terminal and: + +- Install [Bundler](https://bundler.io/) by running `gem install bundler`. +- Create `Gemfile.lock` by running `bundle install`. +- Install Jekyll by running `bundle exec jekyll build`. + +In the `.gitlab-ci.yml` file, this is written as: + +```yaml +script: + - gem install bundler + - bundle install + - bundle exec jekyll build +``` + +In addition, in the `.gitlab-ci.yml` file, each `script` is organized by a `job`. +A `job` includes the scripts and settings you want to apply to that specific +task. + +```yaml +job: + script: + - gem install bundler + - bundle install + - bundle exec jekyll build +``` + +For GitLab Pages, this `job` has a specific name, called `pages`. +This setting tells the Runner you want the job to deploy your website +with GitLab Pages: + +```yaml +pages: + script: + - gem install bundler + - bundle install + - bundle exec jekyll build +``` + +## Specify the `public` directory for output + +Jekyll needs to know where to generate its output. +GitLab Pages only considers files in a directory called `public`. + +Jekyll uses destination (`-d`) to specify an output directory for the built website: + +```yaml +pages: + script: + - gem install bundler + - bundle install + - bundle exec jekyll build -d public +``` + +## Specify the `public` directory for artifacts + +Now that Jekyll has output the files to the `public` directory, +the Runner needs to know where to get them. The artifacts are stored +in the `public` directory: + +```yaml +pages: + script: + - gem install bundler + - bundle install + - bundle exec jekyll build -d public + artifacts: + paths: + - public +``` + +Paste this into `.gitlab-ci.yml` file, so it now looks like this: + +```yaml +image: ruby:2.7 + +pages: + script: + - gem install bundler + - bundle install + - bundle exec jekyll build -d public + artifacts: + paths: + - public +``` + +Now save and commit the `.gitlab-ci.yml` file. You can watch the pipeline run +by going to **CI / CD > Pipelines**. + +When it succeeds, go to **Settings > Pages** to view the URL where your site +is now available. + +If you want to do more advanced tasks, you can update your `.gitlab-ci.yml` file +with [any of the available settings](../../../../ci/yaml/README.md). You can check +your CI syntax with the [GitLab CI/CD Lint Tool](../../../../ci/yaml/README.md#validate-the-gitlab-ciyml). + +The following topics show other examples of other options you can add to your CI/CD file. + +## Deploy specific branches to a Pages site + +You may want to deploy to a Pages site only from specific branches. + +First, add a `workflow` section to force the pipeline to run only when changes are +pushed to branches: + +```yaml +image: ruby:2.7 + +workflow: + rules: + - if: '$CI_COMMIT_BRANCH' + +pages: + script: + - gem install bundler + - bundle install + - bundle exec jekyll build -d public + artifacts: + paths: + - public +``` + +Then configure the pipeline to run the job for the master branch only. + +```yaml +image: ruby:2.7 + +workflow: + rules: + - if: '$CI_COMMIT_BRANCH' + +pages: + script: + - gem install bundler + - bundle install + - bundle exec jekyll build -d public + artifacts: + paths: + - public + rules: + - if: '$CI_COMMIT_BRANCH == "master"' +``` + +## Specify a stage to deploy + +There are three default stages for GitLab CI/CD: build, test, +and deploy. + +If you want to test your script and check the built site before deploying +to production, you can run the test exactly as it will run when you +push to `master`. + +To specify a stage for your job to run in, +add a `stage` line to your CI file: + +```yaml +image: ruby:2.7 + +workflow: + rules: + - if: '$CI_COMMIT_BRANCH' + +pages: + stage: deploy + script: + - gem install bundler + - bundle install + - bundle exec jekyll build -d public + artifacts: + paths: + - public + rules: + - if: '$CI_COMMIT_BRANCH == "master"' +``` + +Now add another job to the CI file, telling it to +test every push to every branch **except** the `master` branch: + +```yaml +image: ruby:2.7 + +workflow: + rules: + - if: '$CI_COMMIT_BRANCH' + +pages: + stage: deploy + script: + - gem install bundler + - bundle install + - bundle exec jekyll build -d public + artifacts: + paths: + - public + rules: + - if: '$CI_COMMIT_BRANCH == "master"' + +test: + stage: test + script: + - gem install bundler + - bundle install + - bundle exec jekyll build -d test + artifacts: + paths: + - test + rules: + - if: '$CI_COMMIT_BRANCH != "master"' +``` + +When the `test` job runs in the `test` stage, Jekyll +builds the site in a directory called `test`. The job affects +all branches except `master`. + +When you apply stages to different jobs, every job in the same +stage builds in parallel. If your web application needs more than +one test before being deployed, you can run all your tests at the +same time. + +## Remove duplicate commands + +To avoid duplicating the same scripts in every job, you can add them +to a `before_script` section. + +In the example, `gem install bundler` and `bundle install` were running +for both jobs, `pages` and `test`. + +Move these commands to a `before_script` section: + +```yaml +image: ruby:2.7 + +workflow: + rules: + - if: '$CI_COMMIT_BRANCH' + +before_script: + - gem install bundler + - bundle install + +pages: + stage: deploy + script: + - bundle exec jekyll build -d public + artifacts: + paths: + - public + rules: + - if: '$CI_COMMIT_BRANCH == "master"' + +test: + stage: test + script: + - bundle exec jekyll build -d test + artifacts: + paths: + - test + rules: + - if: '$CI_COMMIT_BRANCH != "master"' +``` + +## Build faster with cached dependencies + +To build faster, you can cache the installation files for your +project's dependencies by using the `cache` parameter. + +This example caches Jekyll dependencies in a `vendor` directory +when you run `bundle install`: + +```yaml +image: ruby:2.7 + +workflow: + rules: + - if: '$CI_COMMIT_BRANCH' + +cache: + paths: + - vendor/ + +before_script: + - gem install bundler + - bundle install --path vendor + +pages: + stage: deploy + script: + - bundle exec jekyll build -d public + artifacts: + paths: + - public + rules: + - if: '$CI_COMMIT_BRANCH == "master"' + +test: + stage: test + script: + - bundle exec jekyll build -d test + artifacts: + paths: + - test + rules: + - if: '$CI_COMMIT_BRANCH != "master"' +``` + +In this case, you need to exclude the `/vendor` +directory from the list of folders Jekyll builds. Otherwise, Jekyll +will try to build the directory contents along with the site. + +In the root directory, create a file called `_config.yml` +and add this content: + +```yaml +exclude: + - vendor +``` + +Now GitLab CI/CD not only builds the website, +but also pushes with **continuous tests** to feature-branches, +**caches** dependencies installed with Bundler, and +**continuously deploys** every push to the `master` branch. + +## Related topics + +For more information, see the following blog posts. + +- [Use GitLab CI/CD `environments` to deploy your + web app to staging and production](https://about.gitlab.com/blog/2016/08/26/ci-deployment-and-environments/). +- Learn [how to run jobs sequentially, + in parallel, or build a custom pipeline](https://about.gitlab.com/blog/2016/07/29/the-basics-of-gitlab-ci/). +- Learn [how to pull specific directories from different projects](https://about.gitlab.com/blog/2016/12/07/building-a-new-gitlab-docs-site-with-nanoc-gitlab-ci-and-gitlab-pages/) + to deploy this website, <https://docs.gitlab.com>. +- Learn [how to use GitLab Pages to produce a code coverage report](https://about.gitlab.com/blog/2016/11/03/publish-code-coverage-report-with-gitlab-pages/). diff --git a/doc/user/project/pages/getting_started/pages_new_project_template.md b/doc/user/project/pages/getting_started/pages_new_project_template.md new file mode 100644 index 00000000000..cfa4e0910db --- /dev/null +++ b/doc/user/project/pages/getting_started/pages_new_project_template.md @@ -0,0 +1,34 @@ +--- +type: reference, howto +stage: Release +group: Release Management +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 +--- + +# Create a Pages website from a new project template + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/47857) in GitLab 11.8. + +GitLab provides templates for the most popular Static Site Generators (SSGs). +You can create a new project from a template and run the CI/CD pipeline to generate a Pages website. + +Use a template when you want to test GitLab Pages or start a new project that's already +configured to generate a Pages site. + +1. From the top navigation, click the **+** button and select **New project**. +1. Select **Create from Template**. +1. Next to one of the templates starting with **Pages**, click **Use template**. + +  + +1. Complete the form and click **Create project**. +1. From the left sidebar, navigate to your project's **CI/CD > Pipelines** + and click **Run pipeline** to trigger GitLab CI/CD to build and deploy your + site. + +The site can take approximately 30 minutes to deploy. +When the pipeline is finished, go to **Settings > Pages** to find the link to +your Pages website. + +For every change pushed to your repository, GitLab CI/CD runs a new pipeline +that immediately publishes your changes to the Pages site. |