GitOps GitHub Actions integration

Use Hosted GitOps with any popular Continuous Integration (CI) solution, not just with Codefresh CI.
GitHub Actions is one of the third-party CI solutions that you can connect to Hosted GitOps for deployment with image reporting and enrichment.

Connecting a GitHub Action, adds the CI information to images which are displayed in the Images dashboard, as in the example below.

Images dashboard with enriched image information

Images dashboard with enriched image information

For information on how to use the image reporting action in your GitHub Action pipeline and how to configure the integration, see CI Integrations.

Example of GitHub Actions pipeline with Codefresh report image action

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.

Because a Jira integration account is configured in Codefresh, the step needs only the name for CF_JIRA_INTEGRATION, instead of explicit credentials CF_JIRA_API_TOKEN, CF_JIRA_HOST_URL, and CF_JIRA_EMAIL.

name: Docker Image CI

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]
jobs:
  build:
    environment:
      name: test
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Login to DockerHub
        uses: docker/login-action@v2
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}
      - name: Build & push the Docker image
        env:
          CF_IMAGE: docker.io/${{ secrets.DOCKERHUB_USERNAME }}/build-by-github-action:0.0.1
        run: |
          docker build . --file Dockerfile --tag $CF_IMAGE && docker push $CF_IMAGE
          echo "Image should be accessible to your local machine (after docker login) by:"
          echo "docker pull $CF_IMAGE"
          docker pull $CF_IMAGE
          echo "On the next step, the report image would use the integration to pull information on the reported image, using the specified enrichers."
      - name: report image by action
        with:
          # Name of runtime to implement the enrichment
          CF_RUNTIME_NAME: 'codefresh-hosted'

          # Codefresh API key !! Committing a plain text token is a security risk. We highly recommend using encrypted secrets. !!
          # Documentation - https://docs.github.com/en/actions/security-guides/encrypted-secrets
          CF_API_KEY: ${{ secrets.USER_TOKEN }}

          # Name of Container registry integration
          CF_CONTAINER_REGISTRY_INTEGRATION: 'docker'

          # The git branch which is related for the commit
          CF_GIT_BRANCH: 'main'

          # Image path to enrich 
          CF_IMAGE: docker.io/${{ secrets.DOCKERHUB_USERNAME }}/build-by-github-action:0.0.1

          # GitHub Access token !! Committing a plain text token is a security risk. We highly recommend using encrypted secrets. !!
          # Documentation - https://docs.github.com/en/actions/security-guides/encrypted-secrets
          CF_GITHUB_TOKEN: ${{ secrets.CF_GITHUB_TOKEN }}    

          # Name of Jira integration
          CF_ISSUE_TRACKING_INTEGRATION: 'jira' 

         # String starting with the issue ID to associate with image
          CF_JIRA_MESSAGE: 'CR-11027'

          # Jira project filter
          CF_JIRA_PROJECT_PREFIX: "CR"
        uses: codefresh-io/codefresh-report-image@latest
        
        

GitHub Action-GitOps integration settings

The table describes the arguments required to connect a GitHub Action to Codefresh.

Argument Description Required/Optional/Default
CF_HOST Deprecated from v 0.0.460 and higher. Recommend using CF_RUNTIME_NAME instead.
CF_HOST has been deprecated because the URL is not static, and any change can fail the enrichment.

The URL to the cluster with the Codefresh runtime to integrate with. If you have more than one runtime, select the runtime from the list. Codefresh displays the URL of the selected runtime cluster.
Required
CF_RUNTIME_NAME The runtime to use for the integration. If you have more than one runtime, select the runtime from the list. Required
CF_API_KEY The API key with which to authenticate the GitHub Actions user to Codefresh. Generate a valid API key for the GitHub Action. The key does not require any specific scopes. See Create and manage API keys.
Enter this token in GitHub Actions as a secret with the name CF_API_KEY. You can then reference it in all GitHub pipelines as you would any other secret.
Required
CF_CONTAINER_REGISTRY_INTEGRATION The name of the container registry integration created in Codefresh where the image is stored.
  • For a GitHub Container registry, select GHCR_GITHUB_TOKEN_AUTHENTICATION even if you have not created an integration in Codefresh.
    Codefresh retrieves and provides the explicit credentials for the container registry on generating the integration manifest.
  • To create a container registry integration in Codefresh, if you don't have one, click Create Container Registry Integration, and then configure the settings.
    See Container registry integrations.
  • Alternatively, you can use one of these container registries with explicit credentials:
    • DockerHub registry with CF_DOCKERHUB_USERNAME and CF_DOCKERHUB_PASSWORD.
    • Docker Registry Protocol v2 with CF_REGISTRY_DOMAIN, CF_REGISTRY_USERNAME, and CF_REGISTRY_PASSWORD.
    • Google Artifact Registry (GAR) with CF_GOOGLE_JSON_KEY and CF_GOOGLE_REGISTRY_HOST.
Optional
CF_DOCKERHUB_USERNAME Relevant only to provide explicit credentials to the Docker Hub container registry where the image is stored.
The username for the Docker Hub container registry.

To use a Docker Hub container registry integration created in Codefresh, set CF_CONTAINER_REGISTRY_INTEGRATION instead.
Optional
CF_DOCKERHUB_PASSWORD Relevant only if CF_DOCKERHUB_USERNAME is specified.
The password for the Docker Hub container registry.
Optional
CF_REGISTRY_USERNAME Relevant for container registries that support Docker Registry Protocol v2.
The username for the Docker Registry Protocol v2 container registry.

To use a container registry integration created in Codefresh, set CF_CONTAINER_REGISTRY_INTEGRATION instead.
Optional
CF_REGISTRY_PASSWORD Relevant only if CF_REGISTRY_USERNAME is specified.
The password for the Docker Registry Protocol v2 container registry.
Optional
CF_REGISTRY_DOMAIN Relevant only if CF_REGISTRY_USERNAME and CF_REGISTRY_PASSWORD are specified.
The domain for the Docker Registry Protocol v2 container registry.
Optional
CF_GOOGLE_JSON_KEY Relevant only for Google Artifact Registry (GAR) or Google Container Registry (GCR).
The Google Cloud Platform Service Account key in JSON format to authenticate to GAR or GCR.
Optional
CF_GOOGLE_REGISTRY_HOST Relevant only if CF_GOOGLE_JSON_KEY is specified.
The GAR or GCR host.
For example, us-central1-docker.pkg.dev or gcr.io.
Optional
CF_GIT_REPO The Git repository with the configuration and code used to build the image. If not defined, Codefresh retrieves it from the repo defined for the GitHub Action. Required
CF_JIRA_INTEGRATION Deprecated from version 0.0.565. Replaced by CF_ISSUE_TRACKING_INTEGRATION. Deprecated
CF_ISSUE_TRACKING_INTEGRATION The name of the issue tracking integration created in Codefresh to use to enrich the image. Relevant only if Jira enrichment is required for the image. If you don’t have a Jira integration, click Create Atlassian Jira Integration and configure settings. See Jira integration. Optional
CF_IMAGE The image to be enriched and reported in Codefresh. Pass the [account-name]/[image-name]:[tag] built in your CI. Required
CF_WORKFLOW_NAME The name assigned to the workflow that builds the image. When defined, the name is displayed in the Codefresh platform. Example, Staging step Optional
CF_GIT_BRANCH The Git branch with the commit and PR (pull request) data to add to the image. Pass the Branch from the event payload used to trigger your action. Required
CF_GITHUB_TOKEN The GitHub authentication token. See Git user token scopes. Required
CF_GERRIT_CHANGE_ID Relevant only for Gerrit accounts.
The change ID or the commit message containing the Change ID to add to the image. For Gerrit, use this instead of CF_GIT_BRANCH.
Required
CF_GERRIT_HOST_URL Relevant only for Gerrit accounts.
The URL of your website with the Gerrit instance, for example, https://git.company-name.io.
Required
CF_GERRIT_USERNAME Relevant only for Gerrit accounts.
The username for your user account in Gerrit.
Required
CF_GERRIT_PASSWORD Relevant only for Gerrit accounts.
The HTTP password for your user account in Gerrit, to use as the access token to authenticate HTTP requests to Gerrit.
Required
CF_JIRA_PROJECT_PREFIX Relevant only when CF_ISSUE_TRACKING_INTEGRATION is defined. One or more project prefixes in Jira to identify the Jira ticket number to use.
NOTE: Multiple project prefixes require version 0.1.30 or higher.
To specify more than one prefix, use a comma-separated list or a regex.
  • Comma-separated list: DEV,PROD,SAAS
  • Regex: Regex must start with a front slash / and end with /g.
    Example: /[A-Z]{2,}-\d+/g.
Required
CF_JIRA_MESSAGE Relevant only when CF_ISSUE_TRACKING_INTEGRATION is defined. The Jira issue IDs matching the string to associate with the image. Required
CF_JIRA_FAIL_ON_NOT_FOUND Relevant only when CF_ISSUE_TRACKING_INTEGRATION is defined. The report image action when the CF_JIRA_MESSAGE is not found. When set to true, the report image action is failed. Required

For how-to instructions, see 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 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 you can use to templatize argument values.

CF_IMAGE

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:
${{ github.repository }}/${{ github.ref_name }}/${{ github.sha }}

where:

  • ${{ github.repository }} reports the owner of the repository and the name of the repository. For example, nr-codefresh/codefresh-production.
  • ${{ github.ref_name }} reports the short reference to the branch that triggered the workflow. For example, auth-feature-branch.
  • ${{ github.sha }} reports the complete commit SHA that triggered the workflow. For example, fa53bfa91df14c4c9f46e628a65ee21dd574490a.
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 }}:<v1.0>

where:

  • ${{ github.repository }} reports the owner of the repository and the name of the repository. For example, nr-codefresh/codefresh-production.
  • <v1.0> 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 to report the latest Git tag on the repository.

Value:
codefresh/${{ github.repository }}/latest

where:

  • codefresh is the hard-coded owner of the image.
  • ${{ github.repository }} reports the owner of the repository and the name of the repository. For example, nr-codefresh/codefresh-production.
  • latest reports the latest Git tag available for the repository defined by ${{ github.repository }}. For example, v1.0.4-14-g2414721.

CF_GIT_BRANCH

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 }}

where:

  • ${{ github.ref }} 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

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 }}

where:

  • ${{ github.ref_name }} is the name of the target branch or tag. For example, auth-feature-branch.

CF_JIRA_MESSAGE

The Jira message represents an existing Jira issue, and must be a literal string.

Value:
CR-1246

GitHub Action logs

View and analyze logs for GitHub Action workflows through the Logs tab. When a GitHub Action is run, it is added to the Logs tab.
You can:

  • Filter by status or by date range to view a subset of actions
  • Navigate to the build file in GitHub Actions, and view the Codefresh report image step

GitHub Action: Logs tab

GitHub Action: Logs tab
Build YAML in GitHub Action

The Run column includes the link to the build files for the actions.

Here are examples of the build file for the GitHub Action (top) and of the Codefresh report image step in the action (down).

Build file in GitHub Action

Build file in GitHub Action

Codefresh report image step in GitHub Action build file

Codefresh report image step in GitHub Action build file

Shared Configuration Repository
Image enrichment with GitOps integrations
Container registry GitOps integrations
Issue-tracking GitOps integrations