Child pages
  • .asf.yaml features for git repositories
Skip to end of metadata
Go to start of metadata

.asf.yaml is a branch-specific file that a project may put in the root of the git repository to control various new features such as

  • website staging
  • github settings
  • pelican builds

It operates on a per-branch basis, meaning you can have different settings for different branches, and only those with an active .asf.yaml file will kick off a feature. Metadata settings (repo settings, features, labels,) are not branch-dependent, and should exist in the master branch.

Important notes before you start using .asf.yaml

  • The configuration file is specific to the branch in which it resides, (with the exception of repository metadata (features, labels, settings) and only code blocks with a whoami matching the branch name will be run.
  • The configuration file holds a great deal of power, as it controls a host of automated systems.
  • When using a feature in .asf.yaml, make sure that you have discussed what you propose with the entire project first, and have understood what the configuration changes will do to your (and the team's) workflow and project resources.



Implemented Features

Web Site Deployment Service for Git Repositories

The web site deployment service is managed through the staging and publish feature of the .asf.yaml file in git repositories.

NOTE Web site staging and publishing features are applied using the repository in which you have specified staging and publishing Thus, only specify it within the repository that contains your web site material, or you could end up just seeing a list of source code files from your source repository.

Primer

A basic staging and publishing profile to get you started could be:

# Staging and publishing profile for yourproject-website.git:
staging:
  profile: ~
  whoami:  asf-staging


publish:
  whoami:  asf-site


This configuration enables a staging (live preview) web site at yourproject.staged.apache.org using the asf-staging branch of your repository, as well as deploying the asf-site branch of the repository to your main web site at yourproject.apache.org. Details below:

Staging a web site preview domain

To enable staging (live preview) of web sites,  add a staging entry to the site repository's .asf.yaml file.
As an example, take the imaginary yourproject-website.git with an .asf.yaml file containing the following entry:

staging:
  profile: beta

This would stage the current branch at https://yourproject-beta.staged.apache.org/ (meaning you can have multiple staging profiles and thus multiple branches staged for preview).

You can also omit the profile value, and stage directly at https://yourproject.staged.apache.org/ . ( "~" (tilde) means "no value" in YAML):

staging:
  profile: ~


Preventing branch-override on cloning branch

Set a protection on multi-tenancy by specifying a whoami setting. If this does not match the current branch, no checkout/update will be made. You can have this on the asf-staging branch:

staging:
  profile: ~
  whoami:  asf-staging


When you clone that branch to a new branch like asf-staging-copy, the staging web site server will notice that the value of whoami does not match asf-staging-copy, and will ignore that branch until the whoami is updated to match.

Publishing a branch to your project web site

Note: if you have previously used gitwcsub for web site publishing, your first publish action using .asf.yaml will cause any existing gitwcsub or svnwcsub subscription to stop working. This ensures that there are no race conditions or "repository fights" going on when you publish.

To publish a branch to your project web site sub-domain (yourproject.apache.org), set up a configuration block called publish in your .asf.yaml file. Enable branch-protection through the whoami parameter, like so:

publish:
  whoami: asf-site

If, for whatever reason, a project wishes to revert back to gitwcsub for publishing, remove the publish feature in your .asf.yaml file.

Specifying a non-apache.org hostname

By default, web sites will be published at $project.apache.org where $project is the sub-domain name of your project, as determined by the repository name.
Some projects have special domains, like openoffice.org, and may publish to these by specifying a hostname attribute in the publishing config:

publish:
  whoami:   asf-site
  hostname: www.openoffice.org

NOTE: You cannot specify your $project.apache.org hostname with this setting. It has to be inferred to prevent abuse. Also, please do not abuse this feature, thanks!

CMS/pelican sub-directories for static output

The staging and deployment servers support both the content/ sub-dir as well as the pelican build output/ sub-dir as the root directory for the web site. Thus, the website root can be any of:

  • The root of the git branch
  • The content/ directory at the root of the branch
  • The output/ directory at the root of the branch



GitHub settings

Repository metadata

Projects can update their GitHub metadata (repository description, homepage and labels) via .asf.yaml like this:

github:
  description: "JSONP module for Apache Foobar"
  homepage: https://foobar.apache.org/
  labels:
    - json
    - jsonp
    - foobar
    - apache

NOTE : Metadata changes will only apply if the configuration is specified in the master branch of a repository

Repository features

Projects can enable/disable GitHub repository features to provide better support.

github:
  features:
    # Enable wiki for documentation
    wiki: true
    # Enable issues management
    issues: true
    # Enable projects for project management boards
    projects: true

Merge buttons

Projects can enable/disable the "merge PR" button in the GitHub UI and configure which actions should be allowed by adding the following configuration (or derivatives thereof):

github:
  enabled_merge_buttons:
    # enable squash button:
    squash:  true
    # enable merge button:
    merge:   true
    # disable rebase button:
    rebase:  false

GitHub Pages

Projects can enable/update GitHub Pages settings, using GitHub for website publishing, by specifying which branch (and optional path) to publish:

github:
  ghp_branch:  master
  ghp_path:    /docs

The ghp_branch setting can ONLY be either master or gh-pages.

The ghp_path setting is ONLY valid if ghp_branch is set to master, and MUST be either null (~) or /docs.


Jenkins PR Whitelisting

For projects using Jenkins for CI testing, PRs are generally only built when submitted by a committer. Projects MAY choose to designate a GitHub person as a 'safe/reliable' person using the jenkins/github_whitelist feature:

jenkins:
  github_whitelist:
    - janedoe
    - githubmonkey
    - papasmurf1234

The GitHub IDs listed here would have access to start builds based on PRs in addition to the committers on the project.


Static web site content generation


Jekyll CMS

Projects can build their websites automatically using Jekyll. This content can be staged or pushed directly to production when used in conjunction with the staging or publish configuration options

To set up an automatic build (a la the old Apache CMS system), one can add a jekyll section to .asf.yaml

jekyll:
  whoami: jekyll-source-branch
  target: jekyll-output-branch



Pelican CMS

Projects can automatically build web sites using the Pelican CMS System and even have the result either staged or pushed directly to production (with the addition of a staging or publish configuration, as seen above).

To set up an automatic build (much the way the old Apache CMS system works), one can add a pelican section to .asf.yaml:


pelican:
  whoami: master
  target: asf-site


The above configuration will generate the site using pelican and push only the created output to the asf-site branch. An example web site repo that uses the pelican auto-build feature is: https://github.com/apache/infrastructure-website

Our Pelican builds support GFM (GitHub-Flavored Markdown), meaning you can edit web sites using the GitHub UI and instantly get a preview of your page before pushing it to the build/publish process.

GFM is enabled by default, but will default to standard markdown if you have PLUGINS defined in your pelicanconf.py file. To explicitly enable GFM along with other manually defined plugins, you may specify pelican-gfm as a plugin, and it will be woven into the build.

Furthermore, you can build off one branch and publish to another using the target parameter, as seen above. If you leave this parameter out, the build process pushes the generated site to the same branch it built from (in the output/ base directory).

Pelican auto-builds support using different themes via the theme argument to specify the directory that contains your theme. This is equivalent to the -t switch in pelican:



Building and publishing at the same time

You can build and publish your website at the same time by employing both the pelican and publish configurations in your .asf.yaml file:

pelican:
  whoami: master
  target: asf-site

publish:
  whoami: asf-site

The configuration snippet above would, when present in both master and asf-site branches, build the web site from the master branch, then push the result to the asf-site branch and publish that branch as your project web site.

Likewise, you can employ auto-build-and-stage:

pelican:
  whoami: master
  target: asf-site

staging:
  whoami: asf-site
  profile: ~

This would build your site from the master branch, push the result to the asf-site branch and then stage that result on your staging domain.