Skip to content

Commit 2e88ac8

Browse files
Deployed by GitHub Actions
1 parent 5f87b88 commit 2e88ac8

3 files changed

Lines changed: 92 additions & 7 deletions

File tree

main/cli/index.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -787,7 +787,7 @@
787787
<h1 id="cli-reference">CLI reference</h1>
788788
<p>This page provides documentation for our command line tools.</p>
789789
<h2 id="dbt-jobs-as-code">dbt-jobs-as-code</h2>
790-
<p>dbt-jobs-as-code 1.12.1.dev2+gb3330b2</p>
790+
<p>dbt-jobs-as-code 1.12.1.dev6+g50edef4</p>
791791
<p>A CLI to allow defining dbt Cloud jobs as code</p>
792792
<p><strong>Usage:</strong></p>
793793
<div class="highlight"><pre><span></span><code>dbt-jobs-as-code [OPTIONS] COMMAND [ARGS]...

main/search/search_index.json

Lines changed: 1 addition & 1 deletion
Large diffs are not rendered by default.

main/typical_flows/index.html

Lines changed: 90 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -924,6 +924,57 @@ <h3 id="manage-jobs-as-code-only-for-production">Manage jobs as code only for Pr
924924
<li>We could also force a specific version with <code>uvx dbt-jobs-as-code@1.2</code></li>
925925
</ol>
926926
</details>
927+
<details class="example">
928+
<summary>Enhanced GitHub example: Posting plan results as pull request comments</summary>
929+
<p>This example shows how to capture the plan output and post it as a comment on the pull request, making it easier for reviewers to see what changes will be made.</p>
930+
<div class="highlight"><span class="filename">plan_on_pr_with_comment.yml</span><pre><span></span><code><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">Plan for syncing dbt Cloud Jobs from YAML</span>
931+
<span class="nt">run-name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">Running dbt-jobs-as-code plan to see what is going to be changed/deleted</span>
932+
933+
<span class="nt">on</span><span class="p">:</span>
934+
<span class="w"> </span><span class="nt">pull_request</span><span class="p">:</span>
935+
<span class="w"> </span><span class="nt">branches</span><span class="p">:</span>
936+
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">main</span>
937+
<span class="w"> </span><span class="nt">paths</span><span class="p">:</span>
938+
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="s">&#39;jobs/**&#39;</span>
939+
940+
<span class="nt">jobs</span><span class="p">:</span>
941+
<span class="w"> </span><span class="nt">run-python-script</span><span class="p">:</span>
942+
<span class="w"> </span><span class="nt">runs-on</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">ubuntu-latest</span>
943+
<span class="w"> </span><span class="nt">permissions</span><span class="p">:</span>
944+
<span class="w"> </span><span class="nt">pull-requests</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">write</span>
945+
<span class="w"> </span><span class="nt">contents</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">read</span>
946+
<span class="w"> </span><span class="nt">steps</span><span class="p">:</span>
947+
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">Check out repository code</span>
948+
<span class="w"> </span><span class="nt">uses</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">actions/checkout@v4</span>
949+
950+
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">Set up Python</span>
951+
<span class="w"> </span><span class="nt">uses</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">actions/setup-python@v4</span>
952+
<span class="w"> </span><span class="nt">with</span><span class="p">:</span>
953+
<span class="w"> </span><span class="nt">python-version</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;3.12.x&quot;</span>
954+
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">Install dbt-jobs-as-code</span>
955+
<span class="w"> </span><span class="nt">run</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">pip install dbt-jobs-as-code</span>
956+
957+
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">Run dbt-jobs-as-code</span>
958+
<span class="w"> </span><span class="nt">id</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">jobs-as-code-plan</span>
959+
<span class="w"> </span><span class="nt">run</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">|</span>
960+
<span class="w"> </span><span class="no">printf &quot;Changes from dbt-jobs-as-code (full details are available in the actions logs):\n\`\`\`\n&quot; &gt; plan_output.txt</span>
961+
<span class="w"> </span><span class="no">dbt-jobs-as-code plan jobs/my_jobs.yml --vars-yml jobs/prod_vars.yml --limit-projects-envs-to-yml &gt;&gt; plan_output.txt</span>
962+
<span class="w"> </span><span class="no">printf &quot;\n\`\`\`\n&quot; &gt;&gt; plan_output.txt</span>
963+
<span class="w"> </span><span class="nt">env</span><span class="p">:</span>
964+
<span class="w"> </span><span class="nt">DBT_API_KEY</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;${{secrets.DBT_API_KEY}}&quot;</span>
965+
<span class="w"> </span><span class="c1"># DBT_BASE_URL is optional</span>
966+
<span class="w"> </span><span class="c1"># DBT_BASE_URL: &quot;${{secrets.DBT_BASE_URL}}&quot;</span>
967+
968+
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">Comment PR</span>
969+
<span class="w"> </span><span class="nt">uses</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">mshick/add-pr-comment@v2</span>
970+
<span class="w"> </span><span class="nt">with</span><span class="p">:</span>
971+
<span class="w"> </span><span class="nt">message-path</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">plan_output.txt</span>
972+
</code></pre></div>
973+
<div class="admonition note">
974+
<p class="admonition-title">Note</p>
975+
<p>This example uses the <a href="https://github.com/mshick/add-pr-comment">mshick/add-pr-comment</a> GitHub Action to post the plan output as a comment. The <code>pull-requests: write</code> permission is required for the action to post comments.</p>
976+
</div>
977+
</details>
927978
<p>The relevant GitLab pipelines would be the following:</p>
928979
<details class="example">
929980
<summary>Examples of GitLab pipelines for <code>plan</code> and <code>sync</code></summary>
@@ -956,7 +1007,7 @@ <h3 id="manage-jobs-as-code-only-for-production">Manage jobs as code only for Pr
9561007

9571008
<span class="nt">sync_dbt_jobs</span><span class="p">:</span>
9581009
<span class="w"> </span><span class="nt">stage</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">sync</span>
959-
<span class="w"> </span><span class="nt">image</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">python:3.12</span><span class="w"> </span>
1010+
<span class="w"> </span><span class="nt">image</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">python:3.12</span>
9601011
<span class="w"> </span><span class="nt">rules</span><span class="p">:</span>
9611012
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">if</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">$CI_PIPELINE_SOURCE == &quot;push&quot; &amp;&amp; $CI_COMMIT_BRANCH == &quot;main&quot; &amp;&amp; $CI_COMMIT_MESSAGE =~ /^Merge.*/</span>
9621013
<span class="w"> </span><span class="nt">changes</span><span class="p">:</span>
@@ -967,14 +1018,48 @@ <h3 id="manage-jobs-as-code-only-for-production">Manage jobs as code only for Pr
9671018
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">pip install dbt-jobs-as-code</span>
9681019
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="p p-Indicator">|</span>
9691020
<span class="w"> </span><span class="no">echo &quot;Checking out branch...&quot;</span>
970-
<span class="w"> </span><span class="no">git fetch origin $CI_COMMIT_BRANCH </span>
971-
<span class="w"> </span><span class="no">git checkout $CI_COMMIT_BRANCH </span>
972-
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">dbt-jobs-as-code sync jobs/jobs_config.yml</span><span class="w"> </span>
1021+
<span class="w"> </span><span class="no">git fetch origin $CI_COMMIT_BRANCH</span>
1022+
<span class="w"> </span><span class="no">git checkout $CI_COMMIT_BRANCH</span>
1023+
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">dbt-jobs-as-code sync jobs/jobs_config.yml</span>
9731024

9741025
<span class="w"> </span><span class="nt">before_script</span><span class="p">:</span>
9751026
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">export DBT_API_KEY=$DBT_API_KEY</span><span class="w"> </span><span class="c1"># Ensure this variable is set in GitLab CI/CD project settings</span>
9761027
</code></pre></div>
9771028
</details>
1029+
<details class="example">
1030+
<summary>Enhanced GitLab example: Posting plan results as merge request comments</summary>
1031+
<p>This example shows how to capture the plan output and post it as a comment on the merge request, making it easier for reviewers to see what changes will be made.</p>
1032+
<div class="highlight"><span class="filename">.gitlab-ci.yml</span><pre><span></span><code><span class="nt">stages</span><span class="p">:</span>
1033+
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">plan</span>
1034+
1035+
<span class="nt">plan_dbt_jobs</span><span class="p">:</span>
1036+
<span class="w"> </span><span class="nt">stage</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">plan</span>
1037+
<span class="w"> </span><span class="nt">image</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">python:3.12</span>
1038+
<span class="w"> </span><span class="nt">rules</span><span class="p">:</span>
1039+
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">if</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">$CI_PIPELINE_SOURCE == &quot;merge_request_event&quot; &amp;&amp; $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == &quot;main&quot;</span>
1040+
<span class="w"> </span><span class="nt">changes</span><span class="p">:</span>
1041+
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">jobs/**/*</span>
1042+
<span class="w"> </span><span class="nt">script</span><span class="p">:</span>
1043+
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">apt-get update &amp;&amp; apt-get install -y jq git</span>
1044+
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">pip install dbt-jobs-as-code</span>
1045+
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="p p-Indicator">|</span>
1046+
<span class="w"> </span><span class="no">echo &quot;Checking out branch...&quot;</span>
1047+
<span class="w"> </span><span class="no">git fetch origin $CI_MERGE_REQUEST_TARGET_BRANCH_NAME</span>
1048+
<span class="w"> </span><span class="no">git fetch origin $CI_COMMIT_REF_NAME</span>
1049+
<span class="w"> </span><span class="no">git checkout $CI_COMMIT_REF_NAME</span>
1050+
<span class="w"> </span><span class="no">printf &quot;Changes from dbt-jobs-as-code (full details are available in the actions logs):\n\`\`\`\n&quot; &gt; plan_output.txt</span>
1051+
<span class="w"> </span><span class="no">dbt-jobs-as-code plan --limit-projects-envs-to-yml --vars-yml jobs/environments/vars_prod.yml jobs/jobs/**/*.yml &gt;&gt; plan_output.txt 2&gt;&amp;1</span>
1052+
<span class="w"> </span><span class="no">printf &quot;\`\`\`\n&quot; &gt;&gt; plan_output.txt</span>
1053+
<span class="w"> </span><span class="no">cat plan_output.txt</span>
1054+
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="s">&#39;curl</span><span class="nv"> </span><span class="s">--request</span><span class="nv"> </span><span class="s">POST</span><span class="nv"> </span><span class="s">--header</span><span class="nv"> </span><span class="s">&quot;PRIVATE-TOKEN:</span><span class="nv"> </span><span class="s">$CI_AUTOCOMMENTER_API_KEY&quot;</span><span class="nv"> </span><span class="s">--data-urlencode</span><span class="nv"> </span><span class="s">&quot;body@plan_output.txt&quot;</span><span class="nv"> </span><span class="s">&quot;https://gitlab.com/api/v4/projects/$CI_PROJECT_ID/merge_requests/$CI_MERGE_REQUEST_IID/notes&quot;&#39;</span>
1055+
<span class="w"> </span><span class="nt">before_script</span><span class="p">:</span>
1056+
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">export DBT_API_KEY=$DBT_API_KEY</span><span class="w"> </span><span class="c1"># Ensure this variable is set in GitLab CI/CD project settings</span>
1057+
</code></pre></div>
1058+
<div class="admonition note">
1059+
<p class="admonition-title">Note</p>
1060+
<p>This example requires setting up a <code>CI_AUTOCOMMENTER_API_KEY</code> variable in your GitLab CI/CD settings with a personal access token that has <code>api</code> scope to post comments to merge requests.</p>
1061+
</div>
1062+
</details>
9781063
<hr />
9791064
<h3 id="manage-jobs-as-code-in-different-environments">Manage jobs as code in different environments</h3>
9801065
<p>A similar approach to the first case, but in that situation, we use <a href="../advanced_config/templating/">templated YML files</a> so that the same YML file can be used across different environments, and jobs can be configured based on some variables.</p>
@@ -1223,7 +1308,7 @@ <h3 id="automated-promotion-of-jobs-created-in-the-ui-to-other-environments">Aut
12231308
<span class="md-icon" title="Last update">
12241309
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg>
12251310
</span>
1226-
<span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date">May 21, 2025</span>
1311+
<span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date">October 27, 2025</span>
12271312
</span>
12281313

12291314

0 commit comments

Comments
 (0)