How to Use GitLab Issue Boards API to Manage Workflow in PHP

Integrate GitLab API in Your PHP Project

• Install GuzzleHTTP via Composer, which is a PHP HTTP client. It will help us make requests to the GitLab API.

composer require guzzlehttp/guzzle

• Create a new file in your project where we will manage GitLab Issue Boards, for example, `gitlab_issues.php`.

Set Up API Authentication

• Acquire a GitLab personal access token. This can be done from your GitLab account settings under "Access Tokens."
• Store this token in a secure environment variable to protect your credentials.

$token = getenv('GITLAB_ACCESS_TOKEN');
$projectId = 'your_project_id'; // replace with your project ID

Create a Function to Fetch Issue Boards

• Write a function to retrieve issue boards using the GitLab API endpoint `/projects/:id/boards`. The function will use the GuzzleHTTP client to make a GET request.

use GuzzleHttp\Client;

function getIssueBoards($projectId, $token) {
    $client = new Client();
    $response = $client->get("https://gitlab.com/api/v4/projects/{$projectId}/boards", [
        'headers' => [
            'Authorization' => "Bearer {$token}",
        ],
    ]);

    return json_decode($response->getBody());
}

Display Issue Boards

• Utilize the `getIssueBoards` function to fetch and display the details of available boards for your project.

$boards = getIssueBoards($projectId, $token);
foreach ($boards as $board) {
    echo "Board ID: {$board->id}, Name: {$board->name}\n";
}

Create a New Issue

• Develop a function to create a new issue in your repository using the endpoint `/projects/:id/issues`. This will enhance your workflow by automating issue creation.

function createIssue($projectId, $token, $title, $description) {
    $client = new Client();
    $response = $client->post("https://gitlab.com/api/v4/projects/{$projectId}/issues", [
        'headers' => [
            'Authorization' => "Bearer {$token}",
        ],
        'form_params' => [
            'title' => $title,
            'description' => $description,
        ],
    ]);

    return json_decode($response->getBody());
}

Update Issue Attributes

• Implement a function that updates the attributes of an existing issue. This could be useful for changing the issue status, assignees, or labels.

function updateIssue($projectId, $token, $issueId, $updates) {
    $client = new Client();
    $response = $client->put("https://gitlab.com/api/v4/projects/{$projectId}/issues/{$issueId}", [
        'headers' => [
            'Authorization' => "Bearer {$token}",
        ],
        'form_params' => $updates,
    ]);

    return json_decode($response->getBody());
}

Move Issues Between Lists on a Board

• To manage workflow, write a function to move issues between lists on a board using the endpoint `/projects/:id/boards/:board_id/lists/:list_id/issues/:issue_id/move`.

function moveIssue($projectId, $boardId, $listId, $issueId, $token) {
    $client = new Client();
    $response = $client->put("https://gitlab.com/api/v4/projects/{$projectId}/boards/{$boardId}/lists/{$listId}/issues/{$issueId}/move", [
        'headers' => [
            'Authorization' => "Bearer {$token}",
        ],
        'form_params' => [
            'to_list_id' => $listId,
        ],
    ]);

    return json_decode($response->getBody());
}

• Call this function whenever an issue needs to be moved due to status change or priority adjustment.

Conclusion and Best Practices

• Ensure error handling is implemented for API calls to manage failed requests gracefully.
• Use environment variables or secure vaults to store sensitive information like API tokens.
• Regularly update access tokens to maintain security, and review access scopes.