diff --git a/docs/index.rst b/docs/index.rst index 32c130434e4f..f4a7bc4cf449 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -37,6 +37,7 @@ All these exercises are supposed to be run either live in the lecture with insta user/grading user/courses/customizable user/markdown-support + user/integrated-code-lifecycle user/exports user/mobile-applications user/lti diff --git a/docs/user/exercises/programming-repository-access.inc b/docs/user/exercises/programming-repository-access.inc index 45323fced7dd..c4e201d0f4b6 100644 --- a/docs/user/exercises/programming-repository-access.inc +++ b/docs/user/exercises/programming-repository-access.inc @@ -1,3 +1,5 @@ +If you are a student, and want to know how to use the Artemis Version Control for checking out repositories locally, :ref:`checkout this guide.` + The following tables lists the different types of repositories and gives an overview of the access rights different users have. To gain these access rights, a user must assume the indicated role in the course the repository belongs to. diff --git a/docs/user/exercises/programming.rst b/docs/user/exercises/programming.rst index 6f8a8e00782c..61f1731c4dff 100644 --- a/docs/user/exercises/programming.rst +++ b/docs/user/exercises/programming.rst @@ -224,19 +224,5 @@ Each one represents a single test case feedback and should have the format: Integrated Code Lifecycle ------------------------- -The following sections describe programming exercise features that are part of the integrated code lifecycle system. - -Repository View -^^^^^^^^^^^^^^^ - -.. include:: programming-integrated-code-lifecycle-repository-view.inc - -Build Agent View -^^^^^^^^^^^^^^^^ - -.. include:: programming-integrated-code-lifecycle-build-agent-view.inc - -Build Overview View -^^^^^^^^^^^^^^^^^^^ - -.. include:: programming-integrated-code-lifecycle-build-queue-view.inc +The Artemis Integrated Code Lifecycle system allows you to use programming exercises fully integrated within Artemis, without the need of any external tools. +Find more information on it :ref:`here`. diff --git a/docs/user/exercises/programming/build-agent-details.png b/docs/user/exercises/programming/build-agent-details.png deleted file mode 100644 index ae9d8f2561f4..000000000000 Binary files a/docs/user/exercises/programming/build-agent-details.png and /dev/null differ diff --git a/docs/user/exercises/programming/build-agent-summary.png b/docs/user/exercises/programming/build-agent-summary.png deleted file mode 100644 index 414451407f71..000000000000 Binary files a/docs/user/exercises/programming/build-agent-summary.png and /dev/null differ diff --git a/docs/user/exercises/programming/buildQueueCourseManagement.png b/docs/user/exercises/programming/buildQueueCourseManagement.png deleted file mode 100644 index dc16f6dd6a32..000000000000 Binary files a/docs/user/exercises/programming/buildQueueCourseManagement.png and /dev/null differ diff --git a/docs/user/exercises/programming/buildQueueSystemAdministration.png b/docs/user/exercises/programming/buildQueueSystemAdministration.png deleted file mode 100644 index 1a18244e443a..000000000000 Binary files a/docs/user/exercises/programming/buildQueueSystemAdministration.png and /dev/null differ diff --git a/docs/user/exercises/programming/commit-diff-view.png b/docs/user/exercises/programming/commit-diff-view.png deleted file mode 100644 index cfd5cda349cc..000000000000 Binary files a/docs/user/exercises/programming/commit-diff-view.png and /dev/null differ diff --git a/docs/user/exercises/programming/commit-history-view.png b/docs/user/exercises/programming/commit-history-view.png deleted file mode 100644 index ac691c9c3a60..000000000000 Binary files a/docs/user/exercises/programming/commit-history-view.png and /dev/null differ diff --git a/docs/user/exercises/programming/course-management-repositories.png b/docs/user/exercises/programming/course-management-repositories.png deleted file mode 100644 index 47e842da25a5..000000000000 Binary files a/docs/user/exercises/programming/course-management-repositories.png and /dev/null differ diff --git a/docs/user/exercises/programming/current-repository-content-view.png b/docs/user/exercises/programming/current-repository-content-view.png deleted file mode 100644 index 041b6411f6a1..000000000000 Binary files a/docs/user/exercises/programming/current-repository-content-view.png and /dev/null differ diff --git a/docs/user/exercises/programming/finished-build-jobs.png b/docs/user/exercises/programming/finished-build-jobs.png deleted file mode 100644 index 149a7f98819b..000000000000 Binary files a/docs/user/exercises/programming/finished-build-jobs.png and /dev/null differ diff --git a/docs/user/exercises/programming/open-repository-button.png b/docs/user/exercises/programming/open-repository-button.png deleted file mode 100644 index a758454dead7..000000000000 Binary files a/docs/user/exercises/programming/open-repository-button.png and /dev/null differ diff --git a/docs/user/exercises/programming/open-repository-instructor-participations.png b/docs/user/exercises/programming/open-repository-instructor-participations.png deleted file mode 100644 index 03e9e66e3910..000000000000 Binary files a/docs/user/exercises/programming/open-repository-instructor-participations.png and /dev/null differ diff --git a/docs/user/exercises/programming/open-repository-student.png b/docs/user/exercises/programming/open-repository-student.png deleted file mode 100644 index 5685e134d177..000000000000 Binary files a/docs/user/exercises/programming/open-repository-student.png and /dev/null differ diff --git a/docs/user/exercises/programming/queued-build-jobs.png b/docs/user/exercises/programming/queued-build-jobs.png deleted file mode 100644 index eb7165c01436..000000000000 Binary files a/docs/user/exercises/programming/queued-build-jobs.png and /dev/null differ diff --git a/docs/user/exercises/programming/running-build-jobs.png b/docs/user/exercises/programming/running-build-jobs.png deleted file mode 100644 index 08ccfa8856fd..000000000000 Binary files a/docs/user/exercises/programming/running-build-jobs.png and /dev/null differ diff --git a/docs/user/icl/general.rst b/docs/user/icl/general.rst new file mode 100644 index 000000000000..bf0132e6d20e --- /dev/null +++ b/docs/user/icl/general.rst @@ -0,0 +1,12 @@ +.. _icl-general-information: + +General Information +=================== + +Artemis offers the Integrated Code Lifecycle (ICL), a comprehensive feature designed to streamline the development process for programming exercises. +ICL combines version control, secure communication, and continuous integration to provide a seamless experience for students and instructors. +Understanding these components is crucial for effectively using Artemis, especially if you're new to concepts like SSH and Git. The key components of ICL are: + +- :ref:`Local Version Control`: Use the Local Version Control to interact with the repositories of programming exercises. +- :ref:`SSH`: Use SSH to perform Git operations on repositories. +- :ref:`Local Continuous Integration`: Exercise submissions are built and tested by the Local CI system. diff --git a/docs/user/exercises/programming-integrated-code-lifecycle-build-agent-view.inc b/docs/user/icl/local-ci-build-agent-view.inc similarity index 95% rename from docs/user/exercises/programming-integrated-code-lifecycle-build-agent-view.inc rename to docs/user/icl/local-ci-build-agent-view.inc index a59068be8589..b211e879b252 100644 --- a/docs/user/exercises/programming-integrated-code-lifecycle-build-agent-view.inc +++ b/docs/user/icl/local-ci-build-agent-view.inc @@ -5,7 +5,7 @@ The build agent view consists of two parts: the *Build Agent Summary View* and t The **Build Agent Summary View** shows a list of all build agents in the system, along with their status (idle and running), maximum number of concurrent builds, and running builds. The running builds can be canceled individually by clicking the red cancellation button next to the build. An Administrator can also cancel all running builds on a build agent by clicking the '*Cancel All*' button. -.. figure:: programming/build-agent-summary.png +.. figure:: local-ci/build-agent-summary.png :alt: Build Agent Summary View :align: center @@ -20,7 +20,7 @@ the submission time, start time, end time, the duration of the build job, the co The administrator can click on the participation ID to navigate to the participation's submission page. The administrator can also click on the commit hash to navigate to the commits details page and the course ID to navigate to the course management page. -.. figure:: programming/build-agent-details.png +.. figure:: local-ci/build-agent-details.png :alt: Build Agent Details :align: center diff --git a/docs/user/exercises/programming-integrated-code-lifecycle-build-queue-view.inc b/docs/user/icl/local-ci-build-queue-view.inc similarity index 90% rename from docs/user/exercises/programming-integrated-code-lifecycle-build-queue-view.inc rename to docs/user/icl/local-ci-build-queue-view.inc index 2c2470d9561a..7c865758f98c 100644 --- a/docs/user/exercises/programming-integrated-code-lifecycle-build-queue-view.inc +++ b/docs/user/icl/local-ci-build-queue-view.inc @@ -1,7 +1,7 @@ Artemis provides a build overview view that displays all queued, running, and finished build jobs. Access to the system-wide build overview is exclusively available to **Administrators** through the *System Administration* menu. -.. figure:: programming/buildQueueSystemAdministration.png +.. figure:: local-ci/buildQueueSystemAdministration.png :alt: Build Overview System Administration :align: center @@ -10,7 +10,7 @@ exclusively available to **Administrators** through the *System Administration* **Instructors** can access the build overview for a specific course through the *Build Overview* button located in *Course Management*. This view displays only the queued, running, and finished build jobs associated with the selected course. -.. figure:: programming/buildQueueCourseManagement.png +.. figure:: local-ci/buildQueueCourseManagement.png :alt: Build Overview Course Management :align: center @@ -27,7 +27,7 @@ Jobs are dynamically added to and removed from the queue in real-time. Users have the ability to cancel any job in progress. The table provides the following information: -.. figure:: programming/running-build-jobs.png +.. figure:: local-ci/running-build-jobs.png :alt: Running Build Jobs :align: center @@ -43,7 +43,7 @@ Users also have the option to cancel any job that is queued. The table below displays the following information: -.. figure:: programming/queued-build-jobs.png +.. figure:: local-ci/queued-build-jobs.png :alt: Queued Build Jobs :align: center @@ -59,7 +59,7 @@ Instructors can also access build logs with detailed information about the build The table provides the following information: -.. figure:: programming/finished-build-jobs.png +.. figure:: local-ci/finished-build-jobs.png :alt: Finished Build Jobs :align: center diff --git a/docs/user/icl/local-ci/build-agent-details.png b/docs/user/icl/local-ci/build-agent-details.png new file mode 100644 index 000000000000..4b5b8474781a Binary files /dev/null and b/docs/user/icl/local-ci/build-agent-details.png differ diff --git a/docs/user/icl/local-ci/build-agent-summary.png b/docs/user/icl/local-ci/build-agent-summary.png new file mode 100644 index 000000000000..ec11e28a0d1d Binary files /dev/null and b/docs/user/icl/local-ci/build-agent-summary.png differ diff --git a/docs/user/icl/local-ci/buildQueueCourseManagement.png b/docs/user/icl/local-ci/buildQueueCourseManagement.png new file mode 100644 index 000000000000..d4e255f39988 Binary files /dev/null and b/docs/user/icl/local-ci/buildQueueCourseManagement.png differ diff --git a/docs/user/icl/local-ci/buildQueueSystemAdministration.png b/docs/user/icl/local-ci/buildQueueSystemAdministration.png new file mode 100644 index 000000000000..9a857a317ce8 Binary files /dev/null and b/docs/user/icl/local-ci/buildQueueSystemAdministration.png differ diff --git a/docs/user/icl/local-ci/finished-build-jobs.png b/docs/user/icl/local-ci/finished-build-jobs.png new file mode 100644 index 000000000000..eb7b3dda190d Binary files /dev/null and b/docs/user/icl/local-ci/finished-build-jobs.png differ diff --git a/docs/user/icl/local-ci/queued-build-jobs.png b/docs/user/icl/local-ci/queued-build-jobs.png new file mode 100644 index 000000000000..acd382dfe1f8 Binary files /dev/null and b/docs/user/icl/local-ci/queued-build-jobs.png differ diff --git a/docs/user/icl/local-ci/running-build-jobs.png b/docs/user/icl/local-ci/running-build-jobs.png new file mode 100644 index 000000000000..8cc66a2e5c63 Binary files /dev/null and b/docs/user/icl/local-ci/running-build-jobs.png differ diff --git a/docs/user/icl/local-continuous-integration.rst b/docs/user/icl/local-continuous-integration.rst new file mode 100644 index 000000000000..6c3cdd9b8e65 --- /dev/null +++ b/docs/user/icl/local-continuous-integration.rst @@ -0,0 +1,27 @@ +.. _local-ci: + +Continuous Integration +====================== + +Continuous Integration (CI) is a software development practice where developers frequently merge their code changes into a shared repository. Each change is automatically built and tested, which helps to: + +- Detect and address integration issues early +- Ensure code quality and consistency +- Streamline the development process + +Artemis Local CI is our implementation of these CI principles, tailored to support the Artemis learning platform. +It provides tools and views to help users build and test in programming exercises effectively. + +This document will introduce you to the key components of Artemis Local CI: the Build Agent View and the Build Overview View. +These tools will assist you throughout your development workflow on the Artemis platform. + +Build Agent View +^^^^^^^^^^^^^^^^ + +.. include:: local-ci-build-agent-view.inc + + +Build Overview View +^^^^^^^^^^^^^^^^^^^ + +.. include:: local-ci-build-queue-view.inc diff --git a/docs/user/icl/local-vc-authentication.inc b/docs/user/icl/local-vc-authentication.inc new file mode 100644 index 000000000000..6735cd2743df --- /dev/null +++ b/docs/user/icl/local-vc-authentication.inc @@ -0,0 +1,67 @@ +Cloning a repository +^^^^^^^^^^^^^^^^^^^^ + +You can use Sourcetree, git from the terminal, or any client you like to clone your Git repository. +These instructions show you how to clone your repository using Git from the terminal. + +From the exercise view, click the code button to display the Clone dialog. +Copy the clone URL (either the SSH format or the HTTPS, with or without token). +If you are using the SSH protocol, ensure your public key is stored in your Artemis account settings and loaded on the local system to which you are cloning. +From a terminal window, change to the local directory where you want to clone your repository. + +Paste the command you copied from Bitbucket, for example: + +Clone over HTTPS: + +.. code-block:: bash + + git clone https://username@artemis.cit.tum.de/course/documentation-tests.git + + +Clone over HTTPS with access token: + +.. code-block:: bash + + git clone https://username:accessToken@artemis.cit.tum.de/course/documentation-tests.git + + +Clone over SSH: + +.. code-block:: bash + + git clone ssh://git@artemis.cit.tum.de/course/documentation-tests.git + + +If the clone was successful, a new sub-directory appears on your local drive. +This directory has the same name as the repository that you cloned. +The clone contains the files and metadata that Git requires to maintain the changes you make to the source files. + +Choosing between HTTPS and SSH: + +- HTTPS: Easier to set up initially, works through firewalls, but requires entering credentials more frequently. +- SSH: More secure, doesn't require entering passwords for each operation once set up, but initial setup can be more complex. + +Choose HTTPS if you're new to Git or working in an environment with strict firewall rules. +Choose SSH for enhanced security and convenience in long-term development. + +HTTPS access tokens +^^^^^^^^^^^^^^^^^^^ + +Instructors can create HTTP access tokens for repository access in Artemis. +They are created in the account settings and are used in place of passwords for Git over HTTPS. +For every student's exercise, Artemis automatically generates an access token, only associated with the repository of this particular exercise. +You can use these to authenticate to the Artemis Local Version Control. + +Token Creation +"""""""""""""" + +1. Go to Profile > Settings > VCS token. +2. Create a new token + +Using SSH keys to secure Git operations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Artemis provides a simple way for users to connect securely to repositories, using SSH to perform Git operations. +Next is a :ref:`small and basic introduction to SSH`, and if you already know it, :ref:`here is a guide on how to create SSH keys`. +If you already have an SSH key, :ref:`learn how to add it to your Artemis account here`. + diff --git a/docs/user/exercises/programming-integrated-code-lifecycle-repository-view.inc b/docs/user/icl/local-vc-repository-view.inc similarity index 88% rename from docs/user/exercises/programming-integrated-code-lifecycle-repository-view.inc rename to docs/user/icl/local-vc-repository-view.inc index 5273befacd08..aef46936e99a 100644 --- a/docs/user/exercises/programming-integrated-code-lifecycle-repository-view.inc +++ b/docs/user/icl/local-vc-repository-view.inc @@ -3,13 +3,13 @@ These changes are stored in a repository. A repository is a collection of files How to navigate through the repository and view the code is explained in the following sections. This guide is divided into two parts: one for students and one for instructors. It is demonstrated using course programming exercises, but the same principles apply to exams as well. -For Students -"""""""""""" +Access Repositories as a Student +"""""""""""""""""""""""""""""""" As a student, you can use the repository to view your course submissions. To access your submissions, you need to navigate to the exercise, press the '*Code*' button, and click on |open-repository-button|. -.. figure:: programming/open-repository-student.png +.. figure:: local-vc/open-repository-student.png :alt: Opening the repository in the student view :align: center @@ -22,7 +22,7 @@ To the right side of the screen, above the problem statement, you can see the re the '*Code*' button to clone the repository to your local machine and see the full commit history by pressing the '*Open Commit History*' button. Finally, you can download the repository as a ZIP file by pressing the '*Download Repository*' button. -.. figure:: programming/current-repository-content-view.png +.. figure:: local-vc/current-repository-content-view.png :alt: Current Repository Content :align: center @@ -33,7 +33,7 @@ You can see the commit message, the author of the commit, the date of the commit If you created a submission with multiple commits, you can see all of them here but only the last commit has the result of the submission. Lastly, you can also view the code of the commit by pressing on the commit hash. -.. figure:: programming/commit-history-view.png +.. figure:: local-vc/commit-history-view.png :alt: Commit History View :align: center @@ -44,20 +44,20 @@ You can see the changes in the code, the files that have been added, the files t Green color indicates the lines that have been added and red color indicates the lines that have been deleted. You can also see the commit message, the author of the commit, the date of the commit and the commit hash. -.. figure:: programming/commit-diff-view.png +.. figure:: local-vc/commit-diff-view.png :alt: Commit Diff View :align: center Commit Diff View -For Instructors -""""""""""""""" +Access Repositories as an Instructor +"""""""""""""""""""""""""""""""""""" As an instructor, you can use the repository to view the submissions of your students. For this purpose, you need to navigate to the exercise participations page. Here you can see all the students’ participations for the exercise and navigate to the repository of a student by pressing the '*Code*' button and clicking on |open-repository-button|. This will show the repository of the student just like it is shown to the student. -.. figure:: programming/open-repository-instructor-participations.png +.. figure:: local-vc/open-repository-instructor-participations.png :alt: Open Repository Button in Participations Page :align: center @@ -66,11 +66,11 @@ This will show the repository of the student just like it is shown to the studen You can also see the repositories for an exercises **solution**, **template** and **test** repositories on the exercise management page. You can navigate to these repositories by pressing the '*Code*' button and clicking |open-repository-button| as described above. -.. figure:: programming/course-management-repositories.png +.. figure:: local-vc/course-management-repositories.png :alt: Solution, Template and Test Repositories in Exercise Management Page :align: center Solution, Template and Test Repositories in Exercise Management Page -.. |open-repository-button| image:: programming/open-repository-button.png +.. |open-repository-button| image:: local-vc/open-repository-button.png :scale: 50% diff --git a/docs/user/icl/local-vc/commit-diff-view.png b/docs/user/icl/local-vc/commit-diff-view.png new file mode 100644 index 000000000000..19ebb58be3ab Binary files /dev/null and b/docs/user/icl/local-vc/commit-diff-view.png differ diff --git a/docs/user/icl/local-vc/commit-history-view.png b/docs/user/icl/local-vc/commit-history-view.png new file mode 100644 index 000000000000..2dd208d0de16 Binary files /dev/null and b/docs/user/icl/local-vc/commit-history-view.png differ diff --git a/docs/user/icl/local-vc/course-management-repositories.png b/docs/user/icl/local-vc/course-management-repositories.png new file mode 100644 index 000000000000..ab0af10e9103 Binary files /dev/null and b/docs/user/icl/local-vc/course-management-repositories.png differ diff --git a/docs/user/icl/local-vc/current-repository-content-view.png b/docs/user/icl/local-vc/current-repository-content-view.png new file mode 100644 index 000000000000..961e9f17889b Binary files /dev/null and b/docs/user/icl/local-vc/current-repository-content-view.png differ diff --git a/docs/user/icl/local-vc/open-repository-button.png b/docs/user/icl/local-vc/open-repository-button.png new file mode 100644 index 000000000000..b1b4d60873cd Binary files /dev/null and b/docs/user/icl/local-vc/open-repository-button.png differ diff --git a/docs/user/icl/local-vc/open-repository-instructor-participations.png b/docs/user/icl/local-vc/open-repository-instructor-participations.png new file mode 100644 index 000000000000..bf051e6d644d Binary files /dev/null and b/docs/user/icl/local-vc/open-repository-instructor-participations.png differ diff --git a/docs/user/icl/local-vc/open-repository-student.png b/docs/user/icl/local-vc/open-repository-student.png new file mode 100644 index 000000000000..93312d1cab27 Binary files /dev/null and b/docs/user/icl/local-vc/open-repository-student.png differ diff --git a/docs/user/icl/local-vc/open-settings.png b/docs/user/icl/local-vc/open-settings.png new file mode 100644 index 000000000000..84c13407ab74 Binary files /dev/null and b/docs/user/icl/local-vc/open-settings.png differ diff --git a/docs/user/icl/local-vc/ssh-add-public-key.png b/docs/user/icl/local-vc/ssh-add-public-key.png new file mode 100644 index 000000000000..3e4683c09b7e Binary files /dev/null and b/docs/user/icl/local-vc/ssh-add-public-key.png differ diff --git a/docs/user/icl/local-version-control.rst b/docs/user/icl/local-version-control.rst new file mode 100644 index 000000000000..1ca1c1c2c31c --- /dev/null +++ b/docs/user/icl/local-version-control.rst @@ -0,0 +1,16 @@ +.. _local-vc: + +Local Version Control +===================== + +.. contents:: Content of this document + :local: + :depth: 2 + + +Repository View +^^^^^^^^^^^^^^^ + +.. include:: local-vc-repository-view.inc + +.. include:: local-vc-authentication.inc diff --git a/docs/user/icl/ssh-add-key-to-artemis.rst b/docs/user/icl/ssh-add-key-to-artemis.rst new file mode 100644 index 000000000000..0e3425faa501 --- /dev/null +++ b/docs/user/icl/ssh-add-key-to-artemis.rst @@ -0,0 +1,68 @@ +.. _use ssh key: + +Using SSH with Artemis +^^^^^^^^^^^^^^^^^^^^^^ + +.. contents:: Content of this document + :local: + :depth: 1 + +You can use SSH keys to establish a secure connection between your computer and Artemis when you are performing Git operations (pull, clone, push) from your local machine. +Personal keys are linked to your Artemis account, inheriting its permissions and operating under its unique identity. +To use your generated SSH keys with Artemis, you need to add it in the account settings. + + +Add an SSH key to your Artemis account +"""""""""""""""""""""""""""""""""""""" + +**1. Copy your public key** + +On Windows in your command prompt, change directory to your `.ssh` directory, and copy the public key file to your clipboard by running: + +.. code-block:: bash + + cd %userprofile%/.ssh + clip < id_ed25519.pub + +On macOS or Linux simply run the following in a terminal: + +.. _xclip: https://wiki.ubuntuusers.de/xclip/ + +.. code-block:: bash + + pbcopy < ~/.ssh/id_ed25519.pub + +If `pbcopy` isn't working, locate the hidden `.ssh` folder, open the file in a text editor, and copy it to your clipboard. +Note that on Linux, you may need to download and install `xclip`_, then use that, as shown in this code snippet: + +.. code-block:: bash + + sudo apt-get install xclip + xclip -sel clip < ~/.ssh/id_ed25519.pub + +Note that the key's name is not necessarily **id_ed25519.pub**, but can be arbitrary, and depends on how you saved it. + + +**2. Add the key to your Artemis account** + +Open the settings, go to the SSH tab, and select 'New Key'. +Then paste the copied SSH key into the text box. + ++---------------------------------------------------+--------------------------------------------------------------+ +|.. figure:: local-vc/open-settings.png | .. figure:: local-vc/ssh-add-public-key.png | +| :alt: Open account settings | :alt: Add public SSH key to account | +| :align: center | :align: center | +| | | +| Open you Artemis account settings | Add public SSH key to account in account settings | ++---------------------------------------------------+--------------------------------------------------------------+ + +**3. Save the key. You're done!** + +Use SSH to connect to Artemis repositories +"""""""""""""""""""""""""""""""""""""""""" + +After everything is set up, you can go to a programming exercise, and use the SSH clone URL with git to access the repository locally, like this, for example: + +.. code-block:: bash + + git clone ssh://git@artemis.cit.tum.de:7921/git/COURSE/exercise-user_1.git diff --git a/docs/user/icl/ssh-intro.rst b/docs/user/icl/ssh-intro.rst new file mode 100644 index 000000000000..fd41034ebe5d --- /dev/null +++ b/docs/user/icl/ssh-intro.rst @@ -0,0 +1,67 @@ +.. _basic SSH introduction: + +SSH +^^^ + +.. contents:: Content of this document + :local: + :depth: 2 + +Artemis uses SSH as a simple way for users to connect securely to repositories to perform Git operations. + +What is SSH? +"""""""""""" + +.. _SSH (Secure Shell): https://en.wikipedia.org/wiki/Secure_Shell + +`SSH (Secure Shell)`_ is a protocol that allows you to securely connect to another computer over a network. +It’s mostly used by system administrators, developers, and IT professionals to remotely manage servers or computers. +SSH provides a secure and encrypted communication channel between your computer and a remote machine, so any data passed (like passwords or commands) is protected from eavesdropping. +In Artemis you an use SSH to access your repositories with Git. + +Why use SSH? +"""""""""""" + +The main advantage of SSH is security. +When you connect to a remote machine using SSH, all the data exchanged between your computer and the server is encrypted. +This means if someone tries to intercept the communication, they can't read it. It's like sending messages through a locked box that only you and the server can open. + +How does SSH work? +"""""""""""""""""" + +SSH works by using two components: + +- Client: The computer you are using to connect. +- Server: The machine you want to connect to. + +When you want to connect, your SSH client sends a request to the server. +If the connection is successful, you can log in to the server and start working as if you were sitting in front of it. +The connection uses SSH keys for authentication. Although it is also possible to use username and password to connect over SSH, this is discouraged. + +What are SSH Keys? +"""""""""""""""""" + +.. _public-key cryptography: https://en.wikipedia.org/wiki/Public-key_cryptography + + +SSH keys are a more secure alternative to passwords for logging into a server. +They are based on `public-key cryptography`_ and come in pairs: a public key and a private key. + +- Public Key: This key is stored on the server. Think of it like a lock that only you can open. +- Private Key: This key stays on your local machine (never shared!). It’s like the key to that lock. + +When you try to connect to the server, your computer proves it has the private key that matches the server's public key, granting you access. +You can add a personal SSH key to your user account to easily authenticate when performing read operations from your local machine. +An Artemis user can currently add one key to their account. +For instructions on how to add your SSH key to your Artemis account, please refer to :ref:`the relevant documentation`. + +Before you can use SSH keys to secure a connection with Artemis the following must have already been done: + +- SSH is enabled on your university's Artemis instance +- You need an SSH key! See :ref:`Creating SSH keys`. + +.. note:: + + - You can use the same SSH key for multiple repositories or projects. + - An Artemis user can currently only add one key to their account. + - Artemis supports ECDSA, RSA2, and Ed25519 key types. diff --git a/docs/user/icl/ssh-key-creation.rst b/docs/user/icl/ssh-key-creation.rst new file mode 100644 index 000000000000..58e7b01f5a4d --- /dev/null +++ b/docs/user/icl/ssh-key-creation.rst @@ -0,0 +1,161 @@ +.. _create ssh key: + +Creating SSH keys +^^^^^^^^^^^^^^^^^ + +.. contents:: Content of this document + :local: + :depth: 2 + +SSH keys can be used to establish a secure connection with the Artemis Local Version Control, where you are performing Git operations from your local machine. +The SSH key needs to be added to Artemis before you can make use of the key. + +Creating an SSH key on Windows +"""""""""""""""""""""""""""""" + +**1. Check for existing keys** + +You should check for existing SSH keys on your local computer. Open a command prompt, and run: + +.. code-block:: bash + + cd %userprofile%/.ssh + +- If you see "No such file or directory", then there aren't any existing keys: go to step 3. + +- Check to see if you have a key already: + +.. code-block:: bash + + dir id_* + +If there are existing keys, you may want to use those: :ref:`Add your key to Artemis`. + +**2. Back up old SSH keys** + +If you have existing SSH keys, but you don't want to use them when connecting to Bitbucket, you should back those up. +In a command prompt on your local computer, run: + +.. code-block:: bash + + mkdir key_backup + copy * key_backup + +**3. Generate a new SSH key** + +If you don't have an existing SSH key that you wish to use, generate one as follows: +1. Log in to your local computer as an administrator. +2. In a command prompt, run: + +.. _Git (with Git Bash): https://gitforwindows.org/ + + +.. code-block:: bash + + ssh-keygen -t ed25519 -C "your_email@example.com" + +Associating the key with your email address helps you to identify the key later on. +Note that the `ssh-keygen` command is only available if you have already installed `Git (with Git Bash)`_. +You'll see a response similar to this: + +.. code-block:: bash + + C:\Users\artemis>ssh-keygen -t ed25519 -C "your_email@example.com" + Generating public/private ed25519 key pair. + Enter file in which to save the key (/c/Users/artemis/.ssh/id_ed25519): + +3. Just press to accept the default location and file name. If the .ssh directory doesn't exist, the system creates one for you. +4. Enter, and re-enter, a passphrase when prompted. The whole interaction will look similar to this: + +.. code-block:: bash + + C:\Users\artemis>ssh-keygen -t ed25519 -C "your_email@example.com" + Generating public/private ed25519 key pair. + Enter file in which to save the key (/c/Users/artemis/.ssh/id_ed25519): + Created directory '/c/Users/artemis/.ssh'. + Enter passphrase (empty for no passphrase): + Enter same passphrase again: + Your identification has been saved in c/Users/artemis/.ssh/id_ed25519. + Your public key has been saved in c/Users/artemis/.ssh/id_ed25519.pub. + The key fingerprint is: + SHA256:wvaHYeLtY6+DlvV5sFZgDi3abcdefghijklmnopqrstuvw your_email@example.com + +5. You're done and you can now :ref:`add your key to Artemis`. + +Creating an SSH key on Linux & macOS +"""""""""""""""""""""""""""""""""""" + +**1. Check for existing SSH keys** + +You should check for existing SSH keys on your local computer. Open a terminal and run: + +.. code-block:: bash + + cd ~/.ssh + +If you see "No such file or directory, then there aren't any existing keys: go to step 3. +Check to see if you have a key already: + +.. code-block:: bash + + ls id_* + +If there are existing keys, you may want to use those: :ref:`Add your key to Artemis`. + +**2. Back up old SSH keys** + +If you have existing SSH keys, but you don't want to use them when connecting to Bitbucket, you should back those up. +In a command prompt on your local computer, run: + +.. code-block:: bash + + mkdir key_backup + cp * key_backup + +**3. Generate a new SSH key** + +If you don't have an existing SSH key that you wish to use, generate one as follows: + +1. Open a terminal on your local computer and enter the following: + +.. code-block:: bash + + ssh-keygen -t ed25519 -C "your_email@example.com" + +Associating the key with your email address helps you to identify the key later on. You'll see a response similar to this: + +.. code-block:: bash + + artemis@homemac ~ % ssh-keygen -t ed25519 -C artemis@email.com + Generating public/private ed25519 key pair. + Enter file in which to save the key (/Users/artemis/.ssh/id_ed25519): + +2. Just press to accept the default location and file name. If the .ssh directory doesn't exist, the system creates one for you. +3. Enter, and re-enter, a passphrase when prompted. The whole interaction will look similar to this: + +.. code-block:: bash + + artemis@homemac ~ % ssh-keygen -t ed25519 -C artemis@email.com + Generating public/private ed25519 key pair. + Enter file in which to save the key (/Users/artemis/.ssh/id_ed25519): + Enter passphrase (empty for no passphrase): + Enter same passphrase again: + Your identification has been saved in /Users/artemis/.ssh/id_ed25519. + Your public key has been saved in /Users/artemis/.ssh/id_ed25519.pub. + The key fingerprint is: + SHA256:gTVWKbn41z6JgBNu3wYjLC4abcdefghijklmnopqrstuvwxy artemis@email.com + The keys randomart image is: + +--[ED25519 256]--+ + |==+. +o.. | + |.oE. +o.. | + | . ...o | + | .o... | + | oo+S . | + | + ..B = . . | + |.+.+.oo+ * o . | + |o++.o+ . + + | + |B+ o. . . | + +----[SHA256]-----+ + artemis@homemac ~ % + +4. You're done and you can now :ref:`add your key to Artemis`. diff --git a/docs/user/integrated-code-lifecycle.rst b/docs/user/integrated-code-lifecycle.rst new file mode 100644 index 000000000000..9e5ab5231ef0 --- /dev/null +++ b/docs/user/integrated-code-lifecycle.rst @@ -0,0 +1,15 @@ +.. _integrated code lifecycle: + +Integrated Code Lifecycle +========================= + +Artemis' Integrated Code Lifecycle consists of two main components: Local Version Control and Local Continuous Integration. + +.. toctree:: + + icl/general + icl/local-version-control + icl/ssh-intro + icl/ssh-key-creation + icl/ssh-add-key-to-artemis + icl/local-continuous-integration