How to push Fedora Badges
- Sysadmin process: How to push a Badge
- How to manually award a badge
- How to manually revoke a badge or authorization
- How to add admins to Tahrir
- How to create an invitation and QR code
- Useful scripts for manual work
- Contact information
The badge-awarding back-end daemon, fedbadges, wakes up when it receives a fedmsg event. It compares that message and the history in datanommer against a series of rules. If a contributor matches the criteria described in one of those rules, then they are awarded a badge.
The front-end is a web application called Tahrir. It mostly is just an interface for users to look at their badges. However, it also has an admin interface for manually adding new badges, awarding badges, and creating "invitations" (QR codes) for badges.
The badge-awarding back-end daemon, fedbadges, runs on the
The process is
fedmsg-hub and logs are in
The front-end runs under
For a detailed description of how the fedbadges daemon works, see the fedbadges README.
For a diagram of the interacting pieces in the Fedora Badges system, see the fedbadges diagrams.
Sysadmin process: How to push a Badge
Pushing badges consists of two operations:
Push badge assets (
.yaml) to fedora-badges repository
Add badge to badges.fedoraproject.org
Anyone with write permissions to fedora-badges can push badges.
Pull requests can also be used.
Only members of the
sysadmin-badges FAS group and admins of the web interface can add badges.
Badge artists and badge developers should push design assets (
svg art) and rules (
yaml) to the fedora-badges repository.
Preparing to create a badge
Once a badge is approved by the Design Team and has the ready to push tag, they are ready to be pushed. Follow this checklist to push a new badge:
Ensure artwork is approved by Design Team
Ensure name and description of badge are clear
Ensure one of these requirements is met:
Manually awarded badges: What FAS accounts receive permissions to award badge
Awarded via fedmsg rule: YAML file with rules is present
If you are confused or something is missing, comment on the issue and remove the ready to push tag.
Add badge assets to Pagure
Download artwork and rule file (if applicable):
Double-check the artwork is actually the final version from ticket
Open / view both art files to check they are not corrupt (in the past, corrupt images were accidentally pushed)
Give both art and rule files the same name, place into pngs/, svg/, rules/ directories
On request only: Generate a STL file for 3D-printing a badge:
Change directories into
export.sh. This creates a STL file for the badge and moves it to the correct place.
bin/for more info about the script.
Commit all files and push to fedora-badges (or make a PR)
Make sure files have a reasonable name (e.g.
Some types of badges follow a naming convention, like FAS group membership badges (i.e.
fas-badge-name.png) or Koji build badges (i.e.
Follow past precedent where possible.
Later, the file name is used for the file on the front-end server (e.g.
Push assets to back-end server via Ansible
Note: All assets must be in the
master branch of fedora-badges before proceeding.
You must also be a member of
sysadmin-badges in FAS for this to work.
Next, you need to move all assets from the Pagure repository to the back-end server.
This is done via an Ansible playbook from the
Follow these steps to push the assets to production.
Run the playbook:
sudo rbac-playbook manual/push-badges.yml
Enter FAS password and 2FA token
Once finished, ensure badge is now publicly visible (i.e.
Add automatically-awarded badges
Note: Pay close attention when following these steps. It is easy to create a badge, but much harder to edit it later. Double-check information is entered correctly in the YAML file on first go, or else you have to write SQL statements to fix it later.
Automatically awarded badges are created by the YAML rule file. Once the Ansible playbook finishes, the badge is created and placed in the badges index. The only part not created automatically are tags (see Badge metadata below for info about tags). To add new tags, find the badge on badges.fedoraproject.org. If you are logged in as an admin, there is a text field to enter in new tags.
Add manually-awarded badges
Note: Pay close attention when following these steps. It is easy to create a badge, but much harder to edit it later. Double-check information is entered correctly on first go, or else you have to write SQL statements to fix it later.
Once the badge assets are pushed to the back-end, add the badge to the front-end, Tahrir. The front-end is hosted at badges.fedoraproject.org. Follow these steps to add the badge in Tahrir.
Open Admin interface on badges.fedoraproject.org
Go to the Add badge section.
Enter in all information as provided in the badge ticket (see Badge metadata below.)
Double-check all entered information is correct and accurate
Click Create badge to create new badge
The badge is now created. You should be able to find in the badges index.
Manually-awarded badges require authorized users to issue a badge.
You can do this at the bottom of the Admin interface, near Create Authorizations.
Add the person to receive awarding privileges into the Person Email field.
This must be formatted as their fedoraproject.org email address (e.g. FASuser [at] fedoraproject [dot] org).
For badge name, use the slug (or badge name) from the URL of the badge (e.g. for badges.fedoraproject.org/badge/commops-superstar, this is
To add multiple users, repeat this process for each user.
Name: name of the badge – this determines URL of badge, so triple-check for typos
Image: full link to the PNG (e.g.
Description: badge description text (ensure there is no hanging whitespace)
Criteria: link to the issue in fedora-badges
Issuer: keep the default
Tags: comma-delimited list of tags:
Review other similar badges to ensure tags are correct. Some tags are special and function as categories.
Follow past precedent for tags. Avoid creating new tags if at all possible.
Removing tags is not easy. Adding them later is easy.
Close out the ticket
After pushing the badge, do some last checks to make sure the badge pushed correctly. Make sure the page is viewable and double-check that it is categorized correctly in the badges index.
Return to the Pagure issue for the badge. Post a link to the pushed badge. If you granted authorizations, list the FAS usernames you granted authorizations to. After commenting, closing the issue as pushed.
Congratulations, you just pushed your very own Fedora Badge!
How to manually award a badge
To perform this, you must be in the
sysadmin-badges FAS group.
There is a script installed on
It has help options that you can pull up with
It takes a required
--user FAS_USERNAME and a required
--badge BADGE_ID option.
For example, the following invocation would award the "Associate Editor" badge to "ralph":
sudo /usr/local/bin/award-badge --user ralph --badge associate-editor
BADGE_ID for a badge can be found by visiting its page on the web UI.
That badge can be found at
award-badge script and source code is managed by ansible.git.
The source code is in roles/badges/backend/files/award-badge.
Often enough, there is need for a workflow to batch award a badge to a number of people. For instance, the Keepin' Fedora Beautiful badge comes from a member of the Design Team posting a ticket with a list of FAS usernames (i.e. fedora-badges#129).
For cases, like that you can
wget the file with the list of FAS usernames on
badges-backend01 and run something like:
$ for i in $(cat keepingbeautiful-list ) ; do sudo /usr/local/bin/award-badge --user $i --badge keepin-fedora-beautiful-f20; done
How to manually revoke a badge or authorization
You may revoke badge or badge authorizations in a similar fashion to the
You may chain the invocation of the
revoke-authorization script in the same manner as the
sudo /usr/local/bin/revoke-badge --user ralph --badge associate-editor
sudo /usr/local/bin/revoke-authorization --user ralph --badge associate-editor
How to add admins to Tahrir
It would be nice if we could automatically grant admin access in the web interface to members of the
sysadmin-badges FAS group.
We currently do not have this feature and must maintain the list of web UI admins separately.
The configuration file for the badges front-end web app is managed by ansible.git. The source code is in roles/badges/frontend/templates/tahrir.ini.
In that file, find the
It is a comma-separated list of email addresses that, when logged in, should be granted rights to access the admin panels at badges.fedoraproject.org.
To add a new admin, add their
FAS_USERNAME@fedoraproject.org email to that line, commit, and push.
Use Ansible to run the
groups/badges-web.yml playbook to push the config change out to the web front-end nodes.
How to create an invitation and QR code
This is done through the admin panel of the web interface (although we can probably write a script for it to be used on the back-end node).
Invitations / QR codes are typically created for Fedora events. For instance at the Flock 2013 Fedora Contributors conference, we created a badge to award attendees. We followed the procedure below to generate an invitation and a QR code. Next, the QR code was distributed to conference organizers. They added the QR code to the program brochure that each attendee was given. Then, any attendee that scanned the code was redirected on their phone to the badges app, where they were awarded the badge.
Create an invitation
Make sure you are an admin in the web interface and logged into badges.fedoraproject.org
Click the Admin link in the UI
Under the Invitations section, add this information:
Creation Date: Optional. It defaults to the current date.
Expiration Date: Optional, but you probably want to specify one. It defaults to 2 hours from the current time. For instance, at the Flock 2013 conference, we set the expiration date at the end of the conference. Anyone who tried to claim the badge with the QR code after that time would be denied, with the message this invitation is expired.
Badge ID: "ID" of the badge you want to award. See the section above for how to find a badge ID.
Person email: Email of a person in the badges database. In our case, use their Fedora email (e.g.
Now, the user you specified will have a link to the QR code and invite link on their profile page. They can take initiative to distribute and share the badge as they wish.
Useful scripts for manual work
ansible/roles/badges/backend/files/ for the motherload.
These all get deployed to
badges-backend01 where you can login to execute them.
Update the description and the criteria link for a badge. Useful in the event you created it incorrectly, or if feedback from other stakeholders requires us to change something.
Award a badge to a specific user.
Removes a badge from a user to whom it has been awarded erroneously. Remember! If you revoke a badge award from a user, you should also give them the
consolation-prizebadge as a token of apology.
Grant authorization rights on a badge to a privileged user. They can then create invitation links and QR codes for that badge as well as award it directly to other users from the web interface.
Revoke those authorization rights for a user on a given badge.
Fedora Badges community
Award "badges" to Fedora Contributors
Want to help? Learn how to contribute to Fedora Docs ›