.asf.yaml is a branch-specific YAML configuration file that a project may create (using a text editor of your choice) and put in the root of a Git repository to control 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 main (default) branch.
--in your .asf.yaml file. It will cause parsing to fail.
whoamimatching the branch name will run.
.asf.yaml, make sure that you have discussed what you propose with the entire project team, and have understood what the configuration changes will do to the team's workflow and project resources.
If you would like to add some features you are free to open a Pull Request and propose your changes, the whole logic is defined in the asfyaml.py file.
Projects can set their notification targets for commits and GitHub issues/PRs/actions and discussions via .asf.yaml. Note that Jira issue email notification schemes are separate and require an Infra Jira ticket to change.
Setting up notification schemes via .asf.yaml can only happen in the main/master/trunk or default branch of a repository, and each configuration change will cause your project's private@ list to receive a notification of the change, for review purposes.
Settings made in .asf.yaml takes precedence over the original legacy mail targets (entered when setting up the repository). If a specific target scheme is not found in .asf.yaml, the legacy defaults will be used instead.
If you wish to take a look at the default (old style) configuration for a repository, visit
https://gitbox.apache.org/schemes.cgi?$repository-name-here , for instance https://gitbox.apache.org/schemes.cgi?lucene-solr
You can divide pull requests and issues into sub-categories to split up the open/close emails and the comments/code review parts.
For instance, if a project wants new PRs to send an email to dev@foo, but wants any comments on that PR to go to issues@foo, employ the following configuration:
Likewise, you can split issues into issues_status and
issues_comment for sending issue emails to the appropriate targets.
The hierarchy for determining the email target for an action is:
Projects may specify that commits to a repository that touches on specific paths will have a copy of the commit email sent to one or more specific addresses.
These paths are glob-enabled.
Projects may create special rules for bots on GitHub, such as dependabot, to have PR and issue activity from these directed to a distinct mailing list. The general syntax for this is done by appending "_bot_$botname" to the scheme, for instance:
These special schemes are currently only available for pull requests and issues.
You can use the file to enable Jira notifications that will fire when a GitHub issue or pull request has a ticket in its title, such as
"[TICKET-1234] Improve foo bar".
You can set one or more of these options:
comment: Add the PR/issue event as a comment in the referenced Jira ticket.
worklog: Add the event as a worklog entry instead of a comment in the Jira ticket you reference.
label: Add a 'pull-request-available' label to referenced tickets.
link: When you create a GitHub PR/issue, embed a link to the PR or issue in the Jira ticket you reference.
Concatenate the options you want to use as a string list, like this:
publish features of the
.asf.yaml file in a git repository manage web site deployment.
NOTE : Web site staging and publishing features are applied for the repository in which you have specified staging and publishing . Thus, only specify them 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 could be:
This configuration enables a staging (live preview) web site at yourproject.staged.apache.org using the
branch of your repository, and deploys the
asf-site branch of the repository to your main web site at yourproject.apache.org. Details below:
To enable staging (live preview) of your project's web site, 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/ . You can add multiple staging profiles and thus multiple branches staged for preview. This can be helpful when doing A/B evaluations of website contents and features.
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 the setting's value does not match the current branch, no checkout/update happens. You can have this in the .asf.yaml file 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 you update the
whoami to match it.
If you use features such as
autobuild, you can also automatically stage branches on staged.apache.org with the
autobuild, it must match the branches you wish to
autostaging feature derives a profile from the branch name, thus site/* would stage all branches matching site/*-staging as *.project.apache.org. For instance:
$project-foo.staged.apache.org, for instance
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.
Note: although publishing the asf-site branch used to work without .asf.yaml being present, since May 2021 that file MUST be present at the root of the branch you wish to publish. for everything (including soft purging the CDN cache on updates) to work correctly.
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 to gitwcsub for publishing, remove the publish feature in your .asf.yaml file.
By default, web sites are published at $project.apache.org, where $project is the sub-domain name of your project as determined by the repository name.
Some projects, like openoffice.org, have special domains and may publish to these by specifying a
hostname attribute in the publish configuration block, as shown below.
This is also useful when a PMC manages several websites, like comdev-site and comdev-events-site.
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 in any other way, thanks!
To publish to a sub-directory of the web site URL, specify a
subdir value. Such checkouts can be useful for sub-projects.
For instance, if httpd wished to check out a repository into
httpd.apache.org/subproject, they could use the following configuration:
Issue: In some cases (such as recent migration to this mechanism) the initial website check in will clobber the sub-directory sites with a '404' error.
Remediation: Committing to the sub sites will trigger the mechanism to re-pull the content from sub-sites.
The staging and deployment servers support the pelican build
output/ sub-dir as the root directory for the web site. Thus, the website root can be either:
output/directory at the root of the branch
Blogs can be deployed in the same manner as websites, and will be deployed as both $project.blog.apache.org AND $project.apache.org/blog (will redirect internally if a blog is deployed this way).
Deploying a blog is done by utilizing the type parameter in your publish setting:
NB: there is an internal rewrite, so $project.apache.org/blog will only rewrite to /www/blogs/$project internally if that directory exists e.g. a separate blog is deployed
Projects can update their GitHub metadata (repository description, homepage and labels) via
.asf.yaml like this:
NOTE : Metadata changes will only apply if you specify them in the .asf.yaml file in the
master (or otherwise default) branch of a repository
Projects can enable/disable GitHub repository features to support their documentation and development model.
Projects can enable/disable the "merge PR" button in the GitHub UI and configure which actions to allow by adding the following configuration (or derivatives thereof):
At least one of squash, merge, or rebase must be true.
Projects can enable and disable Dependabot alerts and automatic security update Pull Requests:
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 your default branch (e.g.
master, main, ...) or
gh-pages. (Note: This is subject to change as GitHub is relaxing the rules).
ghp_path setting should ALWAYS be specified. It can be either
/. If not specified, it will default to /docs.
You can add a
jobs directive in the standard
notifications section to have GitHub actions send you notifications when a build fails, or when it transitions from failure to success:
This triggers emails when a workflow run fails or if it succeeds after a series of failures. We do not send notifications on normal successful runs, so as to not spam too much.
Projects can enable branch protection in their repos, including most of the sub-level protection features such as 'require status checks to pass before merging' , 'approval by at least $n people' , and 'require pull request reviews'.
NB (1): Enabling any of the above checks overrides what you may have set previously, so you'll need to add all the existing checks to your .asf.yaml to reproduce any that Infra set manually for you.
NB (2): If you need to remove a required check in order to push a change to .asf.yaml, you will need to create an Infra Jira ticket with a request to have the check manually removed.
All protected branches in the YAML must be dictionary entries. Thus, if you only want to disable force push from a branch, you can construct a minimal dictionary like so:
Branches that are not in the YAML or are not dictionary entries are not protected.
To completely remove all branch protection rules, set the protected_branches section to null, as such:
Add this snippet below so branches get auto-deleted upon PR merge to your default branch:
You can revert this by setting it back to false. (Merely removing the entry would not do that).
For projects using Jenkins for CI testing, PRs are generally only built when a committer submits one. Projects MAY choose to designate a GitHub '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. For automated accounts, such as Dependabot, you will need to add the
[bot] suffix to its name.
Projects may assign external (non-committer) collaborators the
triage role for their repository.
The triage role allows people to assign, edit, and close issues and pull requests, without giving them write access to the code.
Add such people to the 'collaborators' stanza inside the github section, as a list of GitHub IDs:
To remove people as collaborators, remove them from the list. You may only have 20 active collaborators at any given time per repository.
Note: If you wish to completely empty a previously non-empty list of collaborators, you should explicitly specify an empty list:
Projects may specify one or more Jira projects to set up autolinking for in their repository, wherein any Jira ticket that is referred to automatically creates a link to the external Jira instance at ASF.
The following snippet would set up autolinking for the INFRA and AMBARI projects in a repository:
autolink_jira property can be either a single string, or a list of strings, each corresponding to a Jira project on issues.apache.org. It MUST adhere to the Jira project name syntax (uppercase alphabetical characters only).
We will evaluate the need for other autolink features in the near future.
GitHub Discussions is currently a beta feature and does not have an API endpoint. Until this is addressed, please open an Infra Jira ticket with a link to a consensus discussion thread for your project.
It is possible for a project to customize the subject lines for GitHub events (issues and pull requests being opened, closed, and commented on) on a per-repository basis.
Customizing the subject line can be done either for individual events, or for all events (by using the
catchall directive), and follows the Python f-string format:
The format follows a dictionary/hash with an event type and a subject line template.
The following event types are currently supported:
close_issue: Someone closes an issue
close_pr: Someone closes a pull request
comment_issue: Someone comments on an issue
comment_pr: Someone comments on a pull request
diffcomment: Someone comments on a segment of code in a pull request
merge_pr: Someone merges a pull request
new_issue: Someone has created a new issue
new_pr: Someone has created a new pull request
catchall: If custom subjects are enabled for this repository, but no specific subject line template is defined for that event type, this will be used if present. If there is no catchall, and the event type does not have a template, the ASF default subject line will be used instead.
The subject line templates support the use of the following variables:
repository: The repository the event is for
user: The GitHub user that triggered this event by creating, commenting on, merging or closing the issue/pr
category: The category of this issue/pr. Will be either "issue" or "pr", respectively
issue_id: The ID of this issue (same as pr_id, as GitHub uses the same internal number pool for both issues and pull requests)
pr_id: The ID of this pull request (same as issue_id)
link: The URL to this specific issue/pr or the specific comment on it
title: The title of the pull request or issue
Note: The repository variable MUST be present in the subject line at all times. Only the variables above are supported, custom variables or calls will not be supported.
See also https://infra.apache.org/project-site.html which lists more options and examples of website generation.
Projects can build their websites automatically using Jekyll. This solution allows the use of custom plugins. Content generated this way can be staged or pushed directly to production when it is used in conjunction with the
publish configuration options.
You can optionally specify a named output directory as
outputdir. If a value is not specified for this property, it defaults to '
_config.yamlfile. It must stay as is and output the generated files into a
To set up an automatic build, add a
jekyll section to
Projects can automatically build web sites using the Pelican Static Site Generator and 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, add a
pelican section to
The above configuration generates the site using Pelican and pushes only the created output to the asf-site branch. An example web site repository 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 change 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.
The Pelican builder supports a feature called
autobuild. When enabled and assigned a pattern, it builds any branch that matches the pattern, and puts the output in a branch with the same root name but ending in -staging.
As an example, setting autobuild to
site/* would automatically build the branch
site/foo, and put the resulting web site in
site/foo-staging. This can be mixed in with the standard parameters:
The Pelican builder has an optional keyword,
minimum_page_count, which sets a lower limit to the number of pages that must be built for the builder to succeed and stage/publish the result.
This can be used to prevent misconfigured builds from publishing partial or blank web sites. The command expects a positive integer in order to check:
The Pelican builder has an optional keyword:
notify which defines a list to which a status report will be sent upon job completion. If no option is specified, a notification will be sent to firstname.lastname@example.org instead.
You can build and publish your website at the same time by employing both the
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.
These features have not been implemented in production yet, but are documented here for future use.