# Create and manage a new GitLab project

    library(gitlabr)

You can use this code to create all your new projects with a specific template. For instance, you can have a first issue to welcome all collaborators, explain them how your repository works and ask them to answer with a comment. This will make sure all collaborators know how to find issues and how to interact with you.

Given you have a GitLab.com account, this code can also be run to contribute to ‘gitlabr’ and set a testing environment (See CONTRIBUTING.md).

# Set up GitLab connection

- Do not forget to define an environment variable named `GITLAB_COM_TOKEN`
  - You can use `usethis::edit_r_environ()` to open the correct file

    # GitLab con
    set_gitlab_connection(
      gitlab_url = "https://gitlab.com",
      private_token = Sys.getenv("GITLAB_COM_TOKEN")
    )

# Define the project

- Name of the project
- Name of the default branch

    test_project_name <- "testor.main"
    main_branch <- "main"

## Create a project called `testor.main`, owned by the user

Project is initialized with a README file.

    project_info <- gl_new_project(
      name = test_project_name,
      default_branch = main_branch,
      initialize_with_readme = TRUE
    )

## Check created branch (depending on GitLab, main branch may still be “master”)

    gl_list_branches(project = project_info$id)

## Open the URL of the project

    browseURL(project_info$web_url)

## Add/modify and commit the `README.md`

    # Content of the README
    content_md <- paste("
    # testor.main

    Repository to test R package ['gitlabr'](https://github.com/statnmap/gitlabr)
    ")

    # Push file with a commit
    gl_push_file(
      project = project_info$id,
      file_path = "README.md",
      content = content_md,
      commit_message = "Update README",
      branch = main_branch,
      overwrite = TRUE
    )

## Create a new branch named “for-tests”

    # Create the new branch
    gl_create_branch(project = project_info$id, branch = "for-tests", ref = main_branch)

    # List branches to see if it was created
    # Note that branch creation can take a while, wait a little before using `gl_list_branches()`
    # gl_list_branches(project = project_info$id)

## Add and commit a CI file (“.gitlab-ci.yml”)

The “.gitlab-ci.yml” below is a simple example of CI with artifact. If you want a proper CI for your R package or bookdown project, you may want to look at `gitlabr::use_gitlab_ci()` and run it once you cloned your project locally.

    content_ci <- paste("
    testing:
      script: echo 'test 1 2 1 2' > 'test.txt'
      artifacts:
        paths:
          - test.txt
    ")

    gl_push_file(
      project = project_info$id,
      file_path = ".gitlab-ci.yml",
      content = content_ci,
      commit_message = "Add CI to the main branch",
      branch = main_branch,
      overwrite = TRUE
    )

## Use the commit created above and add a follow-up comment

    # Get list of commits in default branch
    commits_in_main <- gl_get_commits(project = project_info$id, ref_name = main_branch)
    # Add a comment to this commmit
    gl_comment_commit(
      project = project_info$id,
      id = commits_in_main$id[1],
      text = "Write a comment"
    )

## Create a first issue (#1) with a follow-up comment

    # Create an issue
    issue_info <- gl_create_issue(
      project = project_info$id,
      title = "Dont close issue 1",
      description = "An example issue to not close for tests"
    )

    # Create a comment to the issue
    gl_comment_issue(
      project = project_info$id,
      id = issue_info$iid,
      text = "A comment on issue to not close"
    )

## Delete project

- Use with caution!

    gl_delete_project(project_id)