build

Author: concourse-bot

docs/steps/get/index.html

@@ -2345,6 +2345,17 @@
     </span>
   </a>
 
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#access-metadata-from-local-var" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Access Metadata from Local Var
+      
+    </span>
+  </a>
+  
 </li>
 
     </ul>
@@ -5741,6 +5752,17 @@
     </span>
   </a>
 
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#access-metadata-from-local-var" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Access Metadata from Local Var
+      
+    </span>
+  </a>
+  
 </li>
 
     </ul>
@@ -5777,7 +5799,10 @@
 
 
 <h1 id="get-step"><code>get</code> Step</h1>
-<p>Fetches a version of a <a href="../../resources/">resource</a>. Expand each section below for more details and examples.</p>
+<p>Fetches a version of a <a href="../../resources/">resource</a> and potentially
+metadata about the resource. Metadata is exposed as a <a href="../../vars/#local-var">local
+var</a> under the name of <code>get</code> step. Expand each section
+below for more details and examples.</p>
 <details class="warning">
 <summary><strong><code>get</code></strong>: <a href="../../resources/#resource-schema"><code>resource.name</code></a> | <a href="../../config-basics/#identifier-schema"><code>identifier</code></a> (required)</summary>
 <h3 id="get"><code>get</code></h3>
@@ -6011,6 +6036,48 @@ <h3 id="version"><code>version</code></h3>
 start from the latest version).</p>
 </div>
 </details>
+<hr>
+<details class="example">
+<summary>Access Metadata from Local Var</summary>
+<h3 id="access-metadata-from-local-var">Access Metadata from Local Var</h3>
+<p>Resources have the option to expose metadata for any version that it fetches.
+You'll need to reference the documentation for the resource type you're using
+to see if it exposes any metadata. Metadata is rendered as a table of key-value
+strings if viewed from the web UI.</p>
+<p>If the resource does expose metadata, it is then added as a <a href="../../vars/#local-var">local
+var</a> named after the <code>get</code> step. This example results
+in a local var called <code>my-resource</code>, with keys <code>hello</code> and <code>foo</code>.</p>
+<div class="language-yaml highlight"><pre><span></span><code><span id="__span-5-1"><a id="__codelineno-5-1" name="__codelineno-5-1" href="#__codelineno-5-1"></a><span class="nt">resources</span><span class="p">:</span>
+</span><span id="__span-5-2"><a id="__codelineno-5-2" name="__codelineno-5-2" href="#__codelineno-5-2"></a><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">my-resource</span>
+</span><span id="__span-5-3"><a id="__codelineno-5-3" name="__codelineno-5-3" href="#__codelineno-5-3"></a><span class="w">    </span><span class="nt">type</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">mock</span>
+</span><span id="__span-5-4"><a id="__codelineno-5-4" name="__codelineno-5-4" href="#__codelineno-5-4"></a><span class="w">    </span><span class="nt">source</span><span class="p">:</span>
+</span><span id="__span-5-5"><a id="__codelineno-5-5" name="__codelineno-5-5" href="#__codelineno-5-5"></a><span class="w">      </span><span class="nt">metadata</span><span class="p">:</span>
+</span><span id="__span-5-6"><a id="__codelineno-5-6" name="__codelineno-5-6" href="#__codelineno-5-6"></a><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">hello</span>
+</span><span id="__span-5-7"><a id="__codelineno-5-7" name="__codelineno-5-7" href="#__codelineno-5-7"></a><span class="w">          </span><span class="nt">value</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">world</span>
+</span><span id="__span-5-8"><a id="__codelineno-5-8" name="__codelineno-5-8" href="#__codelineno-5-8"></a><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">foo</span>
+</span><span id="__span-5-9"><a id="__codelineno-5-9" name="__codelineno-5-9" href="#__codelineno-5-9"></a><span class="w">          </span><span class="nt">value</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">bar</span>
+</span><span id="__span-5-10"><a id="__codelineno-5-10" name="__codelineno-5-10" href="#__codelineno-5-10"></a>
+</span><span id="__span-5-11"><a id="__codelineno-5-11" name="__codelineno-5-11" href="#__codelineno-5-11"></a><span class="nt">jobs</span><span class="p">:</span>
+</span><span id="__span-5-12"><a id="__codelineno-5-12" name="__codelineno-5-12" href="#__codelineno-5-12"></a><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">job</span>
+</span><span id="__span-5-13"><a id="__codelineno-5-13" name="__codelineno-5-13" href="#__codelineno-5-13"></a><span class="w">    </span><span class="nt">plan</span><span class="p">:</span>
+</span><span id="__span-5-14"><a id="__codelineno-5-14" name="__codelineno-5-14" href="#__codelineno-5-14"></a><span class="w">      </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">get</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">my-resource</span>
+</span><span id="__span-5-15"><a id="__codelineno-5-15" name="__codelineno-5-15" href="#__codelineno-5-15"></a><span class="w">      </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">task</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">ref-local-vars</span>
+</span><span id="__span-5-16"><a id="__codelineno-5-16" name="__codelineno-5-16" href="#__codelineno-5-16"></a><span class="w">        </span><span class="nt">config</span><span class="p">:</span>
+</span><span id="__span-5-17"><a id="__codelineno-5-17" name="__codelineno-5-17" href="#__codelineno-5-17"></a><span class="w">          </span><span class="nt">platform</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">linux</span>
+</span><span id="__span-5-18"><a id="__codelineno-5-18" name="__codelineno-5-18" href="#__codelineno-5-18"></a><span class="w">          </span><span class="nt">image_resource</span><span class="p">:</span>
+</span><span id="__span-5-19"><a id="__codelineno-5-19" name="__codelineno-5-19" href="#__codelineno-5-19"></a><span class="w">            </span><span class="nt">type</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">mock</span>
+</span><span id="__span-5-20"><a id="__codelineno-5-20" name="__codelineno-5-20" href="#__codelineno-5-20"></a><span class="w">            </span><span class="nt">source</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">{</span><span class="nt">mirror_self</span><span class="p">:</span><span class="w"> </span><span class="nv">true</span><span class="p p-Indicator">}</span>
+</span><span id="__span-5-21"><a id="__codelineno-5-21" name="__codelineno-5-21" href="#__codelineno-5-21"></a><span class="w">          </span><span class="nt">params</span><span class="p">:</span>
+</span><span id="__span-5-22"><a id="__codelineno-5-22" name="__codelineno-5-22" href="#__codelineno-5-22"></a><span class="w">            </span><span class="nt">FOO</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">((.:my-resource.foo))</span>
+</span><span id="__span-5-23"><a id="__codelineno-5-23" name="__codelineno-5-23" href="#__codelineno-5-23"></a><span class="w">          </span><span class="nt">run</span><span class="p">:</span>
+</span><span id="__span-5-24"><a id="__codelineno-5-24" name="__codelineno-5-24" href="#__codelineno-5-24"></a><span class="w">            </span><span class="nt">path</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">sh</span>
+</span><span id="__span-5-25"><a id="__codelineno-5-25" name="__codelineno-5-25" href="#__codelineno-5-25"></a><span class="w">            </span><span class="nt">args</span><span class="p">:</span>
+</span><span id="__span-5-26"><a id="__codelineno-5-26" name="__codelineno-5-26" href="#__codelineno-5-26"></a><span class="w">              </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">-c</span>
+</span><span id="__span-5-27"><a id="__codelineno-5-27" name="__codelineno-5-27" href="#__codelineno-5-27"></a><span class="w">              </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="p p-Indicator">|</span>
+</span><span id="__span-5-28"><a id="__codelineno-5-28" name="__codelineno-5-28" href="#__codelineno-5-28"></a><span class="w">                </span><span class="no">echo Hello ((.:my-resource.hello))</span>
+</span><span id="__span-5-29"><a id="__codelineno-5-29" name="__codelineno-5-29" href="#__codelineno-5-29"></a><span class="w">                </span><span class="no">echo foo $FOO</span>
+</span></code></pre></div>
+</details>
 
 
 

docs/vars/index.html

@@ -5997,9 +5997,17 @@ <h2 id="var-syntax"><code>((var))</code> syntax</h2>
 <em>secret-field</em> to <code>field:1</code>.</p>
 <h2 id="local-var">The "<code>.</code>" var source</h2>
 <p>The special var source name <code>.</code> refers to a "local var source."</p>
-<p>The precise scope for these "local vars" depends on where they're being used. Currently, the only mechanism that uses
-the local var source is the <a href="../steps/load-var/"><code>load_var</code> step</a>, which sets a var in a local var source provided to all
-steps executed in the build.</p>
+<p>The precise scope for these "local vars" depends on where they're being used.
+Currently there are only three mechanisms that populate the local var source:</p>
+<ol>
+<li>The <a href="../steps/load-var/"><code>load_var</code> step</a>, which sets a var in a local var
+   source and is available to all steps executed in the build.</li>
+<li>The <a href="../steps/modifier-and-hooks/across/"><code>across</code> step modifier</a>, but the
+   local var(s) it sets are only available to the steps running within the
+   <code>across</code> step.</li>
+<li>The <a href="../steps/get/"><code>get</code> step</a>, which adds a local var with the same name as
+   the <code>get</code> step and contains all the metadata from the step.</li>
+</ol>
 <h2 id="interpolation">Interpolation</h2>
 <p>Values for vars are substituted structurally. That is, if you have <code>foo: ((bar))</code>, whatever value <code>((bar))</code> resolves to
 will become the value of the <code>foo</code> field in the object. This can be a value of any type and structure: a boolean, a