From d1fc9bc4842e3cb89b3f907bb87b24a8aae61266 Mon Sep 17 00:00:00 2001 From: NimRegev Date: Wed, 19 Oct 2022 14:19:27 +0300 Subject: [PATCH 1/3] Update with parameterization examples Added examples for CF_IMAGE, GIT_BRANCH --- .../ci-integrations/codefresh-classic.md | 100 ++++++++++++++++++ .../integrations/ci-integrations/examples.md | 42 ++++++++ .../ci-integrations/github-actions.md | 69 ++++++++++++ _docs/integrations/ci-integrations/jenkins.md | 82 ++++++++++++++ 4 files changed, 293 insertions(+) create mode 100644 _docs/integrations/ci-integrations/examples.md diff --git a/_docs/integrations/ci-integrations/codefresh-classic.md b/_docs/integrations/ci-integrations/codefresh-classic.md index 7fa98858..5f9488a3 100644 --- a/_docs/integrations/ci-integrations/codefresh-classic.md +++ b/_docs/integrations/ci-integrations/codefresh-classic.md @@ -37,6 +37,106 @@ The table describes the arguments required to connect Codefresh Classic to Codef For how-to instructions, see [Connect a third-party CI platform/tool to Codefresh]({{site.baseurl}}/docs/integrations/ci-integrations/#connect-a-third-party-ci-platformtool-to-codefresh/). +### Templatization examples for CF arguments + +Arguments such as `CF_IMAGE`, `CF_GIT_BRANCH`, and `CF_JIRA_MESSAGE` are populated dynamically when the Codefresh Classic integration pipeline is triggered. You can templatize the values of these arguments to ensure that the required information is included in the reported image. + +Codefresh Classic offers [system variables](https://codefresh.io/docs/docs/codefresh-yaml/variables/#system-provided-variables) you can use to templatize argument values. + +{::nomarkdown} +
+{:/} + +#### CF_IMAGE examples +**Example: Get full repo and branch information** +This example illustrates how to the value for `CF_IMAGE` to report the repo owner, name, and branch, with the Git hash. + + Value: + + {% raw %}`${{CF_REPO_OWNER}}/${{CF_REPO_NAME}}:${{CF_BRANCH_TAG_NORMALIZED}}-${{CF_SHORT_REVISION}}`{% endraw %} + + where: + * {% raw %}`${{CF_REPO_OWNER}}`{% endraw %} reports the owner of the repository. + * {% raw %}`${{CF_REPO_NAME}}`{% endraw %} reports the name of the repository. + * {% raw %}`${{CF_BRANCH_TAG_NORMALIZED}}`{% endraw %} reports the normalized version of the branch name, without invalid characters in case the branch name is the Docker image tag name. + * {% raw %}`${{CF_SHORT_REVISION}}`{% endraw %} reports the abbreviated 7-character revision hash, as used in Git. + +**Example: Use a specific image tag** +This example illustrates how to define the value for `CF_IMAGE` value to report a specific image version. + + Value: + {% raw %}`{{CF_REPO_OWNER}}/${{CF_REPO_NAME}}:` {% endraw %} + + where: + * {% raw %}`${{CF_REPO_OWNER}}`{% endraw %} and {% raw %}`${{CF_REPO_NAME}}`{% endraw %} report the names of the repository owner and the repository respectively. + * {% raw %}``{% endraw %} reports the hard-coded tag v1.0. + + +**Example: Tag image with the latest Git tag available on repository** + +Value: +{% raw %}`codefresh/${{CF_REPO_NAME}}:latest`{% endraw %} + +where: +* {% raw %}`codefresh`{% endraw %} is the hard-coded owner of the image. +* {% raw %}`${{CF_REPO_NAME}}`{% endraw %} reports the name of the repository that triggered the pipeline. +* {% raw %}`latest`{% endraw %} reports the latest Git tag available for the repository defined by {% raw %}`${{CF_REPO_NAME}}`{% endraw %}. + +{::nomarkdown} +
+{:/} + +#### CF_GIT_BRANCH examples + +**Example: Report Git branch or tag with committer and commit message** + +This example illustrates how to report the name or tag of the Git branch with committer and commit message. + + Value: + {% raw %}`${{CF_REPO_NAME}}/${{CF_BRANCH}}:${{CF_COMMIT_AUTHOR}}/${{CF_COMMIT_MESSAGE}}`{% endraw %} + + where: + * {% raw %}`${{CF_REPO_NAME}}`{% endraw %} reports the name of the repository. For example, `production`. + * {% raw %}`${{CF_BRANCH}}`{% endraw %} reports the branch name or tag based on the JSON payload of the Git repository that triggered the pipeline. For example, `auth-feature`. + * {% raw %}`${{CF_COMMIT_AUTHOR}}`{% endraw %} reports the name of the user who made the commit. For example, `nr-codefresh`. + * {% raw %}`${{CF_COMMIT_MESSAGE}}`{% endraw %} reports the commit message of the repository. For example, `support oauth authentication for ci integrations`. + + +**Example: Report normalized Git branch or tag with committer and commit message** + +This example illustrates how to report the normalized name or tag of the Git branch with committer and commit message. +Normalizing the branch name removes any invalid characters in the name if the branch name is also used as the Docker image tag name. + + Value: + + {% raw %}`${{CF_REPO_NAME}}/${{CF_BRANCH_TAG_NORMALIZED}}:${{CF_COMMIT_AUTHOR}}/${{CF_COMMIT_MESSAGE}}`{% endraw %} + + where: + * {% raw %}`${{CF_REPO_NAME}}`{% endraw %} reports the name of the repository. For example, `production`. + * {% raw %}`${{CF_BRANCH_TAG_NORMALIZED}}`{% endraw %} reports the normalized version of the branch name or tag based on the JSON payload of the Git repository that triggered the pipeline. (NIMA: Kostis please suggest a good example ) + * {% raw %}`${{CF_COMMIT_AUTHOR}}`{% endraw %} reports the name of the user who made the commit. For example, `nr-codefresh`. + * {% raw %}`${{CF_COMMIT_MESSAGE}}`{% endraw %}reports the commit message of the repository. For example, `support oauth authentication for ci integrations`. + +**Example: Report normalized Git branch or tag in lowercase with PR information** + +This example illustrates how to report the normalized name or tag of the Git branch in lowercase, with PR (pull request) information. +Normalizing the branch name removes any invalid characters in the name if the branch name is also used as the Docker image tag name. + +Value: + {% raw %}`${{CF_REPO_NAME}}/${{CF_BRANCH_TAG_NORMALIZED}}:${{CF_PULL_REQUEST_TARGET}}/${{CF_PULL_REQUEST_NUMBER}}`{% endraw %} + + where: + * {% raw %}`${{CF_REPO_NAME}}`{% endraw %} reports the name of the repository. For example, `production`. + * {% raw %}`${{CF_BRANCH_TAG_NORMALIZED}}`{% endraw %} reports the normalized version of the branch name or tag based on the JSON payload of the Git repository that triggered the pipeline. For example, `TBD`. (NIMA: Kostis please suggest a good example ) + * {% raw %}`${{CF_PULL_REQUEST_TARGET}}`{% endraw %} reports the target branch of the PR. For example, `TBD`. (NIMA: Kostis please suggest a good example) + * {% raw %}`${{CF_PULL_REQUEST_NUMBER}}`{% endraw %} reports the number of the PR. For example, `#235`. + +{::nomarkdown} +
+{:/} + +#### CF_JRA_MESSAGE examples +TBD ### Example of report image step in Codefresh Classic pipeline diff --git a/_docs/integrations/ci-integrations/examples.md b/_docs/integrations/ci-integrations/examples.md new file mode 100644 index 00000000..7efb8926 --- /dev/null +++ b/_docs/integrations/ci-integrations/examples.md @@ -0,0 +1,42 @@ + + + +### Examples of templatizing arguments + +Some arguments in the CI integrations are populated dunalically when the CI is triggered. You can templatize the values of these arguments to derieve the correct results. +The examples below relate to three arguments you are most likely to templatize and + +### Codefresh Classic +Codefresh Classic provides a list of system variables. Take advantage of these variable to define the value struture of the arguments. +#### CF_IMAGE +1. Example: +**Value syntax** +${{CF_REPO_OWNER}}/${{CF_REPO_NAME}}:${{CF_BRANCH_TAG_NORMALIZED}}-${{CF_SHORT_REVISION}} +where: +${{CF_REPO_OWNER}} will provide the owner of the repository +${{CF_REPO_NAME}} is the name of the repositoru +${{CF_BRANCH_TAG_NORMALIZED}} gets the normalized version of the branch name, without invalid characters in case the branch name was as the Docker image tag name. +${{CF_SHORT_REVISION}} to tag the image with the abbreviated 7-character revision hash, as used in Git. + +**Result in CI image** + + +2. Example: Use a specific image tag +This example illustrates how to define the value when you know the specific image version to use. + +**Value syntax** +%raw ${{CF_REPO_OWNER}}/${{CF_REPO_NAME}}:` +where: +${{CF_REPO_OWNER}} and ${{CF_REPO_NAME}} are the names of the repository owner and the repository respectivley. + is the specific tag to use for the image and is hard-coded. + + +3. Example: Tag image with the latest Git tag available on your repository + +**Templatized value** +`codefresh/${{CF_REPO_NAME}}:latest` +where: +`codefresh` is the hard-coded re +${{CF_REPO_NAME}} is the name of the repository that triggered the integration. + +`latest` tags image with the latest Git tag available for the repository defined by ${{CF_REPO_NAME}}. diff --git a/_docs/integrations/ci-integrations/github-actions.md b/_docs/integrations/ci-integrations/github-actions.md index 2515e44c..5f7bda48 100644 --- a/_docs/integrations/ci-integrations/github-actions.md +++ b/_docs/integrations/ci-integrations/github-actions.md @@ -44,6 +44,75 @@ max-width="50%" For how-to instructions, see [Connect a third-party CI platform/tool to Codefresh]({{site.baseurl}}/docs/integrations/ci-integrations/#connect-a-third-party-ci-platformtool-to-codefresh). +### Example of GitHub Actions in + +#### CF_IMAGE + +**Use case 1: ** + +Value: + +`${{ github.repository }}:${{ github.ref_name }}-${{github.sha}}` + +where: +`${{ github.repository }}` reports the owner of the repository and the name of the repository. For example, `codefresh/hello-world`. +`${{ github.ref_name }}` reports the short reference to the branch that triggered the workflow. For example, `auth-feature-branch`. +`${{github.sha}}` reports the commit SHA that triggered the workflow. + + +**Use Case 2: Use a specific image tag** +This use case illustrates how to define the value for `CF_IMAGE` value when you know the specific image version you want to report. + +Value: +`${{ github.repository }}:` + +where: ` +`${{ github.repository }}` reports the owner of the repository and the name of the repository. For example, `codefresh/hello-world`. +`` reports the hard-coded tag v1.0. + + +**Use case 3: Report the latest Git tag available on repository** + +Value: +`codefresh/${{CF_REPO_NAME}}:latest` + +where: +`codefresh` is the hard-coded re +`${{CF_REPO_NAME}}` reports the name of the repository that triggered the integration. +`latest` reports the latest Git tag available for the repository defined by `${{CF_REPO_NAME}}`. + + +#### CF_GIT_BRANCH + +**Use case 1: Report fully-formed reference of the branch or tag** +This example shows how to report the fully-formed reference of the branch or tag that triggered the workflow run. +For workflows triggered by push events, this is the branch or tag ref that was pushed. +For workflows triggered by pull_requests, this is the pull request merge branch. + +Value: +`${{ github.ref }}` + +Result: +Branch: `refs/heads/production` +Pull request: `refs/pull/#843/merge` + +**Use case 2: Report short reference name of the branch or tag** +This example shows thow to report only the name of the branch or tag that triggered the workflow run, use:`${{ github.ref-name }}`, instead of the full path to the branch. + + +Value: +`${{ github.ref-name }}` + +Result: +`production` +`auth-feature-branch` + +**Use case 3: Report the source of the pull request** +This use casae illustrates how to get the head reference or or source branch of the pull request for pull_request or pull_request_target based events. + +`github.head_ref`??? +`github.job` ????? + ### GitHub Actions pipeline example Here is an example pipeline that uses GitHub Actions to build a container image, and the Codefresh action to enrich and report the resulting image to Codefresh. diff --git a/_docs/integrations/ci-integrations/jenkins.md b/_docs/integrations/ci-integrations/jenkins.md index d80ca8d6..bc30ff01 100644 --- a/_docs/integrations/ci-integrations/jenkins.md +++ b/_docs/integrations/ci-integrations/jenkins.md @@ -40,6 +40,88 @@ The table describes the arguments to connect Codefresh Classic to Codefresh. For how-to instructions, see [Connect a third-party CI platform/tool to Codefresh]({{site.baseurl}}/docs/integrations/ci-integrations/#connect-a-third-party-ci-platform-tool-to-codefresh). +### Templatization examples for CF arguments + +Arguments such as `CF_IMAGE`, `CF_GIT_BRANCH`, and `CF_JIRA_MESSAGE` are populated dynamically when the Jenkins pipeline is triggered. You can templatize the values of these arguments in the pipeline to ensure that the required information is included in the reported image. + +Jenkins offers a Git plugin with [environment variables](https://plugins.jenkins.io/git/#plugin-content-environment-variables){:target="\_blank"} you can use to templatize argument values. + +{::nomarkdown} +
+{:/} + +#### CF_IMAGE +**Example: Report repo, branch with Git hash** +This example illustrates how to define the value for `CF_IMAGE` to report Git repo, branch, committer, and Git hash information. + + Value: + {% raw %}`${env.GIT_COMMITTER_NAME} ${env.GIT_URL}:${env.GIT_BRANCH} ${env.GIT_REVISION}`{% endraw %} + + where: + * {% raw %}`${env.GIT_COMMITTER_NAME}`{% endraw %} reports the name of the user who made the commit. + * {% raw %}`${env.GIT_URL}`{% endraw %} reports the name of the Git repository. + * {% raw %}`${env.GIT_BRANCH}`{% endraw %} reports the name of the Git branch. + * {% raw %}`${env.GIT_REVISION}`{% endraw %} reports the Git SHA1 commit ID pointing to the commit that was built. + + +**Example: Report specific image tag** +This example illustrates how to define the value for `CF_IMAGE` to report a specific image version. + + Value: + {% raw %}`${env.GIT_COMMITTER_NAME}/${env.GIT_URL}:`{% endraw %} + + where: + * {% raw %}`${env.GIT_COMMITTER_NAME}`{% endraw %} and {% raw %}`${env.GIT_URL}`{% endraw %} report the names of the user hwo made the commit and the repository, respectively. + * {% raw %}``{% endraw %} reports the hard-coded tag v1.0. + + +**Example: Report the latest Git tag available on repository** + +This example illustrates how to define the value for `CF_IMAGE` value to report the latest Git tag on the repository. + + Value: + {% raw %}`codefresh/${env.GIT_URL}:latest`{% endraw %} + + where: + * {% raw %}`codefresh`{% endraw %} is the hard-coded re + * {% raw %}`${env.GIT_URL}`{% endraw %} reports the name of the repository that triggered the integration. + * {% raw %}`latest`{% endraw %} reports the latest Git tag available for the repository defined by {% raw %}`${env.GIT_URL}`{% endraw %}. + +{::nomarkdown} +
+{:/} + +#### CF_GIT_BRANCH + +**Example: Report the fully-formed Git branch** +This example illustrates how to define the value for `CF_GIT_BRANCH` value to report the fully-formed Git branch. + + Value: + {% raw %}`${env.GIT_URL}: ${env.GIT_BRANCH}`{% endraw %} + + where: + * {% raw %}`${env.GIT_URL}`{% endraw %} is the name of the repository that triggered the piepline. + * {% raw %}`${env.GIT_BRANCH}`{% endraw %} is the fully-formed name of the Git branch. For example, `origin/auth-feature-branch`. + + +**Example: Report the local Git branch** + +This example illustrates how to define the value for `CF_GIT_BRANCH` value to report only the branch in the repository that triggerred the pipeline. + + Value: + {% raw %}`${env.GIT_URL}: ${env.GIT_LOCAL_BRANCH}`{% endraw %} + + where: + * {% raw %}`${env.GIT_URL}`{% endraw %} is the name of the repository that triggered the piepline. + * {% raw %}`${env.GIT_LOCAL_BRANCH}`{% endraw %} is the name of the Git branch. For example, `auth-feature-branch`. + +{::nomarkdown} +
+{:/} + +#### CF_JIRA_MESSAGE +TBD + ### Example of Jenkins pipeline with report image step From aba57ac851b2ea809f7b5bd98d5f003bf9ce2ed3 Mon Sep 17 00:00:00 2001 From: NimRegev Date: Thu, 20 Oct 2022 16:06:32 +0300 Subject: [PATCH 2/3] Updated examples for all ci integrations --- .../ci-integrations/codefresh-classic.md | 52 ++++++------ .../integrations/ci-integrations/examples.md | 42 ---------- .../ci-integrations/github-actions.md | 81 ++++++++++--------- _docs/integrations/ci-integrations/jenkins.md | 35 ++++---- 4 files changed, 93 insertions(+), 117 deletions(-) delete mode 100644 _docs/integrations/ci-integrations/examples.md diff --git a/_docs/integrations/ci-integrations/codefresh-classic.md b/_docs/integrations/ci-integrations/codefresh-classic.md index 5f9488a3..e57223ee 100644 --- a/_docs/integrations/ci-integrations/codefresh-classic.md +++ b/_docs/integrations/ci-integrations/codefresh-classic.md @@ -8,6 +8,8 @@ toc: true Use Hosted GitOps with any popular Continuous Integration (CI) solution, not just with Codefresh CI. Codefresh Classic is one of the third-party CI platform/tools that you can connect to Codefresh for deployment with image enrichment and reporting. + + For information on how to use the image reporting action in your Codefresh Classic pipeline and how to configure the integration, see [CI Integrations]({{site.baseurl}}/docs/integrations/ci-integrations/). @@ -48,39 +50,40 @@ Codefresh Classic offers [system variables](https://codefresh.io/docs/docs/codef {:/} #### CF_IMAGE examples -**Example: Get full repo and branch information** -This example illustrates how to the value for `CF_IMAGE` to report the repo owner, name, and branch, with the Git hash. +**Example: Report full repo and branch information** +This example illustrates how to define the value for `CF_IMAGE` to report the repo owner, name, and branch, with the Git hash. Value: {% raw %}`${{CF_REPO_OWNER}}/${{CF_REPO_NAME}}:${{CF_BRANCH_TAG_NORMALIZED}}-${{CF_SHORT_REVISION}}`{% endraw %} where: - * {% raw %}`${{CF_REPO_OWNER}}`{% endraw %} reports the owner of the repository. - * {% raw %}`${{CF_REPO_NAME}}`{% endraw %} reports the name of the repository. - * {% raw %}`${{CF_BRANCH_TAG_NORMALIZED}}`{% endraw %} reports the normalized version of the branch name, without invalid characters in case the branch name is the Docker image tag name. - * {% raw %}`${{CF_SHORT_REVISION}}`{% endraw %} reports the abbreviated 7-character revision hash, as used in Git. + * {% raw %}`${{CF_REPO_OWNER}}`{% endraw %} reports the owner of the repository. For example, `nr-codefresh`. + * {% raw %}`${{CF_REPO_NAME}}`{% endraw %} reports the name of the repository. For example, `codefresh-production`. + * {% raw %}`${{CF_BRANCH_TAG_NORMALIZED}}`{% endraw %} reports the normalized version of the branch name, without invalid characters in case the branch name is the Docker image tag name. For example, `pr-2345`, `new-auth-strategy` (branch names without normalization required), and `gcr.io/codefresh-inc/codefresh-io/argo-platform-audit.1.1909.0` (normalized version of original branch name `gcr.io/codefresh-inc/codefresh-io/argo-platform-audit:1.1909.0`). + * {% raw %}`${{CF_SHORT_REVISION}}`{% endraw %} reports the abbreviated 7-character revision hash, as used in Git. For example, `40659e7`. -**Example: Use a specific image tag** -This example illustrates how to define the value for `CF_IMAGE` value to report a specific image version. +**Example: Report a specific image tag** +This example illustrates how to define the value for `CF_IMAGE` value when you know the specific image version you want to report. Value: {% raw %}`{{CF_REPO_OWNER}}/${{CF_REPO_NAME}}:` {% endraw %} where: - * {% raw %}`${{CF_REPO_OWNER}}`{% endraw %} and {% raw %}`${{CF_REPO_NAME}}`{% endraw %} report the names of the repository owner and the repository respectively. - * {% raw %}``{% endraw %} reports the hard-coded tag v1.0. + * {% raw %}`${{CF_REPO_OWNER}}`{% endraw %} and {% raw %}`${{CF_REPO_NAME}}`{% endraw %} report the names of the repository owner and the repository, respectively. For example, `nr-codefresh` and `codefresh-production`, respectively. + * {% raw %}``{% endraw %} reports the hard-coded tag `v1.0`. -**Example: Tag image with the latest Git tag available on repository** +**Example: Report the latest Git tag available on repository** +This example illustrates how to define the value for `CF_IMAGE` value to report the latest Git tag on the repository. Value: {% raw %}`codefresh/${{CF_REPO_NAME}}:latest`{% endraw %} where: * {% raw %}`codefresh`{% endraw %} is the hard-coded owner of the image. -* {% raw %}`${{CF_REPO_NAME}}`{% endraw %} reports the name of the repository that triggered the pipeline. -* {% raw %}`latest`{% endraw %} reports the latest Git tag available for the repository defined by {% raw %}`${{CF_REPO_NAME}}`{% endraw %}. +* {% raw %}`${{CF_REPO_NAME}}`{% endraw %} reports the name of the repository that triggered the pipeline. For example, `codefresh-production`. +* {% raw %}`latest`{% endraw %} reports the latest Git tag available for the repository defined by {% raw %}`${{CF_REPO_NAME}}`{% endraw %}. For example, `v1.0.4-14-g2414721`. {::nomarkdown}
@@ -96,9 +99,9 @@ This example illustrates how to report the name or tag of the Git branch with co {% raw %}`${{CF_REPO_NAME}}/${{CF_BRANCH}}:${{CF_COMMIT_AUTHOR}}/${{CF_COMMIT_MESSAGE}}`{% endraw %} where: - * {% raw %}`${{CF_REPO_NAME}}`{% endraw %} reports the name of the repository. For example, `production`. - * {% raw %}`${{CF_BRANCH}}`{% endraw %} reports the branch name or tag based on the JSON payload of the Git repository that triggered the pipeline. For example, `auth-feature`. - * {% raw %}`${{CF_COMMIT_AUTHOR}}`{% endraw %} reports the name of the user who made the commit. For example, `nr-codefresh`. + * {% raw %}`${{CF_REPO_NAME}}`{% endraw %} reports the name of the repository. For example, `codefresh-production`. + * {% raw %}`${{CF_BRANCH}}`{% endraw %} reports the branch name or tag based on the JSON payload of the Git repository that triggered the pipeline. For example, `new-auth-strategy`. + * {% raw %}`${{CF_COMMIT_AUTHOR}}`{% endraw %} reports the name of the user who made the commit. For example, `cf-support`. * {% raw %}`${{CF_COMMIT_MESSAGE}}`{% endraw %} reports the commit message of the repository. For example, `support oauth authentication for ci integrations`. @@ -112,8 +115,8 @@ Normalizing the branch name removes any invalid characters in the name if the br {% raw %}`${{CF_REPO_NAME}}/${{CF_BRANCH_TAG_NORMALIZED}}:${{CF_COMMIT_AUTHOR}}/${{CF_COMMIT_MESSAGE}}`{% endraw %} where: - * {% raw %}`${{CF_REPO_NAME}}`{% endraw %} reports the name of the repository. For example, `production`. - * {% raw %}`${{CF_BRANCH_TAG_NORMALIZED}}`{% endraw %} reports the normalized version of the branch name or tag based on the JSON payload of the Git repository that triggered the pipeline. (NIMA: Kostis please suggest a good example ) + * {% raw %}`${{CF_REPO_NAME}}`{% endraw %} reports the name of the repository. For example, `codefresh-production`. + * {% raw %}`${{CF_BRANCH_TAG_NORMALIZED}}`{% endraw %} reports the normalized version of the branch name or tag based on the JSON payload of the Git repository that triggered the pipeline. * {% raw %}`${{CF_COMMIT_AUTHOR}}`{% endraw %} reports the name of the user who made the commit. For example, `nr-codefresh`. * {% raw %}`${{CF_COMMIT_MESSAGE}}`{% endraw %}reports the commit message of the repository. For example, `support oauth authentication for ci integrations`. @@ -127,16 +130,19 @@ Value: where: * {% raw %}`${{CF_REPO_NAME}}`{% endraw %} reports the name of the repository. For example, `production`. - * {% raw %}`${{CF_BRANCH_TAG_NORMALIZED}}`{% endraw %} reports the normalized version of the branch name or tag based on the JSON payload of the Git repository that triggered the pipeline. For example, `TBD`. (NIMA: Kostis please suggest a good example ) - * {% raw %}`${{CF_PULL_REQUEST_TARGET}}`{% endraw %} reports the target branch of the PR. For example, `TBD`. (NIMA: Kostis please suggest a good example) - * {% raw %}`${{CF_PULL_REQUEST_NUMBER}}`{% endraw %} reports the number of the PR. For example, `#235`. + * {% raw %}`${{CF_BRANCH_TAG_NORMALIZED}}`{% endraw %} reports the normalized version of the branch name or tag based on the JSON payload of the Git repository that triggered the pipeline. For example, `pr-2345`, `new-auth-strategy` (branch names without normalization required), and `gcr.io/codefresh-inc/codefresh-io/argo-platform-audit.1.1909.0` (normalized version of original branch name `gcr.io/codefresh-inc/codefresh-io/argo-platform-audit:1.1909.0`). + * {% raw %}`${{CF_PULL_REQUEST_TARGET}}`{% endraw %} reports the target branch of the PR. For example, `new-auth-strategy`. + * {% raw %}`${{CF_PULL_REQUEST_NUMBER}}`{% endraw %} reports the number of the PR. For example, `#323`. {::nomarkdown}
{:/} -#### CF_JRA_MESSAGE examples -TBD +#### CF_JIRA_MESSAGE examples +The Jira message represents an existing Jira issue, and must be a literal string. + + Value: + `CR-1246` ### Example of report image step in Codefresh Classic pipeline diff --git a/_docs/integrations/ci-integrations/examples.md b/_docs/integrations/ci-integrations/examples.md deleted file mode 100644 index 7efb8926..00000000 --- a/_docs/integrations/ci-integrations/examples.md +++ /dev/null @@ -1,42 +0,0 @@ - - - -### Examples of templatizing arguments - -Some arguments in the CI integrations are populated dunalically when the CI is triggered. You can templatize the values of these arguments to derieve the correct results. -The examples below relate to three arguments you are most likely to templatize and - -### Codefresh Classic -Codefresh Classic provides a list of system variables. Take advantage of these variable to define the value struture of the arguments. -#### CF_IMAGE -1. Example: -**Value syntax** -${{CF_REPO_OWNER}}/${{CF_REPO_NAME}}:${{CF_BRANCH_TAG_NORMALIZED}}-${{CF_SHORT_REVISION}} -where: -${{CF_REPO_OWNER}} will provide the owner of the repository -${{CF_REPO_NAME}} is the name of the repositoru -${{CF_BRANCH_TAG_NORMALIZED}} gets the normalized version of the branch name, without invalid characters in case the branch name was as the Docker image tag name. -${{CF_SHORT_REVISION}} to tag the image with the abbreviated 7-character revision hash, as used in Git. - -**Result in CI image** - - -2. Example: Use a specific image tag -This example illustrates how to define the value when you know the specific image version to use. - -**Value syntax** -%raw ${{CF_REPO_OWNER}}/${{CF_REPO_NAME}}:` -where: -${{CF_REPO_OWNER}} and ${{CF_REPO_NAME}} are the names of the repository owner and the repository respectivley. - is the specific tag to use for the image and is hard-coded. - - -3. Example: Tag image with the latest Git tag available on your repository - -**Templatized value** -`codefresh/${{CF_REPO_NAME}}:latest` -where: -`codefresh` is the hard-coded re -${{CF_REPO_NAME}} is the name of the repository that triggered the integration. - -`latest` tags image with the latest Git tag available for the repository defined by ${{CF_REPO_NAME}}. diff --git a/_docs/integrations/ci-integrations/github-actions.md b/_docs/integrations/ci-integrations/github-actions.md index 5f7bda48..3403adc4 100644 --- a/_docs/integrations/ci-integrations/github-actions.md +++ b/_docs/integrations/ci-integrations/github-actions.md @@ -44,74 +44,83 @@ max-width="50%" For how-to instructions, see [Connect a third-party CI platform/tool to Codefresh]({{site.baseurl}}/docs/integrations/ci-integrations/#connect-a-third-party-ci-platformtool-to-codefresh). -### Example of GitHub Actions in +### Templatization examples for CF arguments + +Arguments such as `CF_IMAGE`, `CF_GIT_BRANCH`, and `CF_JIRA_MESSAGE` are populated dynamically when the GitHub Actions pipeline is triggered. You can templatize the values of these arguments to ensure that the required information is included in the reported image. + +See GitHub Actions [environment variables](https://docs.github.com/en/actions/learn-github-actions/environment-variables#default-environment-variables) you can use to templatize argument values. + +{::nomarkdown} +
+{:/} #### CF_IMAGE -**Use case 1: ** +**Example: Report full repo and branch information** +This example illustrates how to define the value for `CF_IMAGE` to report the repo owner, name, and short branch, with the Git hash. -Value: + Value: -`${{ github.repository }}:${{ github.ref_name }}-${{github.sha}}` + {% raw %}}`${{ github.repository }}/${{ github.ref_name }}/${{github.sha}}`{% endraw %} + + where: + * {% raw %}`${{ github.repository }}`{% endraw %} reports the owner of the repository and the name of the repository. For example, `nr-codefresh/codefresh-production`. + * {% raw %}`${{ github.ref_name }}`{% endraw %} reports the short reference to the branch that triggered the workflow. For example, `auth-feature-branch`. + * {% raw %}`${{github.sha}}`{% endraw %} reports the complete commit SHA that triggered the workflow. For example, `fa53bfa91df14c4c9f46e628a65ee21dd574490a`. -where: -`${{ github.repository }}` reports the owner of the repository and the name of the repository. For example, `codefresh/hello-world`. -`${{ github.ref_name }}` reports the short reference to the branch that triggered the workflow. For example, `auth-feature-branch`. -`${{github.sha}}` reports the commit SHA that triggered the workflow. -**Use Case 2: Use a specific image tag** -This use case illustrates how to define the value for `CF_IMAGE` value when you know the specific image version you want to report. +**Example: Report a specific image tag** +This example illustrates how to define the value for `CF_IMAGE` when you know the specific image version you want to report. Value: -`${{ github.repository }}:` +{% raw %}`${{ github.repository }}:`{% endraw %} -where: ` -`${{ github.repository }}` reports the owner of the repository and the name of the repository. For example, `codefresh/hello-world`. -`` reports the hard-coded tag v1.0. +where: +* {% raw %}`${{ github.repository }}`{% endraw %} reports the owner of the repository and the name of the repository. For example, `nr-codefresh/codefresh-production`. +* `` reports the hard-coded tag `v1.0`. -**Use case 3: Report the latest Git tag available on repository** +**Example: Report the latest Git tag available on repository** +This example illustrates how to define the value for `CF_IMAGE` to report the latest Git tag on the repository. Value: -`codefresh/${{CF_REPO_NAME}}:latest` +{% raw %}`codefresh/${{ github.repository }}/latest`{% endraw %} -where: -`codefresh` is the hard-coded re -`${{CF_REPO_NAME}}` reports the name of the repository that triggered the integration. -`latest` reports the latest Git tag available for the repository defined by `${{CF_REPO_NAME}}`. +where: +* {% raw %}`codefresh`{% endraw %} is the hard-coded owner of the image. +* {% raw %}`${{ github.repository }}`{% endraw %} reports the owner of the repository and the name of the repository. For example, `nr-codefresh/codefresh-production`. +* {% raw %}`latest`{% endraw %} reports the latest Git tag available for the repository defined by {% raw %}`${{ github.repository }}`{% endraw %}. For example, `v1.0.4-14-g2414721`. #### CF_GIT_BRANCH -**Use case 1: Report fully-formed reference of the branch or tag** -This example shows how to report the fully-formed reference of the branch or tag that triggered the workflow run. +**Example: Report fully-formed reference of the branch or tag** +This example illustrates how to define the value for `CF_GIT_BRANCH` to report the fully-formed reference of the branch or tag that triggered the workflow run. For workflows triggered by push events, this is the branch or tag ref that was pushed. For workflows triggered by pull_requests, this is the pull request merge branch. Value: -`${{ github.ref }}` +{% raw %}`${{ github.ref }}`{% endraw %} -Result: -Branch: `refs/heads/production` -Pull request: `refs/pull/#843/merge` +where: +* {% raw %}`${{ github.ref }}`{% endraw %} is the reference to the branch or tag. For example, `refs/heads/auth-feature-branch` (branch), and `refs/pull/#843/merge` (pull request). -**Use case 2: Report short reference name of the branch or tag** -This example shows thow to report only the name of the branch or tag that triggered the workflow run, use:`${{ github.ref-name }}`, instead of the full path to the branch. +**Example: Report short reference name of the branch or tag** +This example illustrates how to define the value for `CF_GIT_BRANCH` to report only the name of the branch or tag that triggered the workflow run. Value: -`${{ github.ref-name }}` +{% raw %}`${{ github.ref-name }}`{% endraw %} -Result: -`production` -`auth-feature-branch` +where: +{% raw %}`${{ github.ref-name }}`{% endraw %} is the name of the target branch or tag. For example, `auth-feature-branch`. -**Use case 3: Report the source of the pull request** -This use casae illustrates how to get the head reference or or source branch of the pull request for pull_request or pull_request_target based events. +#### CF_JIRA_MESSAGE +The Jira message represents an existing Jira issue, and must be a literal string. -`github.head_ref`??? -`github.job` ????? + Value: + `CR-1246` ### GitHub Actions pipeline example diff --git a/_docs/integrations/ci-integrations/jenkins.md b/_docs/integrations/ci-integrations/jenkins.md index bc30ff01..f1fa5723 100644 --- a/_docs/integrations/ci-integrations/jenkins.md +++ b/_docs/integrations/ci-integrations/jenkins.md @@ -55,24 +55,24 @@ Jenkins offers a Git plugin with [environment variables](https://plugins.jenkins This example illustrates how to define the value for `CF_IMAGE` to report Git repo, branch, committer, and Git hash information. Value: - {% raw %}`${env.GIT_COMMITTER_NAME} ${env.GIT_URL}:${env.GIT_BRANCH} ${env.GIT_REVISION}`{% endraw %} + {% raw %}`${env.GIT_COMMITTER_NAME}/${env.GIT_URL}/${env.GIT_BRANCH}/${env.GIT_REVISION}`{% endraw %} where: - * {% raw %}`${env.GIT_COMMITTER_NAME}`{% endraw %} reports the name of the user who made the commit. - * {% raw %}`${env.GIT_URL}`{% endraw %} reports the name of the Git repository. - * {% raw %}`${env.GIT_BRANCH}`{% endraw %} reports the name of the Git branch. - * {% raw %}`${env.GIT_REVISION}`{% endraw %} reports the Git SHA1 commit ID pointing to the commit that was built. + * {% raw %}`${env.GIT_COMMITTER_NAME}`{% endraw %} reports the name of the user who made the commit. For example, `nr-codefresh`. + * {% raw %}`${env.GIT_URL}`{% endraw %} reports the name of the Git repository. For example, `codefresh-production`. + * {% raw %}`${env.GIT_BRANCH}`{% endraw %} reports the name of the Git branch. For example, `pr-2345`, `new-auth-strategy`. + * {% raw %}`${env.GIT_REVISION}`{% endraw %} reports the Git SHA1 commit ID pointing to the commit that was built. For example, `fa53bfa91df14c4c9f46e628a65ee21dd574490a`. -**Example: Report specific image tag** -This example illustrates how to define the value for `CF_IMAGE` to report a specific image version. +**Example: Report a specific image tag** +This example illustrates how to define the value for `CF_IMAGE` when you know the specific image version you want to report. Value: - {% raw %}`${env.GIT_COMMITTER_NAME}/${env.GIT_URL}:`{% endraw %} + {% raw %}`${env.GIT_COMMITTER_NAME}/${env.GIT_URL}/`{% endraw %} where: - * {% raw %}`${env.GIT_COMMITTER_NAME}`{% endraw %} and {% raw %}`${env.GIT_URL}`{% endraw %} report the names of the user hwo made the commit and the repository, respectively. - * {% raw %}``{% endraw %} reports the hard-coded tag v1.0. + * {% raw %}`${env.GIT_COMMITTER_NAME}`{% endraw %} and {% raw %}`${env.GIT_URL}`{% endraw %} report the names of the user hwo made the commit and the repository, respectively. For example, `nr-codefresh` and `codefresh-production`, respectively. + * {% raw %}``{% endraw %} reports the hard-coded tag `v1.0`. **Example: Report the latest Git tag available on repository** @@ -80,12 +80,12 @@ This example illustrates how to define the value for `CF_IMAGE` to report a spec This example illustrates how to define the value for `CF_IMAGE` value to report the latest Git tag on the repository. Value: - {% raw %}`codefresh/${env.GIT_URL}:latest`{% endraw %} + {% raw %}`codefresh/${env.GIT_URL}/latest`{% endraw %} where: * {% raw %}`codefresh`{% endraw %} is the hard-coded re * {% raw %}`${env.GIT_URL}`{% endraw %} reports the name of the repository that triggered the integration. - * {% raw %}`latest`{% endraw %} reports the latest Git tag available for the repository defined by {% raw %}`${env.GIT_URL}`{% endraw %}. + * {% raw %}`latest`{% endraw %} reports the latest Git tag available for the repository defined by {% raw %}`${env.GIT_URL}`{% endraw %}. For example, `v1.0.4-14-g2414721`. {::nomarkdown}
@@ -97,10 +97,10 @@ This example illustrates how to define the value for `CF_IMAGE` value to report This example illustrates how to define the value for `CF_GIT_BRANCH` value to report the fully-formed Git branch. Value: - {% raw %}`${env.GIT_URL}: ${env.GIT_BRANCH}`{% endraw %} + {% raw %}`${env.GIT_URL}/${env.GIT_BRANCH}`{% endraw %} where: - * {% raw %}`${env.GIT_URL}`{% endraw %} is the name of the repository that triggered the piepline. + * {% raw %}`${env.GIT_URL}`{% endraw %} is the name of the repository that triggered the pipeline. For example, `codefresh-production`. * {% raw %}`${env.GIT_BRANCH}`{% endraw %} is the fully-formed name of the Git branch. For example, `origin/auth-feature-branch`. @@ -109,7 +109,7 @@ This example illustrates how to define the value for `CF_GIT_BRANCH` value to re This example illustrates how to define the value for `CF_GIT_BRANCH` value to report only the branch in the repository that triggerred the pipeline. Value: - {% raw %}`${env.GIT_URL}: ${env.GIT_LOCAL_BRANCH}`{% endraw %} + {% raw %}`${env.GIT_URL}/${env.GIT_LOCAL_BRANCH}`{% endraw %} where: * {% raw %}`${env.GIT_URL}`{% endraw %} is the name of the repository that triggered the piepline. @@ -120,7 +120,10 @@ This example illustrates how to define the value for `CF_GIT_BRANCH` value to re {:/} #### CF_JIRA_MESSAGE -TBD +The Jira message represents an existing Jira issue, and must be a literal string. + + Value: + `CR-1246` ### Example of Jenkins pipeline with report image step From 1c7b50a574bb5ab61ee385e1dba283bdf0762eae Mon Sep 17 00:00:00 2001 From: NimRegev Date: Thu, 20 Oct 2022 16:18:22 +0300 Subject: [PATCH 3/3] Update examples for CI integrations Formatting fixes --- .../ci-integrations/codefresh-classic.md | 4 +-- .../ci-integrations/github-actions.md | 26 ++++++++++++------- _docs/integrations/ci-integrations/jenkins.md | 4 +-- 3 files changed, 18 insertions(+), 16 deletions(-) diff --git a/_docs/integrations/ci-integrations/codefresh-classic.md b/_docs/integrations/ci-integrations/codefresh-classic.md index e57223ee..a0c358cc 100644 --- a/_docs/integrations/ci-integrations/codefresh-classic.md +++ b/_docs/integrations/ci-integrations/codefresh-classic.md @@ -54,7 +54,6 @@ Codefresh Classic offers [system variables](https://codefresh.io/docs/docs/codef This example illustrates how to define the value for `CF_IMAGE` to report the repo owner, name, and branch, with the Git hash. Value: - {% raw %}`${{CF_REPO_OWNER}}/${{CF_REPO_NAME}}:${{CF_BRANCH_TAG_NORMALIZED}}-${{CF_SHORT_REVISION}}`{% endraw %} where: @@ -71,8 +70,7 @@ This example illustrates how to define the value for `CF_IMAGE` value when you k where: * {% raw %}`${{CF_REPO_OWNER}}`{% endraw %} and {% raw %}`${{CF_REPO_NAME}}`{% endraw %} report the names of the repository owner and the repository, respectively. For example, `nr-codefresh` and `codefresh-production`, respectively. - * {% raw %}``{% endraw %} reports the hard-coded tag `v1.0`. - + * {% raw %}``{% endraw %} reports the hard-coded tag `v1.0`. **Example: Report the latest Git tag available on repository** This example illustrates how to define the value for `CF_IMAGE` value to report the latest Git tag on the repository. diff --git a/_docs/integrations/ci-integrations/github-actions.md b/_docs/integrations/ci-integrations/github-actions.md index 3403adc4..a66f1795 100644 --- a/_docs/integrations/ci-integrations/github-actions.md +++ b/_docs/integrations/ci-integrations/github-actions.md @@ -60,20 +60,19 @@ See GitHub Actions [environment variables](https://docs.github.com/en/actions/le This example illustrates how to define the value for `CF_IMAGE` to report the repo owner, name, and short branch, with the Git hash. Value: - - {% raw %}}`${{ github.repository }}/${{ github.ref_name }}/${{github.sha}}`{% endraw %} + {% raw %}`${{ github.repository }}/${{ github.ref_name }}/${{ github.sha }}`{% endraw %} where: * {% raw %}`${{ github.repository }}`{% endraw %} reports the owner of the repository and the name of the repository. For example, `nr-codefresh/codefresh-production`. * {% raw %}`${{ github.ref_name }}`{% endraw %} reports the short reference to the branch that triggered the workflow. For example, `auth-feature-branch`. - * {% raw %}`${{github.sha}}`{% endraw %} reports the complete commit SHA that triggered the workflow. For example, `fa53bfa91df14c4c9f46e628a65ee21dd574490a`. + * {% raw %}`${{ github.sha }}`{% endraw %} reports the complete commit SHA that triggered the workflow. For example, `fa53bfa91df14c4c9f46e628a65ee21dd574490a`. -**Example: Report a specific image tag** +**Example: Report a specific image tag** This example illustrates how to define the value for `CF_IMAGE` when you know the specific image version you want to report. -Value: +Value: {% raw %}`${{ github.repository }}:`{% endraw %} where: @@ -92,29 +91,36 @@ where: * {% raw %}`${{ github.repository }}`{% endraw %} reports the owner of the repository and the name of the repository. For example, `nr-codefresh/codefresh-production`. * {% raw %}`latest`{% endraw %} reports the latest Git tag available for the repository defined by {% raw %}`${{ github.repository }}`{% endraw %}. For example, `v1.0.4-14-g2414721`. +{::nomarkdown} +
+{:/} #### CF_GIT_BRANCH -**Example: Report fully-formed reference of the branch or tag** +**Example: Report fully-formed reference of the branch or tag** This example illustrates how to define the value for `CF_GIT_BRANCH` to report the fully-formed reference of the branch or tag that triggered the workflow run. For workflows triggered by push events, this is the branch or tag ref that was pushed. For workflows triggered by pull_requests, this is the pull request merge branch. -Value: +Value: {% raw %}`${{ github.ref }}`{% endraw %} where: * {% raw %}`${{ github.ref }}`{% endraw %} is the reference to the branch or tag. For example, `refs/heads/auth-feature-branch` (branch), and `refs/pull/#843/merge` (pull request). -**Example: Report short reference name of the branch or tag** +**Example: Report short reference name of the branch or tag** This example illustrates how to define the value for `CF_GIT_BRANCH` to report only the name of the branch or tag that triggered the workflow run. -Value: +Value: {% raw %}`${{ github.ref-name }}`{% endraw %} where: -{% raw %}`${{ github.ref-name }}`{% endraw %} is the name of the target branch or tag. For example, `auth-feature-branch`. +* {% raw %}`${{ github.ref-name }}`{% endraw %} is the name of the target branch or tag. For example, `auth-feature-branch`. + +{::nomarkdown} +
+{:/} #### CF_JIRA_MESSAGE The Jira message represents an existing Jira issue, and must be a literal string. diff --git a/_docs/integrations/ci-integrations/jenkins.md b/_docs/integrations/ci-integrations/jenkins.md index f1fa5723..e831af0b 100644 --- a/_docs/integrations/ci-integrations/jenkins.md +++ b/_docs/integrations/ci-integrations/jenkins.md @@ -76,7 +76,6 @@ This example illustrates how to define the value for `CF_IMAGE` when you know th **Example: Report the latest Git tag available on repository** - This example illustrates how to define the value for `CF_IMAGE` value to report the latest Git tag on the repository. Value: @@ -93,7 +92,7 @@ This example illustrates how to define the value for `CF_IMAGE` value to report #### CF_GIT_BRANCH -**Example: Report the fully-formed Git branch** +**Example: Report the fully-formed Git branch** This example illustrates how to define the value for `CF_GIT_BRANCH` value to report the fully-formed Git branch. Value: @@ -105,7 +104,6 @@ This example illustrates how to define the value for `CF_GIT_BRANCH` value to re **Example: Report the local Git branch** - This example illustrates how to define the value for `CF_GIT_BRANCH` value to report only the branch in the repository that triggerred the pipeline. Value: