Repository files navigation

This is a GitHub Action that given an organization, team, or specified repositories, opens an issue/PR if dependabot is not enabled, or there are more package ecosystems that could be added. It also enablesautomated security updates for the repository.

This action was developed by the GitHub OSPO for our own use and developed in a way that we could open source it that it might be useful to you as well! If you want to know more about how we use it, reach out in an issue in this repository.

• As a part of the security team for my company, I want to make sure that all of the repositories in the company organizations are regularly updating their dependencies to ensure they are using the most secure version of the dependency available.
• As an OSPO or maintainer, I want to automate everything I can to keep maintaining my project(s) easy and efficient.

If you need support using this project or have questions about it, pleaseopen up an issue in this repository. Requests made directly to GitHub staff or support team will be redirected here to open an issue. GitHub SLA's and support/services contracts do not apply to this repository.

All feedback regarding our GitHub Actions, as a whole, should be communicated throughissues on our github-ospo repository.

1. Create a repository to host this GitHub Action or select an existing repository.

2. Select a best fit workflow file from theexamples below.

3. Copy that example into your repository (from step 1) and into the proper directory for GitHub Actions:.github/workflows/ directory with the file extension.yml (ie..github/workflows/evergreen.yml)

4. Edit the values below from the sample workflow with your information:

   • ORGANIZATION
   • TEAM_NAME
   • REPOSITORY
   • EXEMPT_REPOS
   • TYPE
   • TITLE
   • BODY

   If running on a wholeorganization then no repository is needed.
   If running the action on justone repository or alist of repositories, then no organization is needed.
   If running the action on ateam, then an organization is required and no repository is needed.
   The type should be eitherissue orpull representing the action that you want taken after discovering a repository that should enable dependabot.

5. Optionally, edit the valueCREATED_AFTER_DATE if you are setting up this action to run regularly and only want newly created repositories to be considered.Otherwise, if you want all specified repositories regardless of when they were created to be considered, then leave it blank.

6. Optionally edit the valueUPDATE_EXISTING (default valuefalse) if you want to update existing dependabot configuration files.If set totrue, the action will update the existing dependabot configuration file with any package ecosystems that are detected but not configured yet.If set tofalse, the action will only create a new dependabot configuration file if there is not an existing one.

7. Also edit the value forGH_ENTERPRISE_URL if you are using a GitHub Server and not using github.com.For github.com users, leave it empty.

8. Update the value ofGH_TOKEN. Do this by creating aGitHub API token with the following permissions:

   • If usingclassic tokens:
     • workflow, this will set also all permissions forrepo
     • underadmin,read:org andwrite:org
   • If usingfine grain tokens:
     • Administration - Read and Write (Needed to activate theautomated security updates )
     • Pull Requests - Read and Write (IfTYPE input is set topull)
     • Issues - Read and Write (IfTYPE input is set toissue)
     • Workflows - Read and Write (Needed to create thedependabot.yml file)

   Then take the value of the API token you just created, andcreate a repository secret where the name of the secret isGH_TOKEN and the value of the secret the API token.Then finally update the workflow file to use that repository secret by changingGH_TOKEN: ${{ secrets.GITHUB_TOKEN }} toGH_TOKEN: ${{ secrets.GH_TOKEN }}.The name of the secret can really be anything, it just needs to match between when you create the secret name and when you refer to it in the workflow file.

9. If you want the resulting issue with the output to appear in a different repository other than the one the workflow file runs in, update the linetoken: ${{ secrets.GITHUB_TOKEN }} with your own GitHub API token stored as a repository secret. This process is the same as described in the step above. More info on creating secrets can be found in theGitHub documentation on encrypted secrets.

10. Commit the workflow file to the default branch (oftenmaster ormain)

11. Wait for the action to trigger based on theschedule entry or manually trigger the workflow as shown in thedocumentation.

Below are the allowed configuration options:

This action can be configured to authenticate with GitHub App Installation or Personal Access Token (PAT). If all configuration options are provided, the GitHub App Installation configuration has precedence. You can choose one of the following methods to authenticate:

The needed GitHub app permissions are the following underRepository permissions:

• Administration - Read and Write (Needed to activate theautomated security updates )
• Pull Requests - Read and Write (IfTYPE input is set topull)
• Issues - Read and Write (IfTYPE input is set toissue)
• Workflows - Read and Write (Needed to create thedependabot.yml file)
• Contents - Read and Write (Needed to create a commit)

Dependabot allows the configuration ofprivate registries for dependabot to use.
To add a private registry configuration to the dependabot file theDEPENDABOT_CONFIG_FILE needs to be set with the path of the configuration file.

This configuration file needs to exist on the repository where the action runs. It can also be created locally to test some configurations (if created locally it takes precedence over the file on the repository).

Set the input variable:

DEPENDABOT_CONFIG_FILE = "dependabot-config.yaml"

Create a file on your repository in the same path:

npm:type:"npm"url:"https://yourprivateregistry/npm/"username:"${{secrets.username}}"password:"${{secrets.password}}"key:<used if necessary>token:<used if necessary>replaces-base:<used if necessary>maven:type:"maven"url:"https://yourprivateregistry/maven/"username:"${{secrets.username}}"password:"${{secrets.password}}"

The principal key of each configuration need to match the package managers that thescript is looking for.

Thedependabot.yaml created file will look like the following with theregistries: key added:

updates:  -package-ecosystem:"npm"directory:"/"registries:--> added configuration      -'npm'--> added configurationschedule:interval:"weekly"labels:      -"test"      -"dependabot"      -"new"

---name:Weekly dependabot checkson:workflow_dispatch:schedule:    -cron:"3 2 * * 6"permissions:contents:readjobs:evergreen:name:evergreenruns-on:ubuntu-latestpermissions:issues:writesteps:      -name:Run evergreen actionuses:github/evergreen@v1env:GH_TOKEN:${{ secrets.GITHUB_TOKEN }}ORGANIZATION:<YOUR_ORGANIZATION_GOES_HERE>      -name:Post evergreen job summaryrun:cat summary.md >> $GITHUB_STEP_SUMMARY

---name:Weekly dependabot checkson:workflow_dispatch:schedule:    -cron:"3 2 * * 6"permissions:contents:readjobs:evergreen:name:evergreenruns-on:ubuntu-latestpermissions:issues:writesteps:      -shell:bashrun:|          # Get the current date          current_date=$(date +'%Y-%m-%d')          # Calculate the previous month          previous_date=$(date -d "$current_date -7 day" +'%Y-%m-%d')          echo "$previous_date..$current_date"          echo "one_week_ago=$previous_date" >> "$GITHUB_ENV"      -name:Run evergreen actionuses:github/evergreen@v1env:GH_TOKEN:${{ secrets.GITHUB_TOKEN }}ORGANIZATION:<YOUR_ORGANIZATION_GOES_HERE>EXEMPT_REPOS:"org_name/repo_name_1, org_name/repo_name_2"TITLE:"Add dependabot configuration"BODY:"Please add this dependabot configuration so that we can keep the dependencies in this repo up to date and secure. for help, contact XXX"CREATED_AFTER_DATE:${{ env.one_week_ago }}      -name:Post evergreen job summaryrun:cat summary.md >> $GITHUB_STEP_SUMMARY

---name:Weekly dependabot checkson:workflow_dispatch:schedule:    -cron:"3 2 * * 6"permissions:contents:readjobs:evergreen:name:evergreenruns-on:ubuntu-latestpermissions:issues:writesteps:      -shell:bashrun:|          # Get the current date          current_date=$(date +'%Y-%m-%d')          # Calculate the previous month          previous_date=$(date -d "$current_date -7 day" +'%Y-%m-%d')          echo "$previous_date..$current_date"          echo "one_week_ago=$previous_date" >> "$GITHUB_ENV"      -name:Run evergreen actionuses:github/evergreen@v1env:GH_TOKEN:${{ secrets.GITHUB_TOKEN }}REPOSITORY_SEARCH_QUERY:"org:your_organization is:repository is:public archived:false created:>${{ env.one_week_ago }}"TITLE:"Add dependabot configuration"BODY:"Please add this dependabot configuration so that we can keep the dependencies in this repo up to date and secure. for help, contact XXX"      -name:Post evergreen job summaryrun:cat summary.md >> $GITHUB_STEP_SUMMARY

name:Evergreenon:workflow_dispatch:schedule:    -cron:"3 2 * * 6"permissions:contents:readjobs:evergreen:name:"Create dependabot.yml"runs-on:ubuntu-lateststeps:      -name:Run evergreen action for toolsuses:github/evergreen@v1env:GH_APP_ID:${{ secrets.GH_APP_ID }}GH_APP_INSTALLATION_ID:${{ secrets.GH_APP_INSTALLATION_ID }}GH_APP_PRIVATE_KEY:${{ secrets.GH_APP_PRIVATE_KEY }}# GITHUB_APP_ENTERPRISE_ONLY: True --> Set to true when created GHE App needs to communicate with GHE apiGH_ENTERPRISE_URL:${{ github.server_url }}# GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} --> the token input is not used if the github app inputs are setORGANIZATION:your_organizationUPDATE_EXISTING:TrueGROUP_DEPENDENCIES:True      -name:Post evergreen job summaryrun:cat summary.md >> $GITHUB_STEP_SUMMARY

1. Make sure you have at least Python3.11 installed
2. Copy.env-example to.env
3. Fill out the.env file with atoken from a user that has access to the organization to scan (listed below). Tokens should have at least write:org access for organization scanning and write:repository for repository scanning.
4. Fill out the.env file with the configuration parameters you want to use
5. pip3 install -r requirements.txt
6. Runpython3 ./evergreen.py, which will output everything in the terminal

MIT

Looking for more resources for your open source program office (OSPO)? Check out thegithub-ospo repo for a variety of tools designed to support your needs.