In large teams and multi-project organizations, setting up and managing teams and projects can be a tedious and time-consuming errand. To make these tasks easier for our users, we are now providing all the CRUD actions for your teams through Semaphore API v2. This means that if you’re an admin or an owner in an organization, you can now set up teams with users and projects using just a few bash commands.
The new features that are available through Semaphore API v2 are:
- listing and managing teams,
- creating and deleting teams,
- adding and removing teams from a project, and
- managing team members.
Let’s take a closer look at these features, along with some examples on how you can use them.
Managing teams via API v2
We’ll start with a small example to show the best use case for managing teams.
First, we need to find the API credentials that we’ll use as the authentication token on every request. You can find your API credentials at the bottom of your user settings page.
export AUTH_TOKEN=
To learn more about API authentication, read the API v2 authentication guide.
Now that the authorization token is in place, we can proceed to create a new team. You’ll need to start with the organization name since each team must belong to an organization. Permission level determining the actions all members of a team are able to take is also granted when creating a team.
export ORG_USERNAME=
curl -X POST \
-H "Authorization: Token ${AUTH_TOKEN}" \
-d '{ "name" : "Developers Team", "permission" : "edit" }' \
"https://api.semaphoreci.com/v2/orgs/${ORG_USERNAME}/teams"
# Store the returned id in an environment variable
export TEAM_ID=
To learn more about Semaphore permission levels, read Permission levels in an organization.
Managing users in teams
Next, it’s time to add users to the team we’ve just created. To add a user to a team, all you need to know is their username. On Semaphore, all usernames are public, and no confirmation is needed for a user to be added to your team.
curl -X POST \
-H "Authorization: Token ${AUTH_TOKEN}" \
"https://api.semaphoreci.com/v2/teams/${TEAM_ID}/users/"
If you need to add a lot of users at once, with just a little knowledge of bash scripting, you can create a quick script for adding multiple users either to one team, or to different teams. Here’s an example of what this script can look like:
USERNAMES=(john mike peper)
for username in "${USERNAMES[@]}"
do
curl -X POST \
-H "Authorization: Token ${AUTH_TOKEN}" \
"https://api.semaphoreci.com/v2/teams/${TEAM_ID}/users/$username"
done
To check if we’ve added all the users we need to our team, we can list them by requesting:
curl -X GET \
-H "Authorization: Token ${AUTH_TOKEN}" \
"https://api.semaphoreci.com/v2/teams/${TEAM_ID}/users"
Managing projects in teams
Great! We now have the team all set up with users. Next, we need to give them access to a project. To do this, we need to add projects to a team. In order to add a project, we first need to fetch its ID. Let’s first list all projects in our organization to see which one to add to the team.
curl -X GET \
-H "Authorization: Token ${AUTH_TOKEN}" \
"https://api.semaphoreci.com/v2/orgs/${ORG_USERNAME}/projects"
Once we’ve found the projects we want the team to have access to, we can assign them to teams like this:
curl -X POST \
-H "Authorization: Token ${AUTH_TOKEN}" \
"https://api.semaphoreci.com/v2/teams/${TEAM_ID}/projects/"
To check if a team has access to all projects they’re working on, you can list all the projects assigned to the team:
curl -X GET \
-H "Authorization: Token ${AUTH_TOKEN}" \
"https://api.semaphoreci.com/v2/teams/${TEAM_ID}/projects"
You should now be equipped with a faster way to set up and manage an organization. With Semaphore API v2, you now have a better overview of your organization as it grows, and you can easily manage all members of your organization and their projects.
Your feedback is welcome
Keep in mind that we’re still working on improving API v2, so all of your feedback is precious and welcome.
We are also working on command line interface for the API, which should improve the API’s usability and make team management even easier and faster.
Feel free to try managing your users and projects with our new API, and please don’t forget to share your feedback with us by sending us an email or posting a comment below.
Happy building!
At Semaphore, we’re on a mission to make continuous integration fast and easy. If your Rails test suite takes ages to finish, you can automatically parallelize it with Semaphore Boosters and cut its runtime down to just a few minutes. Learn more and schedule a demo.