---
title: "Create and manage a new GitLab project"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Create and manage a new GitLab project}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  eval = FALSE
)
```

```{r setup}
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](https://about.gitlab.com/) account, this code can also be run to contribute to 'gitlabr' and set a testing environment (See [CONTRIBUTING.md](https://github.com/ThinkR-open/gitlabr/blob/main/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

```{r}
# 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

```{r}
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.

```{r}
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")
```{r}
gl_list_branches(project = project_info$id)
```

## Open the URL of the project
```{r}
browseURL(project_info$web_url)
```

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

```{r}
# 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"

```{r}
# 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.


```{r}
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
```{r}
# 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

```{r}
# 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!

```{r, eval=FALSE}
gl_delete_project(project_id)
```