This project contains tools that make building and maintaining a landscape easier by pulling data from LFX on projects and members.
It is an evolution of the former landscape-tools, with a refactor to add the ability to pull projects from LFX and generate text logos when a pure SVG does not exist. Additional differences include:
- Only leverage LFX data for members and projects; no longer look up in CrunchBase or other landscapes.
- Pull review data from a TAC repo using a specific project format, if used.
- More verbose error messages that improve debugging.
The default configuration for the build is located in the config.yml file, which you should put in the top directory in your landscape repo ( i.e. the same place you would have the landscape.yml file ). All options are defined at lfx_landscape_tools/config.py. See the example below for a simple config.yml file for building a members-only landscape.
# Membership levels; name is the membership level name in LFX; category is the matching subcategory name in the landscape
landscapeMemberClasses:
- name: Steering Membership
category: Steering
- name: General Membership
category: General
# Slug for the project from LFX
slug: alliance-for-open-usd-fund-aousdf
# Category name for members
landscapeMemberCategory: AOUSD MembersGenerally you will want to set this up as a GitHub Action in your landscape repository to automatically keep things updated.
There are three options to pick from.
You can create a GitHub App for your organization, with the permissions as listed below.
- Organizations / Projects - Read-only
- Repository / Contents - Read & Write
- Repository / Pull requests - Read & Write
- Repository / Metadata - Read-only
Generate a Private Key and go to your repository where the workflow runs, and under Settings > Secrets and Variables > Actions set:
- Variable
APP_CLIENT_ID: Found on your App's "General" page under "Client ID". - Secret
APP_PRIVATE_KEY: Open the .pem file you downloaded and paste the entire content (including the-----BEGIN RSA PRIVATE KEY-----lines).
Add a repository secret for PAT, which is a GitHub Personal Authorization Token set for the read:org, read:project, and repo scope.
As a fallback, you can use the built in GITHUB_TOKEN. You have to review the permissions for the GITHUB_TOKEN for your repository ( more details here ). Note that you need to ensure GITHUB_TOKEN has the permission to merge PRs (more here).
Note
If project_processing is set to skip or rebuild and config.yml option tacAgendaProjectUrl is set, you cannot use GITHUB_TOKEN; you must use a GitHub App or Personal Access Token (PAT).
Add the one of the following blocks of code to a build.yml file in your landscape repo's .github/workflows/ directory, depending upon whether you are using a GitHub App or a Token. Once done, run the Build Landscape from LFX GitHub Action following the instructions for manually running a GitHub Action to test that it all works.
name: Build Landscape from LFX
on:
workflow_dispatch:
schedule:
- cron: "0 4 * * *"
permissions: {}
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
jobs:
build:
runs-on: ubuntu-latest
permissions:
contents: write
pull-requests: write
steps:
- uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
id: app-token
with:
client-id: ${{ vars.APP_CLIENT_ID }}
private-key: ${{ secrets.APP_PRIVATE_KEY }}
- uses: jmertic/lfx-landscape-tools@b85674b10bfb017500b51b06d9ec5dad3cb55655 # 20260928
with:
project_processing: skip # see options in action.yml
env:
repository: ${{ github.repository }}
ref: ${{ github.ref }}
token: ${{ steps.app-token.outputs.token }} If you are using a Personal Access Token (PAT), substitute secrets.GITHUB_TOKEN below with the secret name you are using ( i.e secrets.PAT ).
name: Build Landscape from LFX
on:
workflow_dispatch:
schedule:
- cron: "0 4 * * *"
permissions: {}
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
jobs:
build:
runs-on: ubuntu-latest
permissions:
contents: write
pull-requests: write
steps:
- uses: jmertic/lfx-landscape-tools@b85674b10bfb017500b51b06d9ec5dad3cb55655 # 20260928
with:
project_processing: skip # see options in action.yml
env:
repository: ${{ github.repository }}
ref: ${{ github.ref }}
token: ${{ secrets.GITHUB_TOKEN }}Add the following code to a validate.yml file in your landscape repo's .github/workflows/ directory.
name: Validate Landscape
on:
merge_group:
pull_request:
branches:
- main
- master
permissions: {}
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
jobs:
validate-landscape:
runs-on: ubuntu-latest
name: "Validate landscape.yml file"
permissions:
contents: read
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: cncf/landscape2-validate-action@6381e8747c73412e638670807b402ef2b863e9f8 # v2.0.1
with:
target_kind: data
target_path: ./landscape.yml(OPTIONAL BUT HIGHLY RECOMMENDED) Setup dependabot for keeping GitHub Actions updated automatically. Two files to add:
Add the following to a file .github/dependabot.yml.
version: 2
updates:
- package-ecosystem: github-actions
directory: /
schedule:
interval: weekly
groups:
all:
dependency-type: "production"Add the one of the following blocks of code to a file .github/workflows/dependabot-automerge.yml
name: Auto-merge Dependabot PRs
on:
pull_request:
types: [opened, synchronize, reopened]
permissions:
contents: write
pull-requests: write
jobs:
dependabot:
runs-on: ubuntu-latest
if: github.actor == 'dependabot[bot]'
steps:
- uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
id: app-token
with:
client-id: ${{ vars.APP_CLIENT_ID }}
private-key: ${{ secrets.APP_PRIVATE_KEY }}
- name: Checkout
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
token: ${{ steps.app-token.outputs.token }}
ref: ${{ github.head_ref }}
persist-credentials: false
- name: Approve PR
run: |
gh pr review --approve "${{ github.event.pull_request.number }}"
env:
GH_TOKEN: ${{ steps.app-token.outputs.token }}
- name: Enable auto-merge
run: |
gh pr merge \
--squash \
--auto \
"${{ github.event.pull_request.number }}"
env:
GH_TOKEN: ${{ steps.app-token.outputs.token }}If you are using a Personal Access Token (PAT), substitute secrets.GITHUB_TOKEN below with the secret name you are using ( i.e secrets.PAT ).
name: Auto-merge Dependabot PRs
on:
pull_request:
types: [opened, synchronize, reopened]
permissions:
contents: write
pull-requests: write
jobs:
dependabot:
runs-on: ubuntu-latest
if: github.actor == 'dependabot[bot]'
steps:
- name: Checkout
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- name: Approve PR
run: |
gh pr review --approve "${{ github.event.pull_request.number }}"
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- name: Enable auto-merge
run: |
gh pr merge \
--squash \
--auto \
"${{ github.event.pull_request.number }}"
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}If the build results in data that differs from the current data in the landscape, a pull request is created to apply those changes. This pull request is by default set to be automatically merged only if the following conditions are met.
- The target repository must have Allow auto-merge enabled in settings.
- The pull request base must have a branch protection rule with at least one requirement enabled.
- The pull request must be in a state where requirements have not yet been satisfied. If the pull request is in a state where it can already be merged, the action will merge it immediately without enabling auto-merge.
You can install this tool on your local computer via pipx.
pipx install git+https://github.com/jmertic/lfx-landscape-tools.gitSimilarly, you can use the command below to upgrade your local install.
pipx upgrade lfx-landscape-toolsYou can then use the lfx_landscape command to run the various commands. Use lfx_landscape --help for the options.
Feel free to send issues or pull requests ( with a DCO signoff of course :-) ) in accordance with the contribution guidelines