.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
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.
whoamimatching the branch name will be run.
.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.
The web site deployment service is managed through the
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.
A basic staging and publishing profile to get you started could be:
This configuration enables a staging (live preview) web site at yourproject.staged.apache.org using the
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:
To enable staging (live preview) of web sites, add a
staging entry to the site repository's
As an example, take the imaginary
yourproject-website.git with an
.asf.yaml file containing the following entry:
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):
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
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.
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:
If, for whatever reason, a project wishes to revert back to gitwcsub for publishing, remove the publish feature in your .asf.yaml file.
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:
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!
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:
content/directory at the root of the branch
output/directory at the root of the branch
Projects can update their GitHub metadata (repository description, homepage and labels) via
.asf.yaml like this:
NOTE : Metadata changes will only apply if the configuration is specified in the
master branch of a repository
Projects can enable/disable GitHub repository features to provide better support.
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):
Projects can enable/update GitHub Pages settings, using GitHub for website publishing, by specifying which branch (and optional path) to publish:
The ghp_branch setting can ONLY be either
ghp_path setting is ONLY valid if
ghp_branch is set to
master, and MUST be either null (~) or
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:
The GitHub IDs listed here would have access to start builds based on PRs in addition to the committers on the project.
To set up an automatic build (a la the old Apache CMS system), one can add a
jekyll section to
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
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
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:
You can build and publish your website at the same time by employing both the pelican and publish configurations in your .asf.yaml file:
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:
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.