|
| 1 | +## Whitelisting Bots |
| 2 | + |
| 3 | +You can allow specific bot users to automatically pass the CLA check. |
| 4 | + |
| 5 | +This can be done on the GitHub organization level by setting the `skip_cla` property on `cla-{stage}-github-orgs` DynamoDB table. |
| 6 | + |
| 7 | +This property is a Map attribute that contains mapping from repository pattern to bot username and email pattern. |
| 8 | + |
| 9 | +Each pattern is a string and can be one of three possible types: |
| 10 | +- `"name"` - exact match for repository name, GitHub username, or email address. |
| 11 | +- `"re:regexp"` - regular expression match for repository name, GitHub username, or email address. |
| 12 | +- `"*"` - matches all. |
| 13 | + |
| 14 | +So the format is like `"repository_pattern": "github_username_pattern;email_pattern"`. |
| 15 | + |
| 16 | +There can be multiple entries under one Github Organization DynamoDB entry. |
| 17 | + |
| 18 | +Example: |
| 19 | +``` |
| 20 | +{ |
| 21 | +(...) |
| 22 | + "organization_name": { |
| 23 | + "S": "linuxfoundation" |
| 24 | + }, |
| 25 | + "skip_cla": { |
| 26 | + "M": { |
| 27 | + "*": { |
| 28 | + "S": "copilot-swe-agent[bot];*" |
| 29 | + }, |
| 30 | + "repo1": { |
| 31 | + "S": "re:vee?rendra;*" |
| 32 | + } |
| 33 | + } |
| 34 | + }, |
| 35 | +(...) |
| 36 | +} |
| 37 | +``` |
| 38 | + |
| 39 | +Algorithm to match pattern is as follows: |
| 40 | +- First we check repository name for exact match. Repository name is without the organization name, so for `https://github.com/linuxfoundation/easycla` it is just `easycla`. If we find an entry in `skip_cla` for `easycla` that entry is used and we stop searching. |
| 41 | +- If no exact match is found, we check for regular expression match. Only keys starting with `re:` are considered. If we find a match, we use that entry and stop searching. |
| 42 | +- If no match is found, we check for `*` entry. If it exists, we use that entry and stop searching. |
| 43 | +- If no match is found, we don't skip CLA check. |
| 44 | +- Now when we have the entry, it is in the following format: `github_username_pattern;email_pattern`. |
| 45 | +- We check both GitHub username and email address against the patterns. Algorith is the same - username and email patterns can be either direct match or `re:regexp` or `*`. |
| 46 | +- If both username and email match the patterns, we skip CLA check. If username or email is not set but the pattern is `*` it means hit. |
| 47 | +- So setting pattern to `username_pattern;*` means that we only check for username match and assume all emails are valid. |
| 48 | +- If we set `repo_pattern` to `*` it means that this configuration applies to all repositories in the organization. If there are also specific repository patterns, they will be checked first. |
| 49 | + |
| 50 | + |
| 51 | +There is a script that allows you to update the `skip_cla` property in the DynamoDB table. It is located in `utils/skip_cla_entry.sh`. You can run it like this: |
| 52 | +- `` MODE=mode ./utils/skip_cla_entry.sh 'org-name' 'repo-pattern' 'github-username-pattern' 'email-pattern' ``. |
| 53 | +- `` MODE=add-key ./utils/skip_cla_entry.sh 'sun-test-org' '*' 'copilot-swe-agent[bot]' '*' ``. |
| 54 | + |
| 55 | +`MODE` can be one of: |
| 56 | +- `put-item`: Overwrites/adds the entire `skip_cla` property. Needs all 4 arguments org, repo, username and email. |
| 57 | +- `add-key`: Adds or updates a key/value inside the `skip_cla` map (preserves other keys). Needs all 4 args. |
| 58 | +- `delete-key`: Removes a key from the `skip_cla` map. Needs 2 arguments: org and repo. |
| 59 | +- `delete-item`: Deletes the entire `skip_cla` item. Needs 1 argument: org. |
| 60 | + |
| 61 | + |
| 62 | +You can also use AWS CLI to update the `skip_cla` property. Here is an example command: |
| 63 | + |
| 64 | +To add a new `skip_cla` entry: |
| 65 | + |
| 66 | +``` |
| 67 | +aws --profile "lfproduct-prod" --region "us-east-1" dynamodb update-item \ |
| 68 | + --table-name "cla-prod-github-orgs" \ |
| 69 | + --key '{"organization_name": {"S": "linuxfoundation"}}' \ |
| 70 | + --update-expression 'SET skip_cla = :val' \ |
| 71 | + --expression-attribute-values '{":val": {"M": {"re:^easycla":{"S":"copilot-swe-agent[bot];*"}}}}' |
| 72 | +``` |
| 73 | + |
| 74 | +To add a new key to an existing `skip_cla` entry (or replace the existing key): |
| 75 | + |
| 76 | +``` |
| 77 | +aws --profile "lfproduct-prod" --region "us-east-1" dynamodb update-item \ |
| 78 | + --table-name "cla-prod-github-orgs" \ |
| 79 | + --key '{"organization_name": {"S": "linuxfoundation"}}' \ |
| 80 | + --update-expression "SET skip_cla.#repo = :val" \ |
| 81 | + --expression-attribute-names '{"#repo": "re:^easycla"}' \ |
| 82 | + --expression-attribute-values '{":val": {"S": "copilot-swe-agent[bot];*"}}' |
| 83 | +``` |
| 84 | + |
| 85 | +To delete a key from an existing `skip_cla` entry: |
| 86 | + |
| 87 | +``` |
| 88 | +aws --profile "lfproduct-prod" --region "us-east-1" dynamodb update-item \ |
| 89 | + --table-name "cla-prod-github-orgs" \ |
| 90 | + --key '{"organization_name": {"S": "linuxfoundation"}}' \ |
| 91 | + --update-expression "REMOVE skip_cla.#repo" \ |
| 92 | + --expression-attribute-names '{"#repo": "re:^easycla"}' |
| 93 | +``` |
| 94 | + |
| 95 | +To delete the entire `skip_cla` entry: |
| 96 | + |
| 97 | +``` |
| 98 | +aws --profile "lfproduct-prod" --region "us-east-1" dynamodb update-item \ |
| 99 | + --table-name "cla-prod-github-orgs" \ |
| 100 | + --key '{"organization_name": {"S": "linuxfoundation"}}' \ |
| 101 | + --update-expression "REMOVE skip_cla" |
| 102 | +``` |
| 103 | + |
| 104 | +To see given organization's entry: `./utils/scan.sh github-orgs organization_name sun-test-org`. |
| 105 | + |
| 106 | +Or using AWS CLI: |
| 107 | + |
| 108 | +``` |
| 109 | +aws --profile "lfproduct-prod" dynamodb scan --table-name "cla-prod-github-orgs" --filter-expression "contains(organization_name,:v)" --expression-attribute-values "{\":v\":{\"S\":\"linuxfoundation\"}}" --max-items 100 | jq -r '.Items' |
| 110 | +``` |
| 111 | + |
0 commit comments