Help us learn about your current experience with the documentation. Take the survey.

参与 GitLab Pages 开发

学习如何配置 GitLab Pages，以便帮助开发该功能。

配置 GitLab Pages 主机名

GitLab Pages 需要主机名或域名，因为每个不同的 GitLab Pages 站点都是通过子域名访问的。您可以设置 GitLab Pages 主机名：

不使用通配符，编辑您的 hosts 文件

由于 /etc/hosts 不支持通配符主机名，您必须为 GitLab Pages 配置一个条目，然后为每个页面站点配置一个条目：

127.0.0.1 gdk.test           # If you're using GDK
127.0.0.1 pages.gdk.test     # Pages host
# Any namespace/group/user needs to be added
# as a subdomain to the pages host. This is because
# /etc/hosts doesn't accept wildcards
127.0.0.1 root.pages.gdk.test # for the root pages

使用 DNS 通配符替代方案

如果您不想编辑 /etc/hosts 而是更喜欢使用 DNS 通配符，您可以使用：

不使用 GDK 配置 GitLab Pages

在 GitLab Pages 站点的根目录中创建一个 gitlab-pages.conf 文件，例如：

# Default port is 3010, but you can use any other
listen-http=:3010

# Your local GitLab Pages domain
pages-domain=pages.gdk.test

# Directory where the pages are stored
pages-root=shared/pages

# Show more information in the logs
log-verbose=true

要查看更多选项，您可以检查 internal/config/flags.go 或运行 gitlab-pages --help。

手动运行 GitLab Pages

对于代码中的任何更改，您必须运行 make 来构建应用程序。最好在启动应用程序之前总是运行它。构建速度很快，所以不用担心！

make && ./gitlab-pages -config=gitlab-pages.conf

使用 GDK 配置 GitLab Pages

在以下步骤中，$GDK_ROOT 是您克隆 GDK 的目录。

  1. 设置 GDK 主机名。

  2. 向 gdk.yml 添加一个 GitLab Pages 主机名：

    gitlab_pages:
  enabled: true         # enable GitLab Pages to be managed by gdk
  port: 3010            # default port is 3010
  host: pages.gdk.test  # the GitLab Pages domain
  auto_update: true     # if gdk must update GitLab Pages git
  verbose: true         # show more information in the logs

使用 GDK 运行 GitLab Pages

设置好这些配置后，GDK 会管理一个 GitLab Pages 进程，您可以使用以下命令访问它：

  • Start: gdk start gitlab-pages
  • Stop: gdk stop gitlab-pages
  • Restart: gdk restart gitlab-pages
  • Tail logs: gdk tail gitlab-pages

手动运行 GitLab Pages

您也可以独立于 GDK 进程管理来构建和启动应用程序。

对于代码中的任何更改，您必须运行 make 来构建应用程序。最好在启动应用程序之前总是运行它。构建速度很快，所以不用担心！

make && ./gitlab-pages -config=gitlab-pages.conf

在 FIPS 模式下构建 GitLab Pages

FIPS_MODE=1 make && ./gitlab-pages -config=gitlab-pages.conf

创建 GitLab Pages 站点

要在本地构建 GitLab Pages 站点，您必须 配置 gitlab-runner。

有关更多信息，请参阅用户手册。

启用访问控制

GitLab Pages 支持私有站点。私有站点只能由有权访问您的 GitLab 项目的用户访问。

GitLab Pages 访问控制默认是禁用的。要启用它：

  1. 在 GitLab 本身中启用 GitLab Pages 访问控制。您可以通过两种方式实现：

    • 如果您不使用 GDK，请编辑 gitlab.yml：

      # gitlab/config/gitlab.yml
pages:
  access_control: true

    • 如果您使用 GDK，请编辑 gdk.yml：

      # $GDK_ROOT/gdk.yml
gitlab_pages:
  enabled: true
  access_control: true

  2. 重启 GitLab（如果通过 GDK 运行，请运行 gdk restart）。运行 gdk reconfigure 会覆盖 config/gitlab.yml 中 access_control 的值。

  3. 在您的本地 GitLab 实例中，在浏览器中访问 http://gdk.test:3000/admin/applications。

  4. 创建一个具有 api 范围的实例级 OAuth 应用程序。

  5. 将您的 redirect-uri 值设置为 pages-domain 授权端点 （例如，http://pages.gdk.test:3010/auth）。 redirect-uri 不能包含任何 GitLab Pages 站点域名。

  6. 添加身份验证客户端配置：

    • 使用 GDK，在 gdk.yml 中：

      gitlab_pages:
  enabled: true
  access_control: true
  auth_client_id: $CLIENT_ID           # the OAuth application id created in http://gdk.test:3000/admin/applications
  auth_client_secret: $CLIENT_SECRET   # the OAuth application secret created in http://gdk.test:3000/admin/applications

      GDK 生成随机的 auth_secret 并基于 GitLab Pages 主机配置构建 auth_redirect_uri。

    • 不使用 GDK，在 gitlab-pages.conf 中：

      ## the following are only needed if you want to test auth for private projects
auth-client-id=$CLIENT_ID                         # the OAuth application id created in http://gdk.test:3000/admin/applications
auth-client-secret=$CLIENT_SECRET                 # the OAuth application secret created in http://gdk.test:3000/admin/applications
auth-secret=$SOME_RANDOM_STRING                   # should be at least 32 bytes long
auth-redirect-uri=http://pages.gdk.test:3010/auth # the authentication callback url for GitLab Pages

  7. 如果在 GDK 内部运行 Pages，您可以在 gdk.yml 中的 gdk 下使用 GDK protected_config_files 部分 来避免 gitlab-pages.conf 配置被重写：

    gdk:
  protected_config_files:
  - 'gitlab-pages/gitlab-pages.conf'

启用对象存储

GitLab Pages 支持使用对象存储来存储工件，但对象存储默认是禁用的。您可以在 GDK 中启用它：

  1. 编辑 gdk.yml 以在 GitLab 本身中启用对象存储：

    # $GDK_ROOT/gdk.yml
object_store:
  enabled: true

  2. 通过运行命令 gdk reconfigure 和 gdk restart 来重新配置和重启 GitLab。

有关更多信息，请参阅 GDK 文档。

代码检查

# Run the linter locally
make lint

# Run linter and fix issues (if supported by the linter)
make format

测试

要运行测试，您可以使用以下命令：

# This will run all of the tests in the codebase
make test

# Run a specific test file
go test ./internal/serving/disk/

# Run a specific test in a file
go test ./internal/serving/disk/ -run TestDisk_ServeFileHTTP

# Run all unit tests except acceptance_test.go
go test ./... -short

# Run acceptance_test.go only
make acceptance
# Run specific acceptance tests
# We add `make` here because acceptance tests use the last binary that was compiled,
# so we want to have the latest changes in the build that is tested
make && go test ./ -run TestRedirect

贡献

功能标志

All newly-introduced feature flags should be disabled by default.

考虑为任何重大更改添加 功能标志。功能标志可以使这些更改的发布和回滚更容易，避免事件和停机时间。要向 GitLab Pages 添加新功能标志：

  1. 在 internal/feature/feature.go 中创建功能标志，默认必须为 关闭 状态。
  2. 使用 Feature flag 模板创建一个问题来跟踪该功能标志。
  3. 将 ~"feature flag" 标签添加到任何处理功能标志的合并请求中。

对于 GitLab Pages，功能标志在全局级别由环境变量控制。需要在服务级别部署才能更改功能标志的状态。启用 GitLab Pages 功能标志的合并请求示例： 强制执行 GitLab Pages 速率限制

相关主题

成为 GitLab Pages 维护者

本文档为想要成为 GitLab Pages 项目维护者的 GitLab 团队成员提供指导。维护者应该对 GitLab Pages 代码库有深入的理解。在申请成为项目维护者之前，一个人应该对代码库有良好的感觉，在一个或多个功能方面的专业知识，以及对我们编码标准的深入理解。

期望

在 GitLab 成为维护者的过程在手册中有定义，并且这是此过程的基础。预期的一件事是大量的审查，然而；与 GitLab Rails 项目相比，GitLab Pages 的变更率太低。

为了解决这个问题，一个人必须在代码库的以下领域感到舒适：

主要领域：

  • Namespace/project resolution
  • ZIP serving and the virtual file system
  • Authentication

较小领域：

  • Redirects
  • Artifacts proxying
  • Handling of TLS certificates
  • Rate-limiting
  • Metrics and monitoring

为了实现这一点，您应该尝试在所有主要领域和上面提到的 2-3 个较小领域做出相关贡献，以便您更好地理解功能。相关贡献可能是错误修复、性能改进、新功能或重大重构。

审查者

在成为维护者之前，您应该首先成为该项目的审查者。这应该包括对代码库任何部分的更改，包括文档。

要成为审查者，请遵循手册中概述的步骤。在成为维护者之前，您应该成为审查者多长时间没有固定的时间表，但您应该在本文档期望部分中提到的领域获得足够的经验。

维护者

要成为维护者，请遵循手册中概述的步骤。当这些陈述感觉真实时，您可能已经准备好成为维护者：

  • The MRs you have reviewed consistently make it through maintainer review without significant additionally required changes
  • The MRs you have created consistently make it through reviewer and maintainer review without significant required changes
  • You feel comfortable working through operational tasks

If those subjective requirements are satisfied, open an MR promoting you to maintainer and tag the existing maintainers.