在 GitLab 上托管¶

添加并提交所有内容

$ git add -A && git commit -am "shard complete"

在 GitLab 上创建一个项目，名称和描述与您在 shard.yml 中指定的相同。

添加远程仓库： (请务必将 <YOUR-GITLAB-USERNAME> 和 <YOUR-REPOSITORY-NAME> 替换为您的实际值)

$ git remote add origin https://gitlab.com/<YOUR-GITLAB-USERNAME>/<YOUR-REPOSITORY-NAME>.git

或者如果您使用 SSH

$ git remote add origin [email protected]:<YOUR-GITLAB-USERNAME>/<YOUR-REPOSITORY-NAME>.git

推送
```
$ git push origin master
```

管道¶

接下来，让我们设置一个 GitLab 管道，它可以在我们向仓库推送代码时运行测试并构建/部署文档。

简单来说，您只需将以下文件添加到仓库的根目录，并将其命名为 .gitlab-ci.yml

image: "crystallang/crystal:latest"

before_script:
  - shards install

cache:
  paths:
  - lib/

spec & format:
  script:
  - crystal spec
  - crystal tool format --check

pages:
  stage: deploy
  script:
  - crystal docs -o public src/palindrome-example.cr
  artifacts:
    paths:
    - public
  only:
  - master

这将创建两个作业。第一个作业名为“spec & format”（您可以使用任何名称），默认情况下位于管道的“test”阶段。它只是在由 image 指定的 Docker 容器的新实例上运行 script 中的命令数组。您可能希望将该容器锁定到您正在使用的 Crystal 版本（在您的 shard.yml 中指定），但在此示例中，我们将只使用 latest 标签。

管道的“test”阶段将通过（数组的每个元素都返回一个健康的退出代码）或失败（其中一个元素返回一个错误）。

如果通过，则管道将继续执行我们在此定义的第二个作业，该作业必须命名为 “pages”。这是一个专门用于将内容部署到您的 Gitlab Pages 站点的作业！它在测试通过后执行，因为我们指定它应该在“deploy”阶段发生。它再次运行 script 中的命令（这次构建文档），但这次我们告诉它将 public 路径（我们在其中存放了文档）保留为作业的工件。

将此作业命名为 pages，并将我们的文档放在 public 目录中，并将其指定为 artifact 的结果是，GitLab 将将该目录中的站点部署到默认 URL https://<YOUR-GITLAB-USERNAME>.gitlab.io/<YOUR-REPOSITORY-NAME>。

文件中 before_script 和 cache 键用于在每个作业中运行相同的脚本 (shards install) 以及保留创建的文件 (cache)。如果您没有依赖项，它们不是必需的。

如果您将上述文件提交到您的项目并推送，您将触发新的管道的第一次运行。

$ git add -A && git commit -am 'Add .gitlab-ci.yml' && git push origin master

一些徽章¶

在管道运行时，让我们在项目中添加一些徽章来展示我们的文档以及（希望）成功的管道状态。（您可能想阅读徽章文档）。

徽章只是一个带图像的链接。所以让我们创建一个链接到我们的管道，并从 Gitlab 管道徽章 API 获取徽章图像。

在通用设置的徽章部分，我们首先添加一个发布徽章。链接是：https://gitlab.com/<YOUR-GITLAB-USERNAME>/<YOUR-REPOSITORY-NAME>/pipelines，徽章图片 URL 是：https://gitlab.com/<YOUR-GITLAB-USERNAME>/<YOUR-REPOSITORY-NAME>/badges/master/pipeline.svg。

现在，如果管道已完成，我们将拥有文档，并且可以使用 shields.io 的通用徽章链接到它们。

链接：https://<YOUR-GITLAB-USERNAME>.gitlab.io/<YOUR-REPOSITORY-NAME>
图像：https://img.shields.io/badge/docs-available-brightgreen.svg

发布¶

发布只是您历史记录中的一个特殊提交，带有名称（请参阅标记）。

根据 Crystal Shards README，

当从 Git 仓库安装库时，预计该仓库具有版本标记，这些标记遵循类似 semver 的格式，以 v 为前缀。例如：v1.2.3、v2.0.0-rc1 或 v2017.04.1

GitLab 还具有一个发布功能，它允许您将文件和描述与该标记关联起来。这样，您可以（例如）分发二进制文件。

正如您从发布文档中看到的那样，您可以在 UI 中创建一个带注释的标记以及发布说明/文件

gitlab new tags UI

或者您也可以从命令行创建标记，如下所示

$ git tag -a v0.1.0 -m "Release v0.1.0"

将其推送到远程仓库

$ git push origin master --follow-tags

然后使用 UI 添加/编辑发布说明并附加文件。

最佳实践

使用 -a 选项为发布创建带注释的标记。
遵循语义化版本控制。

发布徽章¶

如果您愿意，您还可以为发布添加一个 shields.io 徽章。GitLab 并不完全支持这种功能，而且在有人为 shields.io 添加 gitlab 版本徽章之前，我们必须直接在 URL 中编码版本号。

链接：https://img.shields.io/badge/release-<VERSION>-brightgreen.svg
图像：https://img.shields.io/badge/release-<VERSION>-brightgreen.svg

其中 <VERSION> 是版本号，以 v 为前缀，如：v0.1.0。

镜像到 GitHub¶

GitHub 上的项目通常有更多的曝光度，并且与其他服务的集成度更高，因此，如果您希望您的库也在那里托管，您可以从 GitLab 设置到 GitHub 的“推送镜像”。

在 GitHub 上创建一个与您的项目同名的仓库。
按照此处的说明操作： https://docs.gitlab.com/ee/workflow/repository_mirroring.html#setting-up-a-push-mirror-from-gitlab-to-github-core
编辑您的 GitHub 描述。您可以使用以下内容
- 描述：正反读都一样的单词。这是
- 链接：https://gitlab.com/<YOUR-GITLAB-USERNAME>/<YOUR-REPOSITORY-NAME>/

这是一个推送镜像，这意味着更改只会单向传播。因此，请务必让潜在的合作者知道，拉取请求和问题应该提交到您的 GitLab 项目。