Pass data about the specific branch being built into the builder

[wslack]

Right now, we pass in data about the branch being built to the builder: https://github.com/18F/federalist-garden-build/blob/e874d431dfe22732a32da45687a80949b46ad769/build.sh#L65

I'm wondering per a discussion with @jeremyzilar if we can build a component that Jekyll would build using the name of the branch (which isn't set in code anywhere) but would allow someone to see in a bar above a preview site that they are looking at branch example-branch or whatever.

[jeremyzilar]

I would prefer it if the branch name and other site-related data were able to be passed into a sitejekyll/hugo

<meta property="gov:git-org" content="gsa">
<meta property="gov:git-repo" content="digitalgov">
<meta property="gov:git-branch" content="demo">
<meta property="gov:build-time" content="3 mins">

[wslack]

where are those properties stored? Wouldn't you need to build something in the HTML to hold that?

[jeremyzilar]

I believe those are all data stored in Federalist... but now that I think about it, the maybe docker container doesnt know about that data?

Either way, being able to get the current branch name for a build (other than scraping the URL pattern) would help a ton. In addition, if you have a way to pass in the time it took to build, that would help too.

[wslack]

Right - my question is: where do you want the data to go? Jekyll has to place it somewhere during build.

[jseppi]

You should have access to the branch name during the build as the environment variable BRANCH

[wslack]

Right - I think the goal is to get the branch name placed in the HTML head tag or something like that so that a plugin can reference it.

[jseppi]

Yeah, I was more answering @jeremyzilar's concern about scraping the branch name from the URL. Getting it during the build (via the BRANCH env var) would be nicer than that for sure.

As for a plugin, I think there'd need to be separate ones for jekyll and hugo.

[wslack]

I should have been clearer - Federalist would not build a plugin, but would need to put the branch name in page metadata so that an external plugin could reference it.

Another possibility would be coding pages so that any preview branch has a header bar naming the branch that's being viewed so its clear a site is a preview, but we thought the metadata would be a better MVP.

[jseppi]

Hrm, so like have Federalist inject the BRANCH var value into config.yml or something like that?

[wslack]

Is config.yml saved on S3 somewhere? We just need it to get put on S3 somewhere - possibly via some HTML in the base template.

[jseppi]

No, the config isn't stored in S3.

If the branch name was available in the build (which it is, as the BRANCH var), then jekyll/hugo/whatever itself could use the value to add a header/meta-tag/whatever to all the pages it outputs. Plugin(s) to do this automatically without each client site needing to do it custom would be nice since they'd be reusable by a number of sites. We could probably even include the plugin as part of the templates we offer.

I guess the Federalist build container itself could do also it by reading every .html page that is created by the build engine and inserting a tag into each file, but directly modifying client content seems weird to me.

Or am I totally misunderstanding what you're getting at?

[wslack]

If we can do that with the build process via a plugin, that would be awesome.

[wslack]

actually @jseppi what if we just threw in a little metadata file on S3? That could be powerful.

[jseppi]

That could maybe be useful. For something like a banner displaying the current branch of the site being viewed, the site would likely need to use some JS to fetch it and do stuff with the data contained therein.

[wslack]

Yep - or have a chrome plugin fetch that data (which I think is Jeremy's MVP).

[wslack]

@jseppi what are the implementation options here?

1. jekyll/hugo/whatever adds a header/meta-tag/whatever to all the pages it outputs
2. A separate process adds a header/meta-tag/whatever to all the pages output inside the container (takes care of the static pages)
3. A separate process drops some metadata at url.gov/federalist.dat or something

[jseppi]

What is the end goal? A stripe at the top of all pages that says "This is a preview of the ${BRANCH} branch"?

[jseppi]

Because if so, I don't see how the meta-tag or data file are that helpful. Site creators would still have to use that hidden info somehow. They already can make something like that because we expose BRANCH during the build process.

[wslack]

kk. So seems like it would be better to add a smart bar across the top of the page to announce the branch when not previewing.

[jseppi]

I think it should be left up to individual sites to make that choice. We could provide plugins for Jekyll or Hugo to add the banner based on the BRANCH environment variable if you wish.

I don't think Federalist should modify sites' content as part of the build process though. That could result in some bad side effects. For instance, if a client site has a sticky header at the top of their page that moves with scroll position, inserting something above it could break that functionality.

[wslack]

Ok! @jeremyzilar what if you add in the metadata by editing your base.html template or (even better) create the banner using a Jekyll plugin?

[wslack]

Though, I don't know if there's a way for a plugin to know if its on a live branch, demo branch, or preview branch...

[jseppi]

Could use SITE_PREFIX as a proxy for that

[jseppi]

Or I think it would be easy for us to add another env var from federalist called SITE_TYPE with values of live, demo, preview (or something along those lines).

[wslack]

I don't know enough about SITE_PREFIX but if that adds functionality let's do that (with values of site, demo, and preview - so it mirrors the S3 structure plz)

[jseppi]

SITE_PREFIX holds part of the S3 bucket path for where to put the files of a given build. It looks like:

• For a preview: preview/<OWNER>/<REPOSITORY>/<BRANCH>; ex: preview/18f/federalist-docs/jseppi-patch-1
• For a live site: site/<OWNER>/<REPOSITORY>; ex: site/18f/federalist-docs
• For a demo site: demo/<OWNER>/<REPOSITORY>; ex: demo/18f/federalist-docs

So some code could check the first part of the value to tell if it is a preview, live site, or demo.

[wslack]

👍 @jeremyzilar thoughts on this discussion? (I know you are out sick today)

[jeremyzilar]

Yes, having the data available so that we could do something with it on the site, would be all we need.

Where could we access the SITE_PREFIX data? Or where is the easiest place that Federalist could put the SITE_PREFIX data so that I can retrieve it?

If you can figure out a way for me to get the data, I will work on figuring out where this data would be represented on the page or source. It'll likely be a bar across the top of the visible page. Visible data is better than hidden metadata.

[jseppi]

You have access to all these values at build time, @jeremyzilar. I think you could write either a node script (called via npm run federalist) or a hugo plugin to access the environment variables and do whatever you want with them during your site builds.

[jeremyzilar]

Thank you @jseppi — I will give that a try 🎉

[thisisdano]

I don't know how to do this with Node or via a plugin, but I do need the ability to conditionally display content depending on whether it's a preview branch or the production branch. An example is the notification banner we currently show on the Federalist builds:

I'd like this to show on all the branches but the master production branch and I don't know how to do this with the existing config data (like .BaseURL, which I think outputs as / for both demo and master when they have custom domains set).

This could be done with custom config settings, as you already have for Jekyll sites. I've sketched this out in a new issue which may or may not be useful: https://github.com/18F/federalist/issues/1219

But I'm certainly open to guidance or other solutions!

[wslack]

@thisisdano I don't think custom config if your best way to go here especially since I think you want the content to apply to multiple sites instead of having to be plugged in 1 by 1. Instead, I think having something in your code that builds conditionally based on SITE_PREFIX will work better.

Instead, you'll need something to express this in the build process, as discussed above. Config can help but really, you'd still need to put the HTML on your site.

[thisisdano]

I am very happy to build something based on SITE_PREFIX (a solution that would work) but I need more guidance on how to access it, since it's beyond my expertise in either Node or in Hugo plugins.

If I can access the SITE_PREFIX value in my templates, I can easily use it as a template hook to output the desired HTML. That's the only reason I'm interested in config.yml params, since I already know how to access those in the templates.

[jseppi]

In node, you can access env vars via process.env.whatever_the_var_is_named --> process.env.SITE_PREFIX for example. For more info on using a custom node script during build, see https://federalist-docs.18f.gov/pages/how-federalist-works/node-on-federalist/

In hugo, it looks like there is a getenv function you could use: http://gohugo.io/functions/getenv/: {{ getenv SITE_PREFIX }}

[thisisdano]

thanks @jseppi I'll give getenv a shot first

[jseppi]

I think this can be closed. The build-specific environment variables, which include the BRANCH are documented and I think folks are making use of them.

[wslack]

@thisisdano did you get the full feature set you wanted?