Jit Teams sync
By default, Jit uploads GitHub teams and their ownership on GitHub repositories to Jit teams.
Use the sync-teams
scripts as follows:
- If you are not using GitHub for team management, to manually run this command to sync teams data.
- To connect teams (also those originating from GitHub) to external resources like AWS accounts or Web Apps.
## Generating API keys
Before working with the sync-teams script, the following API keys must be created.
- GitHub Personal Access Token (PAT), refer to the Managing your personal access tokens guide to generate.
We recommend generating a fine-grained PAT with read-only access to the organization. - Jit API key, generated from the Jit platform, under Settings > Users and Permissions, go to API Tokens, and create a token with an appropriate name and
member
role. Make sure to copy the values.
Sync teams command
This command has three sub-commands:
Command | Description |
---|---|
install | Ensures Python 3 is installed, sets up a virtual environment and installs the required dependencies. |
configure | Prompts you to input configuration details like the GitHub organization name, API client ID, client secret and GitHub token. The responses are written to an .env file. |
run | Activates the virtual environment and runs two Python scripts in succession to generate teams. |
Usage examples
- Make sure you have installed the prerequisites and cloned the repo.
sudo yum install -y git make git clone https://github.com/jitsecurity/jit-customer-scripts.git cd jit-customer-scripts
sudo apt update sudo apt install -y git make git clone https://github.com/jitsecurity/jit-customer-scripts.git cd jit-customer-scripts
- If you haven't cloned the repo recently, make sure to update it.
git pull https://github.com/jitsecurity/jit-customer-scripts.git
- Run the sub-command
make sync-teams install make sync-teams configure make sync-teams run
Creating teams from GitHub topics
Use the following command to run the script, sync teams and update assets:
To extract the teams from GitHub topics, this command runs the following sub-commands to fetch the repository names and topics from the GitHub API. It then generates the JSON file and syncs between the teams and updates the assets.
python src/utils/github_topics_to_json_file.py
python src/scripts/sync_teams.py teams.json
To automate the process for this script so that your teams are always synchronized, we recommend using the provided GitHub actions and GitHub secrets discussed below or a similar command.
For more information, see Classifying repositories with topics.
Using a custom JSON file as a source for syncing teams
If you prefer using a custom file as a source for syncing your teams, provide a file with the following structure:
{
"teams": [
{
"name": "Team 1",
"members": [
"user1",
"user2"
],
"resources": [
{
"type": "{resource_type}",
"name": "Resource 1"
},
{
"type": "{resource_type}",
"name": "Resource 2"
}
]
},
{
"name": "Team 2",
"members": [
"user3",
"user4"
],
"resources": [
{
"type": "{resource_type}",
"name": "Resource 3"
}
]
}
]
}
Sync the teams by running the following command and replace the path/to/teams.json
with the actual path to your JSON file.
python scripts/sync_teams.py path/to/teams.json
Excluding names
When creating teams, you can exclude team names by either:
- Using the make configure command.
- Updating the env var in the TEAM_WILDCARD_TO_EXCLUDE .env file.
For example, to exclude teams named test
, set the following variable:
TEAM_WILDCARD_TO_EXCLUDE=\_test_
The following topics will be excluded:
- Test
- my-test
- test123
- mytestproject
Sync teams Github action
You can sync teams using a GitHub action. For example, use this workflow file for the GitHub action:
name: Sync Jit Teams
on:
schedule:
- cron: "0 3 * * *"
workflow_dispatch:
jobs:
sync-teams:
runs-on: ubuntu-latest
steps:
- name: Check out code
uses: actions/checkout@v3
- name: Call action
uses: jitsecurity/[email protected]
with:
JIT_CLIENT_ID: ${{ secrets.JIT_CLIENT_ID }}
JIT_CLIENT_SECRET: ${{ secrets.JIT_CLIENT_SECRET }}
ORGANIZATION_NAME: ${{ github.repository_owner }}
GITHUB_API_TOKEN: ${{ secrets.MY_GITHUB_API_TOKEN }}
TEAM_WILDCARD_TO_EXCLUDE: "*dev*, *test*"
Uploading JSON File for Team Structure
This guide explains how to upload a JSON file to manage your team's structure within the Jit platform. By opting to upload a JSON file, the platform will stop syncing teams from GitHub, allowing you to manually define your team's structure.
Importing Your Team Structure
To download an example template, click the "this template" button in the import file dialog.
Steps to Upload a JSON File
Access the Teams Page and Upload JSON File
- Go to the "Teams" page within the Jit platform.
- Click the button labeled "Import Teams From JSON File."
- Select your JSON file containing the team structure.
Processing
After uploading, the platform will process the file. If you had GitHub teams previously, the platform will remove them and create the new teams, members, and resources as specified in the JSON file.
Verification
- Verify the uploaded team structure by navigating to the "Teams" section.
- Ensure all teams, members, and resources are correctly listed.
Important Note
Uploading the JSON file will not remove existing teams, members, and resources. It will only create new teams or update existing ones if new data is provided in the file.
Resource Details
Each resource in your JSON file needs to include a vendor field specifying the source, such as GitHub, AWS, etc. Ensure every resource entry includes this information to avoid processing errors.
Updated 17 days ago