|
| 1 | +# Using Git Templates |
| 2 | + |
| 3 | +The `--template` argument, used in various `apigee-go-gen render` commands, accepts two types of sources for your template files: a local file path or a remote file path via a Git repository URI. |
| 4 | + |
| 5 | +## 1. Local File Path |
| 6 | + |
| 7 | +This is the simplest usage, pointing directly to a file on your local machine. |
| 8 | + |
| 9 | +``` |
| 10 | +# Relative path example |
| 11 | +apigee-go-gen render ... --template ./templates/my_api.yaml.tpl |
| 12 | +
|
| 13 | +# Absolute path example |
| 14 | +apigee-go-gen render ... --template /home/user/project/templates/my_api.yaml.tpl |
| 15 | +``` |
| 16 | + |
| 17 | +## 2. Remote Git Repository URI |
| 18 | + |
| 19 | +!!! Info |
| 20 | + To use this remote fetching feature, you need **Git 2.25 or later** installed and available in your `$PATH`. |
| 21 | + |
| 22 | +You can specify a template file located in a public or private Git repository using a structured URI. The tool fetches only the necessary file and its containing directory using a sparse checkout, minimizing download time. |
| 23 | + |
| 24 | +A Git URI is composed of three parts: **Repository URL**, **Reference (Ref)**, and **Resource Path**. |
| 25 | + |
| 26 | +### Git URI Structure |
| 27 | + |
| 28 | +The Git URI must conform to one of two primary formats for parsing: **Web-View** or **Generic**. |
| 29 | + |
| 30 | +| Format | Purpose | |
| 31 | +|--------------|---------------------------------------------------------------------| |
| 32 | +| **Web-View** | Standard format seen in GitHub, GitLab, and Bitbucket. | |
| 33 | +| **Generic** | A flexible format for any Git URL, including SSH and generic HTTPS. | |
| 34 | + |
| 35 | +### A. Web-View Format |
| 36 | + |
| 37 | +These formats match the path structure you see when browsing files on major Git hosting platforms. |
| 38 | + |
| 39 | +| Style | Structure | |
| 40 | +|---------------|--------------------------------------| |
| 41 | +| **GitHub** | `<REPO_URL>/blob/<REF>/<RESOURCE>` | |
| 42 | +| **GitLab** | `<REPO_URL>/-/blob/<REF>/<RESOURCE>` | |
| 43 | +| **BitBucket** | `<REPO_URL>/src/<REF>/<RESOURCE>` | |
| 44 | + |
| 45 | +#### Example Usage |
| 46 | + |
| 47 | +``` |
| 48 | +# Using GitHub web-view format with the 'main' branch |
| 49 | +apigee-go-gen render ... --template https://github.com/my-org/templates/blob/main/templates/my/api.yaml |
| 50 | +
|
| 51 | +# Using GitLab web-view format with a specific tag |
| 52 | +apigee-go-gen render ... --template https://gitlab.com/apigee/starter/-/blob/v1.2.3/templates/my/api.yaml |
| 53 | +
|
| 54 | +# Using BitBucket web-view format with a commit hash |
| 55 | +apigee-go-gen render ... --template https://bitbucket.org/team/project/src/a1b2c3d4e5f6/templates/my/api.yaml |
| 56 | +``` |
| 57 | + |
| 58 | +### B. Generic Format |
| 59 | + |
| 60 | +This flexible format uses the `/-/` separator and is useful for non-HTTP Git protocols (like SSH) or when you need explicit control over the **Repository URI**, **Reference** and **Resource** . |
| 61 | + |
| 62 | +| Style | Structure | Purpose | |
| 63 | +|-------------|-----------------------------|---------------------------------------------------------------| |
| 64 | +| **Simple** | `<REPO>/-/<REF>/<RESOURCE>` | Used when `<REF>` has no slashes (e.g., `main`). | |
| 65 | +| **Complex** | `<REPO>/-/<REF>#<RESOURCE>` | Used when `<REF>` contains slashes (e.g., `feature/new-api`). | |
| 66 | + |
| 67 | +#### Example Usage |
| 68 | + |
| 69 | +``` |
| 70 | +# Using SSH protocol (implicit) with a simple branch name ('main') |
| 71 | +apigee-go-gen render ... --template git@github.com:my-org/project.git/-/main/my/api.yaml |
| 72 | +
|
| 73 | +# Using SSH protocol (explicit) with a simple branch name ('main') |
| 74 | +apigee-go-gen render ... --template ssh://git@github.com:my-org/project.git/-/main/my/api.yaml |
| 75 | +
|
| 76 | +# Using HTTPS protocol with a tag ('v1.2.3') |
| 77 | +apigee-go-gen render ... --template https://gitlab.com/my-org/project.git/-/v1.2.3/my/api.yaml |
| 78 | +
|
| 79 | +# Using a reference with a slash (branch 'feature/jira-1337') requiring '#' |
| 80 | +apigee-go-gen render ... --template https://repo.example.com/project.git/-/feature/jira-1337#my/api.yaml |
| 81 | +``` |
| 82 | + |
| 83 | +### Reference Types |
| 84 | + |
| 85 | +The reference (`<REF>`) component of the URI is flexible and can point to any valid Git object: |
| 86 | + |
| 87 | +* **Branch Name:** The name of a branch (e.g., `main`, `develop`, `feature/new-service`). |
| 88 | + |
| 89 | +* **Tag:** A version tag (e.g., `v1.0.0`, `release-2024-05`). |
| 90 | + |
| 91 | +* **Commit Hash:** A full or short commit hash (e.g., `a1b2c3d4e5f6` or `a1b2c3d`). |
| 92 | + |
| 93 | +## Private Repositories (SSH) |
| 94 | + |
| 95 | +To access private Git repositories, the preferred and most secure mechanism is using **SSH keys**. This requires your SSH client to have the correct key loaded into the `ssh-agent`. |
| 96 | + |
| 97 | +### SSH Key Setup |
| 98 | + |
| 99 | +Before attempting to fetch a private template, ensure you have an SSH key pair generated and added to your Git hosting platform account (GitHub, GitLab, etc.). |
| 100 | + |
| 101 | +**A. Generate an SSH Key Pair** |
| 102 | + |
| 103 | +If you do not have an SSH key, use `ssh-keygen`. We recommend using the default file name (`id_rsa` or `id_ed25519`) and adding a secure passphrase. |
| 104 | + |
| 105 | +```sh |
| 106 | +ssh-keygen -t ed25519 -C "your_email@example.com" |
| 107 | +``` |
| 108 | + |
| 109 | +**B. Add Key to SSH-Agent** |
| 110 | + |
| 111 | +You must start the `ssh-agent` and add your private key so that Git can use it without prompting for your passphrase on every fetch operation. |
| 112 | + |
| 113 | +```sh |
| 114 | +# 1. Start the ssh-agent in the background |
| 115 | +eval "$(ssh-agent -s)" |
| 116 | + |
| 117 | +# 2. Add your private key (use the path to your generated key) |
| 118 | +ssh-add ~/.ssh/id_ed25519 |
| 119 | +``` |
| 120 | + |
| 121 | +### Troubleshooting SSH Connectivity |
| 122 | + |
| 123 | +If you encounter issues when attempting to fetch a template, it is often related to the client's knowledge of the Git host's server key. |
| 124 | + |
| 125 | +**Error: `ssh: handshake failed: knownhosts: key is unknown`** |
| 126 | + |
| 127 | +This indicates that your `~/.ssh/known_hosts` file does not contain the public SSH key for the Git server (e.g., GitHub.com or Bitbucket.org). You need to add it: |
| 128 | + |
| 129 | +```sh |
| 130 | +# Replace bitbucket.org with your Git host (e.g., github.com, gitlab.com) |
| 131 | +ssh-keyscan -H bitbucket.org >> ~/.ssh/known_hosts |
| 132 | +``` |
| 133 | + |
| 134 | +**Error: `ssh: handshake failed: knownhosts: key mismatch`** |
| 135 | + |
| 136 | +This means the existing key for the Git SSH server in your `~/.ssh/known_hosts` file is incorrect (e.g., the host changed their key). You must first remove the old key, and then add the new one. |
| 137 | + |
| 138 | +```sh |
| 139 | +# 1. Remove the existing, incorrect key |
| 140 | +ssh-keygen -R bitbucket.org |
| 141 | + |
| 142 | +# 2. Add the correct host keys |
| 143 | +ssh-keyscan -H bitbucket.org >> ~/.ssh/known_hosts |
| 144 | +``` |
| 145 | + |
| 146 | + |
| 147 | +## Private Repositories (HTTPS) |
| 148 | + |
| 149 | +If you cannot use SSH, you can access private repositories using the HTTPS URI format by embedding a Personal Access Token (PAT) as the password component. |
| 150 | + |
| 151 | +1. **Generate a PAT:** Create a Personal Access Token in your Git hosting platform's security settings. This token must have the scope necessary to read repository contents (`repo` or similar). |
| 152 | + |
| 153 | +2. **Use the Token in the URI:** The token replaces the password in the standard HTTPS URL structure. |
| 154 | + |
| 155 | + **Structure:** `https://<USERNAME>:<TOKEN>@<GIT_HOST>/<REPO_PATH>` |
| 156 | + |
| 157 | +!!! Warning |
| 158 | + This method is less secure than using SSH, and should be avoided if possible. |
| 159 | + Your Personal Access Token is briefly written to a temporary `.git` directory during the `git checkout` operation. |
| 160 | + Once the `git checkout` operation completes, the `.git` directory is deleted. |
| 161 | + |
| 162 | +#### Example Usage (GitHub) |
| 163 | + |
| 164 | +``` |
| 165 | +# Replace 'USERNAME' and 'TOKEN' |
| 166 | +apigee-go-gen render --template https://USERNAME:TOKEN@github.com/my-org/templates/-/main/path/to/template.tpl |
| 167 | +``` |
0 commit comments