Info |
---|
These are playbooks for on-call tasks. Feel free to add more! |
...
Set the Account Name to the relevant Institution(2U/edx, OpenCraft, etc.)
The contributor's first and last name
The contributor's GitHub username (case sensitive - it should match what you see on their profile at
https://github.com/<username>
)Ideally, their email address
Locate the field Contributor Covered Under Entity and select it
Locate the Role field and add the
Entity Contributor
role to the user.
...
Grant requests that follow those rules and seem reasonable.
🌅 Creating New Repos in the openedx
org
In most cases if the purpose of the repo is related to the Open edX Project, you should create the repo. If it turns out that the repo should not be a part of the openedx
org, it is a lot easier to move the repo out than it is to move it in. Use your best judgement and ask in Slack or at standup if you’re unsure.
Establish who the maintainer will be before creating the repo. The requester’s first contribution should be to set the maintainer in catalog-info.yml. Ask them to join the #wg-maintenance
Slack channel and give an FYI that a new repository exists and that they are the maintainer of it.
When creating a new repo, you may need to establish some initial access. Don’t add users directly--give teams access to the repo instead.
The following will always be needed:
cla-checker
- write accessopenedx-triage
- triage accesswg-security
- read access (this is managed automatically – nothing for you to do)
Depending on the language and purpose of your repo you may also need to add various additional bot users. You can search for all relevant bot teams by searching “bot-” but an example of Python bots is:
bot-release-pypi
- write accessbot-requirements-python
- write access
Finally, if a repo is meant to only hold issues (that is: only a README, catalog-info, gitignore, and GH workflows; NO code, docs, or assets), then click the gear next to the repo’s description and apply the issues-only
topic. Then, to ensure that all Coding CCs can flexibly work with issues on the repo, grant:
committers
(GitHub group) - write access
🏗 Transferring repositories into openedx
Requesters should have submitted a GitHub Request to us based on the guidance here: https://openedx.atlassian.net/wiki/spaces/COMM/pages/3241640370/tCRIL+Engineering+Team#Transferring-repos-into-openedx . Read that guidance if you haven’t already. Then, follow these steps to handle the request, documenting any decisions you make along the way (& their rationale) in the request issue.
First, determine whether the repository should be moved.
See our interim guidance on which repositories belong in the openedx GitHub organization. Feel free to bring the question to the team if you’re not sure.
If you believe the repository should move, ensure that we legally can move the code.
See the Managing GH Repositories (Axim-internal) page. You are encouraged to reach out to our legal counsel if you have any shred of uncertainty here
Choose a method: Transfer or Fork. We default to Transfer.
Transfer. “Transfer” is a feature that GitHub provides. Its main benefit is that links to the repository’s original location will indefinitely forward to the new location, unless the repo is forked back into the original org. Furthermore, transferring the repository implies that Axim is receiving the entire repository as a code contribution under the contributor’s existing CLA, which has legal ramifications. To execute the transfer, follow these steps:
Ask the requester to confirm the transfer using the wording in /wiki/spaces/NPGA/pages/3544940606 . Note the requester must be a principal (or higher) engineer or a manager, or have one of those people comment their approval on the request.
Ask the requester to add you to the repository with admin permissions. If you are not in the source organization (you’re probably not), they can still add you to the repository an outside collaborator. They should not need to grant you any permissions in the source organization as a whole. One you’re granted repository admin permissions, go to the repository’s Settings page, scroll all the way down to the Danger Zone, hit “Transfer”, and follow the prompts.
If the requester wasn’t comfortable granting you admin rights to the repo for some reason, then we can do it the hard way:
Get on a screenshare with the requester (they must have admin rights on the repo being transferred). Particularly, they must share their screen looking at the GitHub page of the repo.
Grant them Owner rights (from https://github.com/orgs/openedx/people , find their username. Click, then use the dropdown on the right sidebar to switch from Member to Owner)
Observe them press the transfer button
Determine which teams need access to the repo and add those teams in the next screen
Press Transfer. After a minute or two, verify that the transfer is complete
Demote them to Member (from https://github.com/orgs/openedx/people , find their username. Click, then use the dropdown on the right sidebar to switch from Owner to Member)
Fork. The benefit here is that it can be done without the involvement of anyone in the source organization. Legally, we claim fewer rights using this method; as such, we are able to use it in situations where transferring wouldn’t be appropriate. Steps:
First, check with the team and/or legal. We don’t use this method much, so if you’re doing it, you should probably check that these steps are still valid.
Fork the repository into the openedx organization.
Update any links in the repository to point to the new openedx location.
If it’s not there already, add a Apache 2 or AGPLv3 license file to the repo.
Add a note to the README stating that any contributions up to <version> are licensed by <original owner> under <original license>, and that any after <version> are licensed by Axim under <AGPL or Apache>. Example: https://github.com/openedx/django-require/#license
Tag the latest commit.
Before new changes are merged to the repo, tag the commit that was the last commit in the old org. The tag should follow a naming convention like this:
Code Block last-commit-in-<orgname>-org # Some examples would be last-commit-in-edx-org last-commit-in-opencraft-org
Methods of transferring
Transfer. Based on https://docs.github.com/en/repositories/creating-and-managing-repositories/transferring-a-repository#transferring-a-repository-owned-by-your-organization
Ask the requester to confirm the transfer using the wording in /wiki/spaces/NPGA/pages/3544940606 . Note the requester must be a principal eng or a manager, or have one of those people comment their approval on the request.
Someone must have Owner rights to both the source org (or simply the source repo) and the dest org in order to do the transfer. In order to do this transfer, follow the following steps to grant the requester (or someone with admin rights to the repo) temporary Owner rights on the openedx GitHub organization:
The main benefit here is that links to the repository’s original location will indefinitely forward to the new location, unless the repo is forked back into the original org.
Fork. You only need write access to the destination organization in order to do this.
User access (for transfers into openedx organization)
By precedent, if an organization contributes a repository into the openedx organization, we will nominate the original developers to become Core Contributors with admin or write access to the transferred repository. This is not a hard-and-fast rule, but it is often warranted, since it means that the developers have demonstrated their willingness and ability to contribute quality code to the project.
We have not been giving edX/2U blanket write access (via the push-pull-all group) for new repositories. See the public memo we released concerning this. There may be scenarios in which we do want to give them blanket write access (e.g., something’s coming in from the edx org); talk to the team in any of these scenarios and document the decision in the GitHub request.
Finally, you will need to grant access to a few teams and/or bots, as outlined in the “Creating New Repos in the openedx
org” section.
✏️ Renaming a repository
Verify the maintainers of the repository agree with the rename request
If the repo is long-established with a lot of cross-repo references, there may be more people that need to be notified/contacted
//todo: figure out what that process looks like
🌇 Archiving a repository
First, make sure that the archival request is following the requirements of. OEP-14: Archiving GitHub Repositories.
If it is, archive the repo:
repo settings
scroll down to the DANGER ZONE
click “Archive this repository”
Then move the repo to openedx-unsupported org:
repo settings
scroll down to DANGER ZONE
transfer ownership
(You will also need write access in the openedx-unsupported org to do this. Ask someone from the team if you’re missing them.)
🐍 Adding codecov to a repository
See Adding Codecov
➡️ Adding DNS for a new CNAME record
See https://github.com/openedx/terraform-internal/pull/11
🧹 Removing old DNS records
See https://github.com/openedx/terraform-internal/pull/12
📦 Helping with the community release
The Build-Test-Release Working Group’s Release Manager will reach out to on-call from time to time with release-related requests. This is necessary because the Release Manager is not an openedx GitHub organization owner, yet they still need to create tags in, push branches to, and merge PRs to various openedx repositories. We can smooth this out by temporarily granting the Release Manager permission and/or merging PRs on their behalf.
The release process, and the ways on-call will need to help, are documented here: https://openedx.atlassian.net/wiki/spaces/COMM/pages/19662426/Process+to+Create+an+Open+edX+Release#Grant-the-release-manager-permissions
✏️ Inviting users to have write access in Confluence
To help fight spam we’ve restricted access to self-create accounts to some email domains, which can be found here: https://admin.atlassian.com/o/3989578f-a3e1-472d-a535-be32ae4fdd81/user-access-settings
Requests to add users should come through the support form to on-call. The user(s) can be invited here, presuming they don’t seem to be spammers: https://admin.atlassian.com/o/3989578f-a3e1-472d-a535-be32ae4fdd81/users?status=ACTIVE
New users can be added to the confluence-users
group unless other access is requested.
🌱 Debugging CLA Check Failures
Check to see if the github username is in the salesforce-export.csv file.
Yes → Re-run the check by updating the PR Title.
No → Go to https://tcril.my.salesforce.com
Search for the github username and see if a contact exists.
Yes → Check to see if the the
Open edX Indinidual CLA
orContributor Covered Under Entity
checkboxes are checked.Note: You should not check the boxes yourself unless you are absolutely certain that there is a contract associated with the individual or entity in salesforce.
One or both boxes are checked → The CLA has been processed but the data hasn’t been exported to github yet. It should be within the next 24hrs. You can provide this information publicly.
Neither box is checked → The CLA has not yet been processed by our legal team but should be within the next few days. You can provide this information publicly.
No → Is there a backlog of unmerged PRs to the salesforce-export.csv?
Yes → Investigate, and potentially re-run the tests.
No → There may be an issue in Zapier, escalate to Ed or Feanil
🐕🦺 Causing the CLA report to generate a new PR off schedule
Sometimes there’s a data issue with the file that is used for our CLA check and you don’t want to wait for the next afternoon run for the fix to get merged into check file in GitHub. If that’s the case, you can run the report from Salesforce manually and push it to Zapier via an email hook.
Log in to Salesforce and navigate to the reports tab.
In the left-hand menu, select “All Reports.”
Find and open “Contributor Report.”
Click the caret on the right-hand side and select “Export.”
Select “Details Only,” then .csv, and the Unicode (UTF-8) encoding.
Click “Export”
Email the report to z70p9d2z@robot.zapier.com as an attachement.
Assuming that all is well the PR should be opened here shortly and auto-merged.
🎟️ Adding a new Github App to the openedx
Org
Collect the following things:
App terms of service.
Annual App cost if any.
Who would pay for it? Us? A community member?
Is the app something that more than one community member could benefit from, even if only one is interested right now? e.g., 2U wants an alerting system for a repo, nobody else cares but if someone DID care, they could participate in the app?
Links to App entry in the GitHub Market Place
Which repos will the app be enabled on?
All repos, specific repos, only public repos, etc.
What permissions does the app seek for the org and repos it has access to?
This may be difficult to figure out without trying to install the app on a test organization. The info is not clearly stated on the app marketplace page for most apps.
Send this info to
vendors at Axim org
to do a vendor review.Legal Approves → Install the app and enable it on the relevant repositories.
👁️🗨️ Enabling a slack channel to get posts from Discourse
Add the channel to the discourse Plugin
In Slack, go to the Discourse App
Click on the name “Discourse Chat Integration” to get to the settings modal.
Use the “Add this app to a channel” button to add the app to a slack channel.
As a discourse admin, go to: https://discuss.openedx.org/admin/plugins/chat-integration/slack
Add any rules for the relevant channel
Discourse’s docs for this: https://meta.discourse.org/t/discourse-chat-integration/66522#configuring-rules-4
☁️ Managing access to Axim Cloudflare
Edward Zarecor handles this, just forward the request to him.
🐙 Managing access to Salesforce for Axim Staff
You may not have the bit required to do this. Both Google Workspace and Salesforce admin rights are required. If you have a request, but not the access, please let Edward Zarecor know.
In Salesforce click the gear icon in the top right of the page and select setup.
From the right-hand menu select Administration > Users > Users
Click the “new user” link.
Add the users first name, last name, and canonical email, [first initial][last name]@axim.org, other required fields will be updated automatically
For the Role, User License, and Profile fields select: Axim Internal User, Salesforce, Standard User, or possibly System Administrator upon request.
Set user users “federation id” to be their canonical email address as above.
Save the record.
In Google Workspaces admin, https://admin.google.com, add the users to the “Salesforce Users Group.”
🎛️ Managing AWS, Cloudflare, and Terraform
We manage our AWS account via Terraform at https://github.com/openedx/terraform-internal/ . At the moment, both AWS and Cloudflare access are required to plan & run that Terraform.
Some of us at Axim have AWS & Cloudlare access, others don’t. If you’re on-call and need to run Terraform, reach out to the team chat, and either we will get you set up to run Terrarform, or run it for you. Feanil Patel is the most knowledgeable here; if unsure, ping him.
How to give yourself AWS access:
Make a terraform-internal PR. Here’s a template.
Have your manager give a thumbs-up on the PR to confirm that the access is warranted.
📖 Add a Repository’s Docs to http://docs.openedx.org
We want to publish the documentation for all repos under the docs.openedx.org domain. We do this using readthedocs.org. Each repo has its on documentation project but they are all made subrojects of the docs.openedx.org
project. There is a openedx-rtd-maintainer
user that has acess to the openedx
org and can setup publishing via RTD.
Go to readthedocs.org and login as the
openedx-rtd-maintaner
Go to the Dashboard
Click Import a Project.
Click
openedx
to filter to justopenedx
repositories.Find the relevant repository and click the “Plus” button. (If you can’t find the project, you may need to add the repo to openedx-rtd-bot GitHub team with
write
access to the repo (needed to put status on PRs about docs PR builds)Click through the addition wizard.
Go to
Admin
→Advancd Settings
and check theBuild pull requests for this project
checkbox and hitSave
at the bottom.Go to the
Admin
→Integrations
→GitHub incoming webhook
and copy the webhook URL.Go to the repository’s
Settings
→Webhooks
page and clickAdd webhook
Paste the RTD URL from above into the
Payload URL
Field.Under
Which events would you like to trigger this webhook?
SelectLet me select individual events
and choose the following.Branch or tag creation
Branch or tag deletion
Pull requests
Pushes
Click
Add Webhook
Go to https://readthedocs.org/dashboard/docsopenedxorg/subprojects/
Add the new project as a Subproject of the docs.openedx.org project.
Inform the requester of the URL for the repo docs under docs.openedx.org. Something like: https://docs.openedx.org/projects/xblock-utils/en/latest/
✍️ Make Private Wiki Content Public
If pages are private on the wiki, we need 2U review before we can make them or parts of them public.
Create a ticket on the 2U Open Source Process WG Ticket like this one.
Work with the 2U assigned reviewer.
Get them access to the content by adding them to the space/pages.
Work with them to cleanup the content.
Delete the history of the pages before making the agreed upon pages public.
🎓 Adding Organizations to the Verifiable Credentials Registry
For organization that want to integrate with the LC Wallet application, they will need to be added to a registry that is managed by the Digital Credentials Consortium team. They have asked that Axim manage those requests initially rather than having organizations contact them directly. We are not sure how much interest there will be in this and will adapt depending on what happens.
For now, ping Edward Zarecor on these if you see such a request.
🔐 Share Secrets with 2U SRE
There are ocassions where we need to share credentials with 2U SRE for some of the features in the Open edX community that they support. Some examples include, SMTP creds for github action notifications from the requirements bot and action runners to speed up edx-platform test runs.
Context: We have a folder in keeper that we have shared with 2U SRE (axim-eng-and-2u-sre-shared-secrets-for-openedx-github-org).
Make sure the 2U SRE person you’re working has access to the
axim-eng-and-2u-sre-shared-secrets-for-openedx-github-org
keeper folder.If they don’t have access
Confirm their identity with the manager of 2U SRE and grant their 2U e-mail address access to the folder.
Check to see if a record already exists for the secret they want to share.
If it does
Ask the 2U SRE person to update it with the new value.
If it does not
Create a new record(so we can maintain its permissions)
Ask the 2U SRE person to add the secret to the record.
🤖 Adding required GitHub Actions CI checks to a repository
GitHub actions workflows in any given repository do not need to pass to merge PRs by default. To set a GitHub actions workflow job as required, you should:
Ensure the job has been run in the past week.
This is necessary because workflows that have not been run will not appear in the UI element for adding them as required.
If the requested job has not been run in the past week, you can re-run the CI on any open PR (or dig through the history in the “Actions” tab to re-run the job)
Click on the “Settings” tab for the repo
Click on “Branches” within settings to see “Branch protection rules”
Find the branch you want to add the requirement to and click “Edit”
You will most likely want to edit the default branch
Under “Require status checks to pass before merging” you should see a search box with placeholder text that says “Search for status checks in the last week for this repository”
Use this search box to find the job you want to add as a required check.
Save your changes.
Verify the check is required by looking at any open PR (you should see “Required” next the the check).
🔍 Audit Github Users
Because we are adding users from other organizations to the openedx
github org and sometimes data can get out of sync, we should regularly perform an audit of who has GitHub access and whether they continue to be in the CLA list.
To help perform the audit, we’ve written a new audit_users
script in the repo tools repo.
...
In a python environment run, pip install git+ssh://git@github.com/openedx/repo-tools.git
Export a github token (classic, not fine-grained) into your environment that has read:org
and repo
access.
Code Block |
---|
export GITHUB_TOKEN=ghp_.... |
...
Run the script: audit_users
(no arguments needed). You should get an output of users that don’t have associated entries in our CLA database.
...
You’ll need to investigate why they have access and either remove them from GitHub or add/update their records in salesforce.
Bot Users: You can ignore bot users
Triage-only Access: You can ignore users that only have Triage access (in the Triage group, and any other group that grants Triage or less access, such as the Product Manager group which exists only for @-mentions to work)
Any sort of write access:
Search the axim-engineering repo for their on or offboarding ticket. Perhaps they were on/offboarded incorrectly - fix if so
Otherwise, remove their write access while investigating why they have it. Are they in a 2U group? Reach out to George. Another group? Check in Standup, and/or in GitHub logs to figure out how they got the access and ask that person.
🎨 Enable renovate on a repo
Go to the Open edX org Renovate GitHub app installation page and add the requested repo under “Only select repositories” in “Repository access”
🔏 Adding Secrets to the Openedx Github Org
For each org secret, we want to document how to rotate the secret as well so as a part of the process of adding it, you should also update /wiki/spaces/~feanil/pages/3251372059 with an entry for the new secret you’re adding. If it got accidentally exposed, what steps would we need to take to re-create it?
Go to /wiki/spaces/~feanil/pages/3251372059 and add an entry for how to rotate the new secret.
Go to https://github.com/organizations/openedx/settings/secrets/actions
Add the new secret.
🐱 Managing the On-Call Slack integration
(This is defined as a webhook that posts a msg
payload to the #axim-engineering chat room, and could be added to other GitHub repos to post to our axim-engineering chatroom)
...
Webhook is defined in Slack - to view/manage:
Left sidebar, hover over More
Choose Automation
On-call Ticket Bot should be visible and editable to all eng team members
Defines a json payload with one key,
msg
, that the GH Action posts toHas a “web request URL”, https://hooks.slack.com/triggers/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, defined as
SLACK_WEBHOOK_URL
in our repo secrets
...
Integration code is here: https://github.com/openedx/axim-engineering/blob/main/.github/workflows/add-GHrequest-to-team-board.yml#L57-L67
...
👩🔧 FC Contractor teams and access
For FC projects, contractors may be granted write access at the discretion of Axim.
Add contractor(s) to a new group with a descriptive name prefaced by axim-*
, for example, axim-fc-65-implementation
Oftentimes, contractors are working on new repos. Create a new repo as detailed below. Ensure the Axim lead(s) of the FC project are on the axim-*
team created above, and use that team as (temporary) maintainers. Alternatively, list the Axim lead(s) directly.
🌅 Creating New Repos in the openedx
org
In most cases if the purpose of the repo is related to the Open edX Project, you should create the repo. If it turns out that the repo should not be a part of the openedx
org, it is a lot easier to move the repo out than it is to move it in. Use your best judgement and ask in Slack or at standup if you’re unsure.
👩🔧 Who is maintaining the repo?
Establish who the maintainer will be before creating the repo. The requester’s first contribution should be to set the maintainer in catalog-info.yml
. Ask them to join the #wg-maintenance
Slack channel and give an FYI that a new repository exists and that they are the maintainer of it.
👩💻 Granting Access Rights
When creating a new repo, you may need to establish some initial access. Don’t add users directly--give teams access to the repo instead.
The following will always be needed:
cla-checker
- write accessopenedx-triage
- triage accesswg-security
- read access (this is managed automatically – nothing for you to do)
Depending on the language and purpose of your repo you may also need to add various additional bot users. You can search for all relevant bot teams by searching “bot-” but an example of Python bots is:
bot-release-pypi
- write accessbot-requirements-python
- write access
If a repo is meant to only hold issues (that is: only a README, catalog-info, gitignore, and GH workflows; NO code, docs, or assets), then click the gear next to the repo’s description and apply the issues-only
topic. Then, to ensure that all Coding CCs can flexibly work with issues on the repo, grant:
committers
(GitHub group) - write access
✅ Adding Required Checks
When making a new repo, add required checks (such as commitlint) via https://github.com/openedx/repo-tools/tree/master/edx_repo_tools/repo_checks#usage
🏗 Transferring repositories into openedx
Requesters should have submitted a GitHub Request to us based on the guidance here: https://openedx.atlassian.net/wiki/spaces/COMM/pages/3241640370/tCRIL+Engineering+Team#Transferring-repos-into-openedx . Read that guidance if you haven’t already. Then, follow these steps to handle the request, documenting any decisions you make along the way (& their rationale) in the request issue.
First, determine whether the repository should be moved.
See our interim guidance on which repositories belong in the openedx GitHub organization. Feel free to bring the question to the team if you’re not sure.
If you believe the repository should move, ensure that we legally can move the code.
See the /wiki/spaces/NPGA/pages/3544940606. You are encouraged to reach out to our legal counsel if you have any shred of uncertainty here
Choose a method: Transfer or Fork. We default to Transfer.
Transfer. “Transfer” is a feature that GitHub provides. Its main benefit is that links to the repository’s original location will indefinitely forward to the new location, unless the repo is forked back into the original org. Furthermore, transferring the repository implies that Axim is receiving the entire repository as a code contribution under the contributor’s existing CLA, which has legal ramifications. To execute the transfer, follow these steps:
Ask the requester to confirm the transfer using the wording in /wiki/spaces/NPGA/pages/3544940606 . Note the requester must be a principal (or higher) engineer or a manager, or have one of those people comment their approval on the request.
Ask the requester to add you to the repository with admin permissions. If you are not in the source organization (you’re probably not), they can still add you to the repository an outside collaborator. They should not need to grant you any permissions in the source organization as a whole. One you’re granted repository admin permissions, go to the repository’s Settings page, scroll all the way down to the Danger Zone, hit “Transfer”, and follow the prompts.
If the requester wasn’t comfortable granting you admin rights to the repo for some reason, then we can do it the hard way:
Get on a screenshare with the requester (they must have admin rights on the repo being transferred). Particularly, they must share their screen looking at the GitHub page of the repo.
Grant them Owner rights (from https://github.com/orgs/openedx/people , find their username. Click, then use the dropdown on the right sidebar to switch from Member to Owner)
Observe them press the transfer button
Determine which teams need access to the repo and add those teams in the next screen
Press Transfer. After a minute or two, verify that the transfer is complete
Demote them to Member (from https://github.com/orgs/openedx/people , find their username. Click, then use the dropdown on the right sidebar to switch from Owner to Member)
Fork. The benefit here is that it can be done without the involvement of anyone in the source organization. Legally, we claim fewer rights using this method; as such, we are able to use it in situations where transferring wouldn’t be appropriate. Steps:
First, check with the team and/or legal. We don’t use this method much, so if you’re doing it, you should probably check that these steps are still valid.
Fork the repository into the openedx organization.
Update any links in the repository to point to the new openedx location.
If it’s not there already, add a Apache 2 or AGPLv3 license file to the repo.
Add a note to the README stating that any contributions up to <version> are licensed by <original owner> under <original license>, and that any after <version> are licensed by Axim under <AGPL or Apache>. Example: https://github.com/openedx/django-require/#license
Tag the latest commit.
Before new changes are merged to the repo, tag the commit that was the last commit in the old org. The tag should follow a naming convention like this:
Code Block last-commit-in-<orgname>-org # Some examples would be last-commit-in-edx-org last-commit-in-opencraft-org
Methods of transferring
Transfer. Based on https://docs.github.com/en/repositories/creating-and-managing-repositories/transferring-a-repository#transferring-a-repository-owned-by-your-organization
Ask the requester to confirm the transfer using the wording in /wiki/spaces/NPGA/pages/3544940606 . Note the requester must be a principal eng or a manager, or have one of those people comment their approval on the request.
Someone must have Owner rights to both the source org (or simply the source repo) and the dest org in order to do the transfer. In order to do this transfer, follow the following steps to grant the requester (or someone with admin rights to the repo) temporary Owner rights on the openedx GitHub organization:
The main benefit here is that links to the repository’s original location will indefinitely forward to the new location, unless the repo is forked back into the original org.
Fork. You only need write access to the destination organization in order to do this.
User access (for transfers into openedx organization)
By precedent, if an organization contributes a repository into the openedx organization, we will nominate the original developers to become Core Contributors with admin or write access to the transferred repository. This is not a hard-and-fast rule, but it is often warranted, since it means that the developers have demonstrated their willingness and ability to contribute quality code to the project.
We have not been giving edX/2U blanket write access (via the push-pull-all group) for new repositories. See the public memo we released concerning this. There may be scenarios in which we do want to give them blanket write access (e.g., something’s coming in from the edx org); talk to the team in any of these scenarios and document the decision in the GitHub request.
Finally, you will need to grant access to a few teams and/or bots, as outlined in the “Creating New Repos in the openedx
org” section.
✏️ Renaming a repository
Verify the maintainers of the repository agree with the rename request
If the repo is long-established with a lot of cross-repo references, there may be more people that need to be notified/contacted
//todo: figure out what that process looks like
🌇 Archiving a repository
First, make sure that the archival request is following the requirements of. OEP-14: Archiving GitHub Repositories.
If it is, archive the repo:
repo settings
scroll down to the DANGER ZONE
click “Archive this repository”
Then move the repo to openedx-unsupported org:
repo settings
scroll down to DANGER ZONE
transfer ownership
(You will also need write access in the openedx-unsupported org to do this. Ask someone from the team if you’re missing them.)
🐍 Adding codecov to a repository
See Adding Codecov
➡️ Adding DNS for a new CNAME record
See https://github.com/openedx/terraform-internal/pull/11
🧹 Removing old DNS records
See https://github.com/openedx/terraform-internal/pull/12
📦 Helping with the community release
The Build-Test-Release Working Group’s Release Manager will reach out to on-call from time to time with release-related requests. This is necessary because the Release Manager is not an openedx GitHub organization owner, yet they still need to create tags in, push branches to, and merge PRs to various openedx repositories. We can smooth this out by temporarily granting the Release Manager permission and/or merging PRs on their behalf.
The release process, and the ways on-call will need to help, are documented here: https://openedx.atlassian.net/wiki/spaces/COMM/pages/19662426/Process+to+Create+an+Open+edX+Release#Grant-the-release-manager-permissions
✏️ Inviting users to have write access in Confluence
To help fight spam we’ve restricted access to self-create accounts to some email domains, which can be found here: https://admin.atlassian.com/o/3989578f-a3e1-472d-a535-be32ae4fdd81/user-access-settings
Requests to add users should come through the support form to on-call. The user(s) can be invited here, presuming they don’t seem to be spammers: https://admin.atlassian.com/o/3989578f-a3e1-472d-a535-be32ae4fdd81/users?status=ACTIVE
New users can be added to the confluence-users
group unless other access is requested.
🌱 Debugging CLA Check Failures
Check to see if the github username is in the salesforce-export.csv file.
Yes → Re-run the check by updating the PR Title.
No → Go to https://tcril.my.salesforce.com
Search for the github username and see if a contact exists.
Yes → Check to see if the the
Open edX Indinidual CLA
orContributor Covered Under Entity
checkboxes are checked.Note: You should not check the boxes yourself unless you are absolutely certain that there is a contract associated with the individual or entity in salesforce.
One or both boxes are checked → The CLA has been processed but the data hasn’t been exported to github yet. It should be within the next 24hrs. You can provide this information publicly.
Neither box is checked → The CLA has not yet been processed by our legal team but should be within the next few days. You can provide this information publicly.
No → Is there a backlog of unmerged PRs to the salesforce-export.csv?
Yes → Investigate, and potentially re-run the tests.
No → There may be an issue in Zapier, escalate to Ed or Feanil
🐕🦺 Causing the CLA report to generate a new PR off schedule
Sometimes there’s a data issue with the file that is used for our CLA check and you don’t want to wait for the next afternoon run for the fix to get merged into check file in GitHub. If that’s the case, you can run the report from Salesforce manually and push it to Zapier via an email hook.
Log in to Salesforce and navigate to the reports tab.
In the left-hand menu, select “All Reports.”
Find and open “Contributor Report.”
Click the caret on the right-hand side and select “Export.”
Select “Details Only,” then .csv, and the Unicode (UTF-8) encoding.
Click “Export”
Email the report to z70p9d2z@robot.zapier.com as an attachement.
Assuming that all is well the PR should be opened here shortly and auto-merged.
🎟️ Adding a new Github App to the openedx
Org
Collect the following things:
App terms of service.
Annual App cost if any.
Who would pay for it? Us? A community member?
Is the app something that more than one community member could benefit from, even if only one is interested right now? e.g., 2U wants an alerting system for a repo, nobody else cares but if someone DID care, they could participate in the app?
Links to App entry in the GitHub Market Place
Which repos will the app be enabled on?
All repos, specific repos, only public repos, etc.
What permissions does the app seek for the org and repos it has access to?
This may be difficult to figure out without trying to install the app on a test organization. The info is not clearly stated on the app marketplace page for most apps.
Send this info to
vendors at Axim org
to do a vendor review.Legal Approves → Install the app and enable it on the relevant repositories.
👁️🗨️ Enabling a slack channel to get posts from Discourse
Add the channel to the discourse Plugin
In Slack, go to the Discourse App
Click on the name “Discourse Chat Integration” to get to the settings modal.
Use the “Add this app to a channel” button to add the app to a slack channel.
As a discourse admin, go to: https://discuss.openedx.org/admin/plugins/chat-integration/slack
Add any rules for the relevant channel
Discourse’s docs for this: https://meta.discourse.org/t/discourse-chat-integration/66522#configuring-rules-4
☁️ Managing access to Axim Cloudflare
Edward Zarecor handles this, just forward the request to him.
🐙 Managing access to Salesforce for Axim Staff
You may not have the bit required to do this. Both Google Workspace and Salesforce admin rights are required. If you have a request, but not the access, please let Edward Zarecor know.
In Salesforce click the gear icon in the top right of the page and select setup.
From the right-hand menu select Administration > Users > Users
Click the “new user” link.
Add the users first name, last name, and canonical email, [first initial][last name]@axim.org, other required fields will be updated automatically
For the Role, User License, and Profile fields select: Axim Internal User, Salesforce, Standard User, or possibly System Administrator upon request.
Set user users “federation id” to be their canonical email address as above.
Save the record.
In Google Workspaces admin, https://admin.google.com, add the users to the “Salesforce Users Group.”
🎛️ Managing AWS, Cloudflare, and Terraform
We manage our AWS account via Terraform at https://github.com/openedx/terraform-internal/ . At the moment, both AWS and Cloudflare access are required to plan & run that Terraform.
Some of us at Axim have AWS & Cloudlare access, others don’t. If you’re on-call and need to run Terraform, reach out to the team chat, and either we will get you set up to run Terrarform, or run it for you. Feanil Patel is the most knowledgeable here; if unsure, ping him.
How to give yourself AWS access:
Make a terraform-internal PR. Here’s a template.
Have your manager give a thumbs-up on the PR to confirm that the access is warranted.
📖 Add a Repository’s Docs to http://docs.openedx.org
We want to publish the documentation for all repos under the docs.openedx.org domain. We do this using readthedocs.org. Each repo has its on documentation project but they are all made subrojects of the docs.openedx.org
project. There is a openedx-rtd-maintainer
user that has acess to the openedx
org and can setup publishing via RTD.
Go to readthedocs.org and login as the
openedx-rtd-maintaner
Go to the Dashboard
Click Import a Project.
Click
openedx
to filter to justopenedx
repositories.Find the relevant repository and click the “Plus” button. (If you can’t find the project, you may need to add the repo to openedx-rtd-bot GitHub team with
write
access to the repo (needed to put status on PRs about docs PR builds)Click through the addition wizard.
Go to
Admin
→Advancd Settings
and check theBuild pull requests for this project
checkbox and hitSave
at the bottom.Go to the
Admin
→Integrations
→GitHub incoming webhook
and copy the webhook URL.Go to the repository’s
Settings
→Webhooks
page and clickAdd webhook
Paste the RTD URL from above into the
Payload URL
Field.Under
Which events would you like to trigger this webhook?
SelectLet me select individual events
and choose the following.Branch or tag creation
Branch or tag deletion
Pull requests
Pushes
Click
Add Webhook
Go to https://readthedocs.org/dashboard/docsopenedxorg/subprojects/
Add the new project as a Subproject of the docs.openedx.org project.
Inform the requester of the URL for the repo docs under docs.openedx.org. Something like: https://docs.openedx.org/projects/xblock-utils/en/latest/
✍️ Make Private Wiki Content Public
If pages are private on the wiki, we need 2U review before we can make them or parts of them public.
Create a ticket on the 2U Open Source Process WG Ticket like this one.
Work with the 2U assigned reviewer.
Get them access to the content by adding them to the space/pages.
Work with them to cleanup the content.
Delete the history of the pages before making the agreed upon pages public.
🎓 Adding Organizations to the Verifiable Credentials Registry
For organization that want to integrate with the LC Wallet application, they will need to be added to a registry that is managed by the Digital Credentials Consortium team. They have asked that Axim manage those requests initially rather than having organizations contact them directly. We are not sure how much interest there will be in this and will adapt depending on what happens.
For now, ping Edward Zarecor on these if you see such a request.
🔐 Share Secrets with 2U SRE
There are ocassions where we need to share credentials with 2U SRE for some of the features in the Open edX community that they support. Some examples include, SMTP creds for github action notifications from the requirements bot and action runners to speed up edx-platform test runs.
Context: We have a folder in keeper that we have shared with 2U SRE (axim-eng-and-2u-sre-shared-secrets-for-openedx-github-org).
Make sure the 2U SRE person you’re working has access to the
axim-eng-and-2u-sre-shared-secrets-for-openedx-github-org
keeper folder.If they don’t have access
Confirm their identity with the manager of 2U SRE and grant their 2U e-mail address access to the folder.
Check to see if a record already exists for the secret they want to share.
If it does
Ask the 2U SRE person to update it with the new value.
If it does not
Create a new record(so we can maintain its permissions)
Ask the 2U SRE person to add the secret to the record.
🤖 Adding required GitHub Actions CI checks to a repository
GitHub actions workflows in any given repository do not need to pass to merge PRs by default. To set a GitHub actions workflow job as required, you should:
Ensure the job has been run in the past week.
This is necessary because workflows that have not been run will not appear in the UI element for adding them as required.
If the requested job has not been run in the past week, you can re-run the CI on any open PR (or dig through the history in the “Actions” tab to re-run the job)
Click on the “Settings” tab for the repo
Click on “Branches” within settings to see “Branch protection rules”
Find the branch you want to add the requirement to and click “Edit”
You will most likely want to edit the default branch
Under “Require status checks to pass before merging” you should see a search box with placeholder text that says “Search for status checks in the last week for this repository”
Use this search box to find the job you want to add as a required check.
Save your changes.
Verify the check is required by looking at any open PR (you should see “Required” next the the check).
🔍 Audit Github Users
Because we are adding users from other organizations to the openedx
github org and sometimes data can get out of sync, we should regularly perform an audit of who has GitHub access and whether they continue to be in the CLA list.
To help perform the audit, we’ve written a new audit_users
script in the repo tools repo.
In a python environment run,
pip install git+ssh://git@github.com/openedx/repo-tools.git
Export a github token (classic, not fine-grained) into your environment that has
read:org
andrepo
access.Code Block export GITHUB_TOKEN=ghp_....
Run the script:
audit_users
(no arguments needed). You should get an output of users that don’t have associated entries in our CLA database.You’ll need to investigate why they have access and either remove them from GitHub or add/update their records in salesforce.
Bot Users: You can ignore bot users
Triage-only Access: You can ignore users that only have Triage access (in the Triage group, and any other group that grants Triage or less access, such as the Product Manager group which exists only for @-mentions to work)
Any sort of write access:
Search the axim-engineering repo for their on or offboarding ticket. Perhaps they were on/offboarded incorrectly - fix if so
Otherwise, remove their write access while investigating why they have it. Are they in a 2U group? Reach out to George. Another group? Check in Standup, and/or in GitHub logs to figure out how they got the access and ask that person.
🎨 Enable renovate on a repo
Go to the Open edX org Renovate GitHub app installation page and add the requested repo under “Only select repositories” in “Repository access”
🔏 Adding Secrets to the Openedx Github Org
For each org secret, we want to document how to rotate the secret as well so as a part of the process of adding it, you should also update /wiki/spaces/~feanil/pages/3251372059 with an entry for the new secret you’re adding. If it got accidentally exposed, what steps would we need to take to re-create it?
Go to /wiki/spaces/~feanil/pages/3251372059 and add an entry for how to rotate the new secret.
Go to https://github.com/organizations/openedx/settings/secrets/actions
Add the new secret.
🐱 Managing the On-Call Slack integration
(This is defined as a webhook that posts a msg
payload to the #axim-engineering chat room, and could be added to other GitHub repos to post to our axim-engineering chatroom)
Webhook is defined in Slack - to view/manage, go here, or:
Left sidebar, hover over More
Choose Automation
On-call Ticket Bot should be visible and editable to all eng team members
Defines a json payload with one key,
msg
, that the GH Action posts toHas a “web request URL”, defined as
SLACK_WEBHOOK_URL
in our repo secrets(the webhook URL allows anyone to send a message to our channel via this integration, so don’t paste it anywhere)
Integration code is here: https://github.com/openedx/axim-engineering/blob/main/.github/workflows/add-GHrequest-to-team-board.yml#L57-L67
For more: https://github.com/slackapi/slack-github-action?tab=readme-ov-file
🙊 Handling Unresponsive PR Authors
In the case that a PR author hasn’t signed the CLA but has a really trivial fix, you should first try a few times to get them to sign a CLA. If they are unresponsive, you can close the PR and remake it youself. BE SURE to follow the guidance from legal:
For trivial PRs with unresponsive authors, as a rule of thumb if the change is:
less than 10 lines of code,
mostly deletions, or
the only way to do something, or it is just updated facts
it's okay to close it out and still make the change.
In this case, I can see that we tried a couple times to get the CLA, and that's good practice, too.