From 6b2343319aa17873b8532eb039e102c01d72f18f Mon Sep 17 00:00:00 2001 From: Alexey Igrychev Date: Wed, 11 Jan 2023 11:10:17 +0000 Subject: [PATCH 1/2] chore(README): focus on install action Signed-off-by: Alexey Igrychev --- README.md | 261 +++++++++--------------------------------------------- 1 file changed, 43 insertions(+), 218 deletions(-) diff --git a/README.md b/README.md index 948800e..b2bafd4 100644 --- a/README.md +++ b/README.md @@ -3,127 +3,11 @@

___ -This action set allows you to organize CI/CD with GitHub Actions and [werf](https://github.com/werf/werf). The set consists of several independent and complex actions: - -- [werf/actions/converge](https://github.com/werf/actions/tree/v1.2/converge) -- [werf/actions/dismiss](https://github.com/werf/actions/tree/v1.2/dismiss) -- [werf/actions/build](https://github.com/werf/actions/tree/v1.2/build) -- [werf/actions/run](https://github.com/werf/actions/tree/v1.2/run) -- [werf/actions/cleanup](https://github.com/werf/actions/tree/v1.2/cleanup) - -Each action combines all the necessary steps in itself, and logic may be divided into [environment setup](#environment-setup-in-details) and launching the corresponding command. +This action allows you to organize CI/CD with GitHub Actions and [werf](https://github.com/werf/werf). **Ready-to-use GitHub Actions Workflows** for different CI/CD workflows are available [here](https://werf.io/documentation/v1.2/advanced/ci_cd/github_actions.html#complete-set-of-configurations-for-ready-made-workflows). -> Also, there is another action — [werf/actions/install](https://github.com/werf/actions/tree/v1.2/install). With this action, the user can install werf and use binary within job steps for own purposes. - -## Versioning - -When using actions, select the version corresponding to the required `MAJOR.MINOR` version of werf: - -```yaml -# Run converge using actual werf version within 1.1 alpha channel. -- uses: werf/actions/converge@v1.1 - -# Run converge using actual werf version within 1.2 alpha channel. -- uses: werf/actions/converge@v1.2 -``` - -## Environment setup in details - -### werf binary installation - -By default, all actions install actual werf version within 1.2 alpha channel (more details about channels, werf release cycle and compatibility promise [here](https://werf.io/installation.html#all-changes-in-werf-go-through-all-stability-channels)). -Using the `channel` input the user can switch the release channel. - -> This is recommended approach to be up-to-date and to use actual werf version without changing configurations. - -```yaml -- uses: werf/actions/converge@v1.2 - with: - channel: alpha -``` - -Withal, it is not necessary to work within release channels, and the user might specify certain werf version with `version` input. - -```yaml -- uses: werf/actions/converge@v1.2 - with: - version: v1.2.9 -``` - -### werf ci-env - -This is the step where an action: - -- sets the defaults for werf command options based on [GitHub Workflow environment variables](https://docs.github.com/en/actions/reference/environment-variables) (e.g. container repository address to the `WERF_REPO` environment variable using the following pattern: `ghcr.io/$GITHUB_REPOSITORY/`). -- performs _docker login_ to `ghcr.io` using the `github-token` input (only if `ghcr.io` used as `WERF_REPO`). - -> The `github-token` input is optional, and the input is there in case you need to use a non-default token. By default, an action will use [the token provided to your workflow](https://docs.github.com/en/actions/reference/authentication-in-a-workflow#about-the-github_token-secret). - -### kubeconfig setup (*optional*) - -The _kubeconfig_ may be used for deployment, cleanup, distributed locks and caches. Thus, the configuration should be added before step with the action or passed as base64 encoded data with `kube-config-base64-data` input: - -* Prepare _kubeconfig_ (e.g. `cat ~/.kube/config | base64`) and save in [GitHub Secrets](https://docs.github.com/en/actions/reference/encrypted-secrets) (e.g. with name `KUBE_CONFIG_BASE64_DATA`). - -* Pass secret with `kube-config-base64-data` input: - - ```yaml - - uses: werf/actions/converge@v1.2 - with: - kube-config-base64-data: ${{ secrets.KUBE_CONFIG_BASE64_DATA }} - ``` - -## Working with werf options - -All werf options can be defined with environment variables: - -```yaml -- uses: werf/actions/converge@v1.2 - env: - WERF_LOG_VERBOSE: "on" # The same as using the option --log-verbose=on. -``` - -## Working with container registry - -### Default container repository - -An action generates the default container repository address and performs _docker login_ to the registry within [werf ci-env step](#werf-ci-env). - -For cleanup action, the user needs [to create personal access token](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token) with `read:packages` and `delete:packages` scope and uses it as the `WERF_REPO_GITHUB_TOKEN` environment variable or the `github-token` input. It is recommended [to store the token as a secret](https://help.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets). - -```yaml -- uses: werf/actions/cleanup@v1.2 - with: - kube-config-base64-data: ${{ secrets.KUBE_CONFIG_BASE64_DATA }} - env: - WERF_REPO_GITHUB_TOKEN: ${{ secrets.WERF_CLEANUP_PAM }} -``` - -### Custom container repository - -An arbitrary container repository can be specified with the `WERF_REPO` and `WERF_REPO_CONTAINER_REGISTRY` environment variables. For instance, steps for GCR: - -```yaml -- name: Login to GCR - uses: docker/login-action@v1 - with: - registry: gcr.io - username: _json_key - password: ${{ secrets.GCR_JSON_KEY }} - -- uses: werf/actions/converge@v1.2 - env: - WERF_REPO: "gcr.io/company/app" - WERF_REPO_CONTAINER_REGISTRY: "gcr" -``` - -> To learn more about how to work with the different container registries, see the appropriate [article in the werf documentation](https://werf.io/documentation/v1.2/advanced/supported_container_registries.html). - -## Examples - -### converge +## How to use ```yaml converge: @@ -135,113 +19,54 @@ converge: uses: actions/checkout@v2 with: fetch-depth: 0 - - - name: Converge - uses: werf/actions/converge@v1.2 - with: - env: production - kube-config-base64-data: ${{ secrets.KUBE_CONFIG_BASE64_DATA }} -``` - -### dismiss - -```yaml -dismiss: - name: Dismiss - runs-on: ubuntu-latest - steps: - - - name: Checkout code - uses: actions/checkout@v2 - - - name: Dismiss - uses: werf/actions/dismiss@v1.2 - with: - kube-config-base64-data: ${{ secrets.KUBE_CONFIG_BASE64_DATA }} - env: production -``` - -### run - -```yaml -run: - name: Run - runs-on: ubuntu-latest - steps: - - - name: Checkout code - uses: actions/checkout@v2 - with: - fetch-depth: 0 - - - name: Run - uses: werf/actions/run@v1.2 - with: - image: backend - args: rails server - kube-config-base64-data: ${{ secrets.KUBE_CONFIG_BASE64_DATA }} - env: - WERF_DOCKER_OPTIONS: "-d -p 3000:3000" -``` - -### cleanup - -```yaml -cleanup: - name: Cleanup - runs-on: ubuntu-latest - steps: - - - name: Checkout code - uses: actions/checkout@v2 - - - name: Fetch all history for all tags and branches - run: git fetch --prune --unshallow - - - name: Cleanup - uses: werf/actions/cleanup@v1.2 - with: - kube-config-base64-data: ${{ secrets.KUBE_CONFIG_BASE64_DATA }} - env: - WERF_REPO_GITHUB_TOKEN: ${{ secrets.WERF_CLEANUP_PAM }} -``` - -### install - -```yaml -werf: - name: werf - runs-on: ubuntu-latest - steps: - - - name: Checkout code - uses: actions/checkout@v2 - - - name: Install werf CLI - uses: werf/actions/install@v1.2 - # For deploy and distributed locks. - - name: Create kube config + - name: Install werf + uses: werf/actions/install@v1.2 + + - name: Run script run: | - KUBECONFIG=$(mktemp -d)/config - base64 -d <(printf "%s" $KUBE_CONFIG_BASE64_DATA) > $KUBECONFIG - echo KUBECONFIG=$KUBECONFIG >> $GITHUB_ENV - env: - KUBE_CONFIG_BASE64_DATA: ${{ secrets.KUBE_CONFIG_BASE64_DATA }} - - - name: Run werf commands - run: | - source $(werf ci-env github --as-file) + . $(werf ci-env github --as-file) werf render werf converge env: - GITHUB_TOKEN: ${{ github.token }} + WERF_KUBECONFIG_BASE64: ${{ secrets.KUBE_CONFIG_BASE64_DATA }} WERF_ENV: production ``` -# FAQ +## Versioning -## werf always rebuilds images on new commit +When using action, select the version corresponding to the required `MAJOR.MINOR` version of werf: + +```yaml +# Setup actual werf version within 1.1 alpha channel. +- uses: werf/actions/install@v1.1 + +# Setup actual werf version within 1.2 alpha channel. +- uses: werf/actions/install@v1.2 +``` + +By default, the action installs actual werf version within alpha channel (more details about channels, werf release cycle and compatibility promise [here](https://werf.io/installation.html#all-changes-in-werf-go-through-all-stability-channels)). +Using the `channel` input the user can switch the release channel. + +> This is recommended approach to be up-to-date and to use actual werf version without changing configurations. + +```yaml +- uses: werf/actions/install@v1.2 + with: + channel: alpha +``` + +Withal, it is not necessary to work within release channels, and the user might specify certain werf version with `version` input. + +```yaml +- uses: werf/actions/install@v1.2 + with: + version: v1.2.9 +``` + +## FAQ + +### werf always rebuilds images on new commit Make sure to use `fetch-depth: 0` setting in the checkout action, like follows: @@ -252,10 +77,10 @@ Make sure to use `fetch-depth: 0` setting in the checkout action, like follows: fetch-depth: 0 ``` -By default fetch-depth set to `1` which disables git history when checking out code. werf cache selection algorithm uses git history to determine whether some image bound to some commit could be used as a cache when building current commit (current commit should be descendant to the cache commit). +By default, fetch-depth set to `1` which disables git history when checking out code. werf cache selection algorithm uses git history to determine whether some image bound to some commit could be used as a cache when building current commit (current commit should be descendant to the cache commit). Setting `fetch-depth` to `0` enables full fetch of git history and it is a **recommended** approach. It is also possible to limit fetch history with some decent number of commits, which would enable images caching limited to that number of commits, but this would have a negative impact on cache reproducibility. -# License +## License Apache License 2.0, see [LICENSE](LICENSE) From 51f58468970c8c1807b515f981ade4de91c4b183 Mon Sep 17 00:00:00 2001 From: Alexey Igrychev Date: Fri, 20 Jan 2023 11:53:15 +0000 Subject: [PATCH 2/2] chore: up actions/checkout to v3 Signed-off-by: Alexey Igrychev --- .github/workflows/test.yaml | 4 ++-- README.md | 4 ++-- build/README.md | 2 +- cleanup/README.md | 2 +- converge/README.md | 2 +- dismiss/README.md | 2 +- install/README.md | 2 +- run/README.md | 2 +- 8 files changed, 10 insertions(+), 10 deletions(-) diff --git a/.github/workflows/test.yaml b/.github/workflows/test.yaml index f84a465..b3a627e 100644 --- a/.github/workflows/test.yaml +++ b/.github/workflows/test.yaml @@ -12,7 +12,7 @@ jobs: runs-on: ${{ matrix.os }} steps: - name: Checkout code - uses: actions/checkout@v2 + uses: actions/checkout@v3 with: fetch-depth: 0 @@ -31,7 +31,7 @@ jobs: steps: - name: Checkout code - uses: actions/checkout@v2 + uses: actions/checkout@v3 with: fetch-depth: 0 diff --git a/README.md b/README.md index b2bafd4..83b24a6 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ converge: steps: - name: Checkout code - uses: actions/checkout@v2 + uses: actions/checkout@v3 with: fetch-depth: 0 @@ -72,7 +72,7 @@ Make sure to use `fetch-depth: 0` setting in the checkout action, like follows: ``` - name: Checkout code - uses: actions/checkout@v2 + uses: actions/checkout@v3 with: fetch-depth: 0 ``` diff --git a/build/README.md b/build/README.md index 0428da5..9ddf77f 100644 --- a/build/README.md +++ b/build/README.md @@ -33,7 +33,7 @@ build: steps: - name: Checkout code - uses: actions/checkout@v2 + uses: actions/checkout@v3 with: fetch-depth: 0 diff --git a/cleanup/README.md b/cleanup/README.md index 3ddbef8..ed1a121 100644 --- a/cleanup/README.md +++ b/cleanup/README.md @@ -33,7 +33,7 @@ cleanup: steps: - name: Checkout code - uses: actions/checkout@v2 + uses: actions/checkout@v3 - name: Fetch all history for all tags and branches run: git fetch --prune --unshallow diff --git a/converge/README.md b/converge/README.md index 77bcde0..4c986f9 100644 --- a/converge/README.md +++ b/converge/README.md @@ -36,7 +36,7 @@ converge: steps: - name: Checkout code - uses: actions/checkout@v2 + uses: actions/checkout@v3 with: fetch-depth: 0 diff --git a/dismiss/README.md b/dismiss/README.md index 7e758c5..0714f7e 100644 --- a/dismiss/README.md +++ b/dismiss/README.md @@ -36,7 +36,7 @@ dismiss: steps: - name: Checkout code - uses: actions/checkout@v2 + uses: actions/checkout@v3 - name: Dismiss uses: werf/actions/dismiss@v1.2 diff --git a/install/README.md b/install/README.md index fa197a7..5eb6506 100644 --- a/install/README.md +++ b/install/README.md @@ -43,7 +43,7 @@ werf: steps: - name: Checkout code - uses: actions/checkout@v2 + uses: actions/checkout@v3 - name: Install werf CLI uses: werf/actions/install@v1.2 diff --git a/run/README.md b/run/README.md index 670fc5a..10f45e4 100644 --- a/run/README.md +++ b/run/README.md @@ -40,7 +40,7 @@ run: steps: - name: Checkout code - uses: actions/checkout@v2 + uses: actions/checkout@v3 with: fetch-depth: 0