Merge pull request #156 from zong-zhe/kpm-push-ci

doc: add docs for 'kpm push by github action'

Author: Peefy

docs/user_docs/guides/package-management/4-share_your_pkg.md renamed to docs/user_docs/guides/package-management/4-how-to/4-share_your_pkg.md

@@ -0,0 +1,82 @@
+# Push Your KCL Package by GitHub Action
+
+[kpm](https://github.com/KusionStack/kpm) is a tool for managing kcl packages. This article will guide you how to use kpm in GitHub Action to push your kcl package to OCI registry.
+
+## Step 1: Install kpm
+
+At first, you need to install kpm on your computer. You can follow [kpm installation document](https://kcl-lang.io/docs/user_docs/guides/package-management/installation).
+
+## Step 2: Create a GitHub account
+
+If you already have a GitHub account, you can skip this step.
+
+[Sign up for a new GitHub account](https://docs.github.com/en/get-started/signing-up-for-github/signing-up-for-a-new-github-account)
+
+## Step 3: Create a GitHub repository for your KCL package
+
+### 1. Prepare a GitHub repository for your KCL package
+
+You need to prepare a GitHub repository for your KCL package.
+
+[Create a GitHub repository](https://docs.github.com/en/get-started/quickstart/create-a-repo)
+
+In this repository, add your KCL program, take the repository https://github.com/awesome-kusion/catalog.git as an example,
+
+```bash
+├── .github
+│   └── workflows
+│       └── push.yaml # github action workflow
+├── LICENSE
+├── README.md
+├── kcl.mod # kcl.mod to define your kcl package
+├── kcl.mod.lock # kcl.mod.lock generated by kpm
+└── main.k # Your KCL program
+```
+
+### 2. Set OCI Registry, account and password for your Github repository
+
+Take docker.io as an example, you can set secrets `REG`, `REG_ACCOUNT` and `REG_TOKEN` for your repository. The value of `REG` is `docker.io`, the value of `REG_ACCOUNT` is your `docker.io` account, and the value of `REG_TOKEN` is your `docker.io` login password.
+
+[Add secrets to the repository](https://docs.github.com/en/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository)
+
+If you use `ghcr.io` as `Registry`, you need to use GitHub token as secrets.
+
+[Create a GitHub Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token#personal-access-tokens-classic)
+
+## Step 4: Add your KCL package to the repository and write github action workflow
+
+Add github action file `.github/workflows/push.yml` to this repository, the content is as follows:
+
+```yaml
+name: KPM Push Workflow
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+
+      - name: Set up Go 1.19
+        uses: actions/setup-go@v2
+        with:
+          go-version: 1.19
+
+      - name: Install kpm
+        run: go install kcl-lang.io/kpm@latest
+
+      - name: Login and Push
+        env:
+          KPM_REG: ${{ secrets.REG }}
+          KPM_REPO: ${{ secrets.REG_ACCOUNT }}
+        run: kpm login -u ${{ secrets.REG_ACCOUNT }} -p ${{ secrets.REG_TOKEN }} ${{ secrets.REG }} && kpm push
+
+      - name: Run kpm project from oci registry
+        run: kpm run oci://${{ secrets.REG }}/${{ secrets.REG_ACCOUNT }}/catalog --tag 0.0.1
+
+```

docs/user_docs/guides/package-management/5-share_your_pkg_docker.md renamed to docs/user_docs/guides/package-management/4-how-to/5-share_your_pkg_docker.md

@@ -0,0 +1,4 @@
+{
+  "label": "How to",
+  "position": 4
+}

docs/user_docs/guides/package-management/4-how-to/6-push_github_action.md

@@ -20,6 +20,9 @@
   "sidebar.user_docs.category.Package Management": {
     "message": "包管理工具"
   },
+  "sidebar.user_docs.category.How to": {
+    "message": "如何使用"
+  },
   "sidebar.user_docs.category.Schema Definition": {
     "message": "模型定义"
   },

docs/user_docs/guides/package-management/4-how-to/_category_.json

@@ -0,0 +1,87 @@
+# 如何在 github action 中使用 kpm 发布您的 KCL 包 
+
+[kpm](https://github.com/KusionStack/kpm) 是一个用于管理 kcl 包的工具。本文将指导您如何在 GitHub Action 中使用 kpm 将您的 kcl 包推送到发布到 ghcr.io 中。
+
+下面是一个简单的步骤，指导您如何使用 kpm 将您的 kcl 包推送到 OCI Registry。
+
+## 步骤 1：安装 kpm
+
+首先，您需要在您的计算机上安装 kpm。您可以按照 [kpm 安装文档](https://kcl-lang.io/docs/user_docs/guides/package-management/installation)中的说明进行操作。
+
+## 步骤 2：创建一个 GitHub 账号
+
+如果您已经有 GitHub 帐号了，您可以选择跳过这一步
+
+[注册新的一个 GitHub 账号](https://docs.github.com/zh/get-started/signing-up-for-github/signing-up-for-a-new-github-account)
+
+## 步骤 3: 为您的 KCL 包创建一个 GitHub 仓库并进行相关配置
+
+### 1. 为您的 KCL 程序包准备仓库
+您需要为您的 KCL 程序包准备一个 GitHub 仓库。
+
+[创建一个 GitHub 仓库](https://docs.github.com/zh/get-started/quickstart/create-a-repo) 
+
+
+在这个仓库中添加您的 KCL 程序，以仓库 https://github.com/awesome-kusion/catalog.git 为例，
+
+```bash
+├── .github
+│   └── workflows
+│       └── push.yaml # github action 文件 
+├── LICENSE
+├── README.md
+├── kcl.mod # kcl.mod 将当前仓库内容定义为一个 kcl 包
+├── kcl.mod.lock # kcl.mod.lock 是 kpm 自动生成的文件
+└── main.k # 您的 KCL 程序
+```
+
+### 2. 为您的仓库设置 OCI Registry，账户和密码
+
+以 docker.io 为例，您可以为您的仓库设置 secrets `REG`, `REG_ACCOUNT` 和 `REG_TOKEN`。`REG` 的值为 `docker.io`，`REG_ACCOUNT` 的值为您的 docker.io 账户, `REG_TOKEN` 为您的 `docker.io` 登录密码。
+
+[为仓库添加 secrets](https://docs.github.com/zh/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository)
+
+如果您使用 `ghcr.io` 作为 `Registry`, 您需要使用 GitHub token 作为 secrets。
+
+[创建一个 GitHub Token](https://docs.github.com/zh/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#personal-access-tokens-classic)
+
+
+## 步骤 4: 将您的 KCL 包添加到仓库中并编写 github action workflow
+
+为这个仓库添加 github action 文件 `.github/workflows/push.yml`，内容如下：
+
+```yaml
+name: KPM Push Workflow
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+
+      - name: Set up Go 1.19
+        uses: actions/setup-go@v2
+        with:
+          go-version: 1.19
+
+      - name: Install kpm
+        run: go install kcl-lang.io/kpm@latest
+
+      - name: Login and Push
+        env:
+          # 通过环境变量指定 OCI Registry 和账户
+          KPM_REG: ${{ secrets.REG }}
+          KPM_REPO: ${{ secrets.REG_ACCOUNT }}
+          # kpm login 时使用 secrets.REG_TOKEN 
+        run: kpm login -u ${{ secrets.REG_ACCOUNT }} -p ${{ secrets.REG_TOKEN }} ${{ secrets.REG }} && kpm push
+
+      - name: Run kpm project from oci registry
+        run: kpm run oci://${{ secrets.REG }}/${{ secrets.REG_ACCOUNT }}/catalog --tag 0.0.1
+
+```

i18n/zh-CN/docusaurus-plugin-content-docs/current.json

@@ -0,0 +1,4 @@
+{
+  "label": "如何使用",
+  "position": 4
+}

i18n/zh-CN/docusaurus-plugin-content-docs/current/user_docs/guides/package-management/4-share_your_pkg.md renamed to i18n/zh-CN/docusaurus-plugin-content-docs/current/user_docs/guides/package-management/4-how-to/4-share_your_pkg.md

@@ -20,6 +20,9 @@
   "sidebar.user_docs.category.Package Management": {
     "message": "包管理工具"
   },
+  "sidebar.user_docs.category.How to": {
+    "message": "如何使用"
+  },
   "sidebar.user_docs.category.Schema Definition": {
     "message": "模型定义"
   },