This document has the goal to help brand new OFBiz committers to set all the things up to start working with OFBiz repositories.
GitHub OFBiz repos and Apache GitBox service
Apache OFBiz has moved the main development from SVN to GitHub and those repository are handled by Apache Service GitBox, which in short provides a way for Apache projects to commit changes into repositories with both GitHub credentials or ASF credentials.
The process explained here is the Apache Account Linking through GitBox, that links the Apache account with a GitHub (personal) account and once fully completed will give the committer read-write access to repositories.
Here's the full list of steps covered:
- Apache personal account configuration;
- Creation of a personal GitHub account;
- Linking personal GitHub account with Apache account;
- Setup GitBox
- Create an access token on GitHub to use to login to the account via https
Apache personal account configuration
The form will have some of the fields already preset, like Username, User ID, Public Name, Forwarding Email Address, Preferred shell, SSH Access. These fields usually should not be changed, while other personal fields can be updated (Forwarding email address, Alias address, Homepage URL,...).
Click on Submit changes... once done with modifications.
GitHub personal account creation
Visit the GitHub site and follow the steps to create a new account.
While creating the account take note of the username chosen.
Enable 2-Factor Authentication (2FA)
The GitHub 2FA is required by GitBox, so this step is mandatory to correctly complete the GitBox setup.
Enabling the 2FA is quite straightforward and GitHub provides a very good documentation for it.
Once done, if we go to Account Security Settings page (Settings → Password and authentication under Access section of the left-side menu) we should see that the 2-Factor Authentication has been setup for the account.
Linking personal GitHub account with Apache account
Now that a GitHub account as been successfully created and secured with 2FA, we should go back to our Apache Account Page, fill in out GitHub username into the field Your GitHub Username and save the changes.
This action will trigger an invitation to join the ASF Organization on GitHub; an invitation email should be send to the email address related to the GitHub account.
It's important to accept this invitation, since to be part of the ASF Organization is required by GitBox setup.
Choose the Apache OFBiz project to be involved in
Accepting the ASF Organization invitation on GitHub will let you be part of the "Apache Committers" group.
To also be invited to be added to "ofbiz committers" group you should choose the OFBiz repositories during the invitation acceptance phase. You would normally choose the following repositories:
You should be notified by email by GitBox that you have been successfully added to both committers groups.
At this point we should have all the necessary to successfully complete the GitBox Setup.
and login with your Apache Account credentials.
Once logged in, a summary page, should be displayed. In this page we can see the GitBox Setup Process Steps and a list of repository we can access.
If all the configuration steps went good we should see the status bar like this
Authenticated with ASF : logged in to Apache Account
Authenticated with GitHub: logged in into your GitHub Account
Member of GitHub Org: invited and accepted to be part of ASF Organization on GitHub
MFA Status verified: Multi-Factor Authentication (2FA) enabled on GitHub
Accounts Linked: Apache Account and GitHub Account successfully linked in GitBox
The overall page should looks like this
Create an Access Token on GitHub
We're almost done .
At this point all our accounts are setup and configured and there is only one thing left to do: we need to create a Personal Access Token on GitHub account, that is required for the login while operating with repositories.
Most of the Git service providers nowdays (like GitHub, BitBucket,...) to improve security, do not support anymore the possibility to authenticate with personal account password over https, while performing operations on online repositories: instead they require a Personal Access Token (PAT), that is a complex string generated by the Git provider, with associated roles and scopes that basically maps and limits the operations you can perform on an online repository with it.
Follow the GitHub documentation to generate a PAT.
Now that we have created our PAT, we can use it as login password along the GitHub username to authenticate and perform operations on OFBiz online repositories!