github.com/Racer159/jackal@v0.32.7-0.20240401174413-0bd2339e4f2e/examples/git-data/README.md (about)

     1  import ExampleYAML from "@site/src/components/ExampleYAML";
     2  
     3  # Git Repositories
     4  
     5  This example shows how to package `git` repositories within a Jackal package.  This package does not deploy anything itself but pushes assets to the specified `git` service to be consumed as desired.  Within Jackal, there are a few ways to include `git` repositories (as described below).
     6  
     7  :::tip
     8  
     9  Git repositories included in a package can be deployed with `jackal package deploy` if an existing Kubernetes cluster has been initialized with `jackal init`.  If you do not have an initialized cluster but want to push resources to a remote registry anyway, you can use [`jackal package mirror-resources`](./../../docs/2-the-jackal-cli/100-cli-commands/jackal_package_mirror-resources.md).
    10  
    11  :::
    12  
    13  ## Tag-Based Git Repository Clone
    14  
    15  Tag-based `git` repository cloning is the **recommended** way of cloning a `git` repository for air-gapped deployments because it wraps meaning around a specific point in git history that can easily be traced back to the online world. Tag-based clones are defined using the `scheme://host/repo@tag` format as seen in the example of the `Racer159/jackal` repository (`https://github.com/Racer159/jackal.git@v0.15.0`).
    16  
    17  A tag-based clone only mirrors the tag defined in the Jackal definition. The tag will be applied on the `git` mirror to a jackal-specific branch name based on the tag name (e.g. the tag `v0.1.0` will be pushed to the `jackal-ref-v0.1.0` branch).  This ensures that this tag will be pushed and received properly by the airgap `git` server.
    18  
    19  :::note
    20  
    21  If you would like to use a protocol scheme other than http/https, you can do so with something like the following: `ssh://git@github.com/Racer159/jackal.git@v0.15.0`.  Using this you can also clone from a local repo to help you manage larger git repositories: `file:///home/jackal/workspace/jackal@v0.15.0`.
    22  
    23  :::
    24  
    25  :::caution
    26  
    27  Because Jackal creates long-lived mirrors of repositories in the air gap, it does not support shallow clones (i.e. `git clone --depth x`).  These may be present in build environments (i.e. [GitLab runners](https://github.com/Racer159/jackal/issues/1698)) and should be avoided.  To learn more about shallow and partial clones see the [GitHub blog on the topic](https://github.blog/2020-12-21-get-up-to-speed-with-partial-clone-and-shallow-clone).
    28  
    29  :::
    30  
    31  ## SHA-Based Git Repository Clone
    32  
    33  In addition to tags, Jackal also supports cloning and pushing a specific SHA hash from a `git` repository, but this is **not recommended** as it is less readable/understandable than tag cloning.  Commit SHAs are defined using the same `scheme://host/repo@shasum` format as seen in the example of the `Racer159/jackal` repository (`https://github.com/Racer159/jackal.git@c74e2e9626da0400e0a41e78319b3054c53a5d4e`).
    34  
    35  A SHA-based clone only mirrors the SHA hash defined in the Jackal definition. The SHA will be applied on the `git` mirror to a jackal-specific branch name based on the SHA hash (e.g. the SHA `c74e2e9626da0400e0a41e78319b3054c53a5d4e` will be pushed to the `jackal-ref-c74e2e9626da0400e0a41e78319b3054c53a5d4e` branch).  This ensures that this tag will be pushed and received properly by the airgap `git` server.
    36  
    37  ## Git Reference-Based Git Repository Clone
    38  
    39  If you need even more control, Jackal also supports providing full `git` [refspecs](https://git-scm.com/book/en/v2/Git-Internals-The-Refspec), as seen in `https://repo1.dso.mil/big-bang/bigbang.git@refs/heads/release-1.54.x`.  This allows you to pull specific tags or branches by using this standard.  The branch name used by jackal on deploy will depend on the kind of ref specified, branches will use the upstream branch name, whereas other refs (namely tags) will use the `jackal-ref-*` branch name.
    40  
    41  ## Git Repository Full Clone
    42  
    43  Full clones are used in this example with the `stefanprodan/podinfo` repository and follow the `scheme://host/repo` format (`https://github.com/stefanprodan/podinfo.git`). Full clones will contain **all** branches and tags in the mirrored repository rather than any one specific tag.
    44  
    45  :::note
    46  
    47  If you want to learn more about how Jackal works with GitOps, see the [podinfo-flux](../podinfo-flux/) example.
    48  
    49  :::
    50  
    51  ## `jackal.yaml` {#jackal.yaml}
    52  
    53  :::info
    54  
    55  To view the example in its entirety, select the `Edit this page` link below the article and select the parent folder.
    56  
    57  :::
    58  
    59  <ExampleYAML src={require('./jackal.yaml')} showLink={false} />